@taurgis/bonsai 3.2.2 → 4.0.0

package/dist/commands/list.js

@@ -4,9 +4,10 @@ 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 } from '../lib/text.js';
+import { NO_TOPIC_LABEL, formatTip, resultListHeading, sanitizeForTerminal, } 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';
 // Listings are ordered newest-first, so the truncation word is "first"; --limit caps at this value.
@@ -14,21 +15,38 @@ 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');
+/** Project a full row down to the default minimal shape (see {@link ListRowMinimal}). */
+function toMinimalListRow(row) {
+    return {
+        sourceUrls: row.sourceUrls,
+        topic: row.topic,
+        freshness: row.freshness,
+        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';
     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.';
+    static description = 'List page-level cached artifacts by source URL, topic, freshness, and token estimate. ' +
+        'Pass --full for every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps).';
     /**
-     * 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).
+     * Aggregate counts (and an explicit empty/truncation signal) attached to the success envelope so
+     * agents get a cache-wide summary without a separate round trip (AXI principles: pre-computed
+     * aggregates, definitive empty states). Always set by `run()` before it returns.
      */
-    jsonTruncation = null;
+    jsonSummary = null;
     static examples = [
         {
             description: 'list cached entries',
@@ -46,6 +64,10 @@ export default class ResearchList extends BaseCommand {
             description: 'list entries matching a URL glob',
             command: '<%= config.bin %> list --url "https://react.dev/*"',
         },
+        {
+            description: 'list every metadata field instead of the minimal default row',
+            command: '<%= config.bin %> list --full --json',
+        },
     ];
     static flags = {
         topic: Flags.string({
@@ -72,25 +94,18 @@ export default class ResearchList extends BaseCommand {
             description: 'capture method',
             options: CAPTURE_METHODS,
         })(),
-        limit: limitFlag(100, 50, 'result count (default 50, max 100)'),
+        limit: limitFlag(LIST_DEFAULT_MAX_LIMIT, 50, `result count (max ${LIST_DEFAULT_MAX_LIMIT})`),
+        full: Flags.boolean({
+            default: false,
+            description: CLI_FLAG_DESCRIPTIONS.listFull,
+        }),
     };
     static stdoutIsPrimaryData = true;
-    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.matchesTopic(meta, this.flags.topic)) {
+        if (!matchesTopicFilter(meta, this.flags.topic)) {
             return false;
         }
-        if (!this.matchesTags(meta, this.flags.tags)) {
+        if (!matchesTagsFilter(meta, this.flags.tags)) {
             return false;
         }
         if (this.flags.url && !artifactMatchesUrlFilter(meta, this.flags.url)) {
@@ -156,7 +171,9 @@ 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(res.topic) : colors.gray(NO_TOPIC_LABEL);
+            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 = {
@@ -171,7 +188,10 @@ export default class ResearchList extends BaseCommand {
             this.log(`   Source URLs: ${colors.gray(res.sourceUrls.join(', '))}\n`);
         });
     }
-    /** Empty-cache / no-match tip (human mode only; --json returns `data: []` with no messaging). */
+    /**
+     * Empty-cache / no-match tip (human mode only). Under `--json`/`--toon`, `data: []` is paired with
+     * `summary.empty: true` instead of prose — see {@link toSuccessJson}.
+     */
     emitEmptyListGuidance() {
         if (this.jsonEnabled())
             return;
@@ -184,12 +204,19 @@ export default class ResearchList extends BaseCommand {
             ? 'try relaxing filters, or list everything: '
             : 'populate the cache first: ';
         this.log(headline);
-        this.log(`\nTip: ${tipLead}${colors.cyan(tipCmd)}`);
+        this.log(`\n${formatTip(`${tipLead}${colors.cyan(tipCmd)}`)}`);
+        // Bare `bonsai` (no args) redirects here (content-first default), so an empty, unfiltered cache
+        // is also the first thing a brand-new user sees — point at --help so command discovery isn't lost.
+        if (!filtered) {
+            this.log(formatTip(`see every command: ${colors.cyan(`${this.config.bin} --help`)}`));
+        }
     }
     async run() {
-        const urlErr = emptyUrlFilterError(this.flags.url);
-        if (urlErr)
-            this.error(urlErr, { exit: 2, code: 'INVALID_FLAG_VALUE' });
+        const flagErr = emptyUrlFilterError(this.flags.url) ??
+            emptyTopicFilterError(this.flags.topic) ??
+            emptyTagsFilterError(this.flags.tags);
+        if (flagErr)
+            this.error(flagErr, { exit: 2, code: 'INVALID_FLAG_VALUE' });
         const roots = loadStoreRoots({
             configDir: this.config.configDir,
             cwd: process.cwd(),
@@ -203,23 +230,24 @@ export default class ResearchList extends BaseCommand {
             return timeB - timeA;
         });
         const finalResults = results.slice(0, this.flags.limit);
-        // 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;
+        // 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,
+            empty: results.length === 0,
+            byFreshness: countByFreshness(results),
+        };
         this.logListResults(finalResults, results.length);
-        return finalResults;
+        return this.flags.full ? finalResults : finalResults.map(toMinimalListRow);
     }
-    /** Attach `truncation` when the returned `data` array was capped by `--limit`. */
+    /** Attach the aggregate `summary` computed in `run()` (see {@link ListSummary}). */
     toSuccessJson(data) {
         const envelope = this.baseSuccessJson(data);
-        if (!this.jsonTruncation)
+        if (!this.jsonSummary)
             return envelope;
-        return { ...envelope, truncation: this.jsonTruncation };
+        return { ...envelope, summary: this.jsonSummary };
     }
 }

package/dist/commands/prune.d.ts

@@ -13,6 +13,8 @@ export default class ResearchPrune extends BaseCommand<typeof ResearchPrune> {
         'older-than': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         inactive: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         url: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        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>;
         'artifact-type': import("@oclif/core/interfaces").OptionFlag<"source" | "research_note" | "index" | "section" | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/prune.js

@@ -7,8 +7,9 @@ import { scanCacheDir } from '../lib/research/storage.js';
 import { loadStoreRoots } from '../lib/research/store-roots.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 { NO_TOPIC_LABEL, pluralize, sanitizeForTerminal } from '../lib/text.js';
 import { artifactMatchesUrlFilter } from '../lib/research/url.js';
+import { matchesTopicFilter, matchesTagsFilter } from '../lib/research/metadata-filters.js';
 import { pruneFlagError } from '../lib/prune-flags.js';
 import { colors } from '../lib/color.js';
 import { CLI_FLAG_DESCRIPTIONS } from '../lib/cli-presentation.js';
@@ -16,7 +17,7 @@ import { CLI_FLAG_DESCRIPTIONS } from '../lib/cli-presentation.js';
 export default class ResearchPrune extends BaseCommand {
     static id = 'prune';
     static summary = 'Prune cached research artifacts';
-    static description = 'Delete cached artifacts by content age, idle time, URL glob, or artifact type.';
+    static description = 'Delete cached artifacts by content age, idle time, URL glob, artifact type, topic, or tags.';
     static examples = [
         {
             description: 'preview pruning entries older than 30 days',
@@ -30,6 +31,10 @@ export default class ResearchPrune extends BaseCommand {
             description: 'prune entries matching a URL glob',
             command: '<%= config.bin %> prune --url "https://react.dev/*" --yes',
         },
+        {
+            description: 'prune entries tagged as deprecated',
+            command: '<%= config.bin %> prune --tags deprecated --yes',
+        },
     ];
     static flags = {
         'older-than': Flags.string({
@@ -41,6 +46,15 @@ export default class ResearchPrune extends BaseCommand {
         url: Flags.string({
             description: CLI_FLAG_DESCRIPTIONS.sourceUrlGlob,
         }),
+        topic: Flags.string({
+            char: 't',
+            description: CLI_FLAG_DESCRIPTIONS.filterTopic,
+        }),
+        tags: Flags.string({
+            char: 'g',
+            description: CLI_FLAG_DESCRIPTIONS.filterTags,
+            multiple: true,
+        }),
         '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
@@ -68,6 +82,8 @@ export default class ResearchPrune extends BaseCommand {
             inactive: this.flags.inactive,
             artifactType: this.flags['artifact-type'],
             url: this.flags.url,
+            topic: this.flags.topic,
+            tags: this.flags.tags,
             dryRun: this.flags['dry-run'],
             yes: this.flags.yes,
             readOnly: this.readOnly,
@@ -83,6 +99,12 @@ export default class ResearchPrune extends BaseCommand {
         if (this.flags.url && !artifactMatchesUrlFilter(meta, this.flags.url)) {
             return false;
         }
+        if (!matchesTopicFilter(meta, this.flags.topic)) {
+            return false;
+        }
+        if (!matchesTagsFilter(meta, this.flags.tags)) {
+            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
@@ -118,7 +140,12 @@ export default class ResearchPrune extends BaseCommand {
                 prunedCount++;
             }
             catch (err) {
-                this.warn(`Failed to delete cache file ${f.path}: ${err.message}`);
+                // A failed unlink still flips the command to exit 1 (see the caller's comment), so it must
+                // render as an Error, not a Warning — this.error's exit:false form prints the same "Error: …"
+                // line and returns instead of throwing, so the remaining candidates still get processed.
+                this.error(`Failed to delete cache file ${f.path}: ${err.message}`, {
+                    exit: false,
+                });
             }
         }
         return prunedCount;
@@ -147,8 +174,12 @@ export default class ResearchPrune extends BaseCommand {
                     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')})`);
+                        const topicStr = f.topic
+                            ? colors.cyan(sanitizeForTerminal(f.topic))
+                            : colors.gray(NO_TOPIC_LABEL);
+                        this.log(`- [${topicStr}] Key: ${colors.bold(f.cacheKey)} (${colors.gray(f.url || 'Imported note')})`);
                     });
+                    this.tip('re-run with --yes to prune these entries.');
                 }
             }
         }

package/dist/commands/status.js

@@ -32,6 +32,10 @@ export default class ResearchStatus extends BaseCommand {
             description: 'evaluate status with a specific tier and TTL',
             command: '<%= config.bin %> <%= command.id %> https://example.com/docs --tier volatile --ttl 2h',
         },
+        {
+            description: 'check multiple URLs in one batch (space-separated)',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs https://example.com/api',
+        },
     ];
     static strict = false;
     static args = {
@@ -83,6 +87,12 @@ export default class ResearchStatus extends BaseCommand {
             if (result.status === 'miss') {
                 this.warn(cacheMissHint(this.config.bin, normalizedUrl));
             }
+            else if (result.action === 'would_revalidate') {
+                this.tip(`${this.config.bin} ${normalizedUrl} to revalidate.`);
+            }
+            else {
+                this.tip(`${this.config.bin} inspect ${normalizedUrl} for full metadata.`);
+            }
         }
         return {
             cacheKey,

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

@@ -1,5 +1,5 @@
 import { type Hook, type Interfaces } from '@oclif/core';
-export declare function buildCommandNotFoundDetails(id: string, argv: string[] | undefined, config: Interfaces.Config): {
+export declare function buildCommandNotFoundDetails(rawId: string, argv: string[] | undefined, config: Interfaces.Config): {
     code: 'COMMAND_NOT_FOUND' | 'MISSING_URL_SCHEME' | 'UNEXPECTED_ARGUMENT';
     command: string;
     jsonMode: boolean;

package/dist/hooks/command-not-found/suggest.js

@@ -1,5 +1,5 @@
 import { toConfiguredId } from '@oclif/core';
-import { closestMatch, maxFuzzyDistance } from '../../lib/text.js';
+import { closestMatch, maxFuzzyDistance, sanitizeForTerminal } from '../../lib/text.js';
 import { writeCommandNotFoundJson } from '../../lib/cli-emit.js';
 import { looksLikeSchemelessUrl } from '../../lib/research/url.js';
 /**
@@ -97,7 +97,17 @@ function missingUrlSchemeDetails(urls, argv, config) {
         suggestions: [suggestion],
     };
 }
-export function buildCommandNotFoundDetails(id, argv, config) {
+export function buildCommandNotFoundDetails(rawId, argv, config) {
+    // The attempted id is raw user input echoed straight back into this error's message and
+    // suggestions — untrusted per the repo's trust-boundary rules, same reasoning as
+    // BaseCommand.error(). Sanitize once, up front, so every derived value below (segments, the
+    // display-only "attempted" string, a bare-URL correction) is already safe; a real command/topic id
+    // never contains control bytes, so this only affects input that could never have matched one
+    // anyway. Gate on jsonMode exactly like BaseCommand.error() does, so `--json` keeps
+    // byte-for-byte fidelity — this hook fires before a Command instance exists, so there's no
+    // `jsonEnabled()` to call, but the same boolean is cheap to compute directly from argv.
+    const jsonMode = isJsonMode(argv);
+    const id = jsonMode ? rawId : sanitizeForTerminal(rawId);
     // Match against every loaded command id — including hidden ones that stay invokable
     // (`fetch`, plugin internals). Root `--help` hides them; typo recovery should not.
     const commandIds = config.commandIDs;

package/dist/lib/argv.d.ts

@@ -16,6 +16,11 @@ export interface NormalizationResult {
 export interface ArgvNormalizeOptions {
     /** Tokens that consume the next argv value (`--topic`, `-t`, …). From cli-flag-manifest. */
     valueTakingFlags: ReadonlySet<string>;
+    /**
+     * Root segment of every registered command id (`config:get` → `config`). From cli-flag-manifest.
+     * A `word:` token whose root is in this set is a command (`config:get`), never a URL scheme.
+     */
+    knownCommandRoots: ReadonlySet<string>;
 }
 /**
  * Normalize raw process argv for oclif. `valueTakingFlags` must come from the composition root

package/dist/lib/argv.js

@@ -1,5 +1,6 @@
 import { EXIT_USAGE } from './cli-error-policy.js';
 import { buildCliErrorEnvelope } from './envelope.js';
+import { sanitizeForTerminal } from './text.js';
 /** Shared MISSING_COMMAND copy for flag-only argv preflight. */
 function missingCommandDetails(bin, swallowed) {
     if (swallowed) {
@@ -26,7 +27,7 @@ function missingCommandDetails(bin, swallowed) {
  * it picks a command, so `bonsai --read-only list` would otherwise treat `--read-only` as the
  * command id. Strip and re-append them after the command/URL, same pattern as `--json`.
  */
-const GLOBAL_BOOLEAN_FLAGS = new Set(['--read-only', '--plan']);
+const GLOBAL_BOOLEAN_FLAGS = new Set(['--read-only', '--plan', '--toon']);
 /**
  * When a value-taking flag is the only "command" and its value looks like a URL, the user almost
  * certainly put the URL where the flag value belongs (e.g. `bonsai --tags https://example.com`).
@@ -47,7 +48,13 @@ function findSwallowedUrlFlag(argv, valueTakingFlags) {
     return null;
 }
 function missingUsageExit(json, argv, valueTakingFlags) {
-    const details = missingCommandDetails('bonsai', findSwallowedUrlFlag(argv, valueTakingFlags));
+    const swallowed = findSwallowedUrlFlag(argv, valueTakingFlags);
+    // `swallowed.url` is raw user input echoed straight back into the MISSING_COMMAND message and its
+    // "pass the URL as the command" suggestion — untrusted per the repo's trust-boundary rules, same
+    // reasoning as BaseCommand.error(). This preflight path fires before oclif ever dispatches a
+    // command, so there is no `this.jsonEnabled()` to call — but `json` is already known here, so gate
+    // on it the same way: sanitize only the human-mode message, keep `--json` byte-for-byte.
+    const details = missingCommandDetails('bonsai', swallowed && !json ? { ...swallowed, url: sanitizeForTerminal(swallowed.url) } : swallowed);
     return {
         exitCode: EXIT_USAGE,
         json,
@@ -86,7 +93,15 @@ function hasCommandToken(argv, valueTakingFlags) {
  * (`cli-flag-manifest`) — this module stays free of command registry imports.
  */
 export function normalizeArgv(rawArgv, options) {
-    const { valueTakingFlags } = options;
+    const { valueTakingFlags, knownCommandRoots } = options;
+    // AXI "content first": a truly bare invocation (`bonsai`, no args/flags at all) shows live cache
+    // data instead of oclif's default root help — `bonsai help`, `--help`, and `-h` remain the
+    // explicit path to the command reference (all of them are non-empty argv and skip this branch).
+    // oclif has no built-in "default command" concept for empty argv (see oclif/oclif#277), so this
+    // is a one-line argv rewrite, the same technique the URL-shorthand rewrite below already uses.
+    if (rawArgv.length === 0) {
+        return { argv: ['list'] };
+    }
     // oclif's JSON flag is command-scoped, so `bonsai list --json` works but
     // `bonsai --json list` is otherwise parsed as an unknown command named
     // "--json". Collect every --json, append one copy after the command/URL, and
@@ -113,8 +128,15 @@ export function normalizeArgv(rawArgv, options) {
     // forms like `javascript:` or `data:` so fetch can reject unsupported protocols instead of oclif
     // reporting a misleading "command not found". If the invocation begins with a flag, allow common
     // flag-before-argument usage such as `bonsai --format detailed https://example.com`.
+    // Exclude tokens whose part before the first `:` names a real command (`config:get`) — oclif
+    // joins namespaced command ids with `:` regardless of the display-only topicSeparator, so those
+    // are commands, not URL schemes, and must reach normal command dispatch instead of a misleading
+    // "Invalid URL" error.
     const firstNonFlagArgIndex = firstPositionalIndex(core, valueTakingFlags);
-    const rootFetchShape = firstNonFlagArgIndex !== -1 && looksLikeUrl(core[firstNonFlagArgIndex]);
+    const firstArg = firstNonFlagArgIndex !== -1 ? core[firstNonFlagArgIndex] : undefined;
+    const rootFetchShape = firstArg !== undefined &&
+        looksLikeUrl(firstArg) &&
+        !knownCommandRoots.has(firstArg.split(':')[0]);
     if (rootFetchShape) {
         const url = core[firstNonFlagArgIndex];
         core = [
@@ -131,7 +153,7 @@ export function normalizeArgv(rawArgv, options) {
         core.push('--json');
     // Flag-only argv (`--json`, `--read-only`, `--tags https://…`) never resolves a command.
     // Exit here so command_not_found does not special-case dash-prefixed ids.
-    // Empty argv and `--help`/`--version` stay with oclif.
+    // Truly empty argv already returned above; `--help`/`--version` stay with oclif here.
     if (!helpRequested && core.length > 0 && !hasCommandToken(core, valueTakingFlags)) {
         return {
             argv: jsonMode ? ['--json'] : [],

package/dist/lib/cli-flag-manifest.d.ts

@@ -3,3 +3,10 @@
  * Built from command class metadata so argv normalization stays free of command imports.
  */
 export declare const VALUE_TAKING_FLAG_TOKENS: ReadonlySet<string>;
+/**
+ * Root segment of every registered command id (`config:get` → `config`). oclif joins namespaced
+ * command ids with `:` regardless of the display-only `topicSeparator` setting, so a token like
+ * `config:get` is a real command, not a URL — argv normalization checks this set before assuming
+ * `word:` is a URL scheme.
+ */
+export declare const KNOWN_COMMAND_ROOT_TOKENS: ReadonlySet<string>;

package/dist/lib/cli-flag-manifest.js

@@ -6,3 +6,10 @@ import { valueTakingFlagTokensFromCommands } from './value-flags.js';
  * Built from command class metadata so argv normalization stays free of command imports.
  */
 export const VALUE_TAKING_FLAG_TOKENS = valueTakingFlagTokensFromCommands(commands, BaseCommand.baseFlags);
+/**
+ * Root segment of every registered command id (`config:get` → `config`). oclif joins namespaced
+ * command ids with `:` regardless of the display-only `topicSeparator` setting, so a token like
+ * `config:get` is a real command, not a URL — argv normalization checks this set before assuming
+ * `word:` is a URL scheme.
+ */
+export const KNOWN_COMMAND_ROOT_TOKENS = new Set(Object.keys(commands).map((id) => id.split(':')[0]));

package/dist/lib/cli-presentation.d.ts

@@ -8,17 +8,19 @@ export declare const CLI_FLAG_DESCRIPTIONS: {
     readonly maxAge: "maximum cache age to accept (e.g. \"2h\", \"7d\", \"6m\")";
     readonly fetchStorage: "override where this result is cached (secrets always stored globally)";
     readonly importStorage: "override where this note is cached (secrets always stored globally)";
-    readonly fetchTopic: "main research topic for metadata";
-    readonly importTopic: "main topic for this research note";
+    readonly fetchTopic: "main research topic for metadata (max 200 chars)";
+    readonly importTopic: "main topic for this research note (max 200 chars)";
     readonly filterTopic: "exact topic (case-insensitive)";
-    readonly fetchTags: "taxonomic tags for this research (can be repeated)";
-    readonly importTags: "taxonomic tags (can be repeated)";
+    readonly fetchTags: "taxonomic tags for this research (can be repeated, max 100 chars each)";
+    readonly importTags: "taxonomic tags (can be repeated, max 100 chars each)";
     readonly filterTags: "tags to require (must match all)";
     readonly format: "output format";
     readonly readOnly: "(alias: --plan) block filesystem writes/deletes; network fetches still run; also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE";
+    readonly toon: "emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json";
     readonly sourceUrlGlob: "source URL glob (case-insensitive, supports * wildcard)";
     readonly listArtifactType: "artifact type; section children are omitted from list - use inspect to see them";
     readonly pruneArtifactType: "artifact type to prune, including section children";
+    readonly listFull: "include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps); default output is a minimal row (source URLs, topic, freshness, token estimate)";
 };
 /** One human-readable label/value pair for CLI stdout. */
 export type HumanField = readonly [label: string, value: string];

package/dist/lib/cli-presentation.js

@@ -1,4 +1,5 @@
 import { colors } from './color.js';
+import { MAX_TAG_LENGTH, MAX_TOPIC_LENGTH } from './research/metadata-flags.js';
 const HUMAN_LABEL_WIDTH = 25;
 // Repeated verbatim across several flag descriptions; single-use wording lives inline below.
 const DURATION_EXAMPLES = 'e.g. "2h", "7d", "6m"';
@@ -13,17 +14,19 @@ export const CLI_FLAG_DESCRIPTIONS = {
     maxAge: `maximum cache age to accept (${DURATION_EXAMPLES})`,
     fetchStorage: `override where this result is cached (${SECRET_STORAGE_NOTE})`,
     importStorage: `override where this note is cached (${SECRET_STORAGE_NOTE})`,
-    fetchTopic: 'main research topic for metadata',
-    importTopic: 'main topic for this research note',
+    fetchTopic: `main research topic for metadata (max ${MAX_TOPIC_LENGTH} chars)`,
+    importTopic: `main topic for this research note (max ${MAX_TOPIC_LENGTH} chars)`,
     filterTopic: 'exact topic (case-insensitive)',
-    fetchTags: 'taxonomic tags for this research (can be repeated)',
-    importTags: 'taxonomic tags (can be repeated)',
+    fetchTags: `taxonomic tags for this research (can be repeated, max ${MAX_TAG_LENGTH} chars each)`,
+    importTags: `taxonomic tags (can be repeated, max ${MAX_TAG_LENGTH} chars each)`,
     filterTags: 'tags to require (must match all)',
     format: 'output format',
     readOnly: '(alias: --plan) block filesystem writes/deletes; network fetches still run; also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE',
+    toon: 'emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json',
     sourceUrlGlob: 'source URL glob (case-insensitive, supports * wildcard)',
     listArtifactType: 'artifact type; section children are omitted from list - use inspect to see them',
     pruneArtifactType: 'artifact type to prune, including section children',
+    listFull: 'include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps); default output is a minimal row (source URLs, topic, freshness, token estimate)',
 };
 function formatHumanLabel(label) {
     const text = `${label}:`;

package/dist/lib/cli-result-types.d.ts

@@ -33,7 +33,7 @@ export type CacheHitStatus = 'hit' | 'miss' | 'stale' | 'refreshed' | 'revalidat
 export type FreshnessState = 'fresh' | 'stale_grace' | 'stale_expired' | 'none';
 /** Freshness values that appear on list rows (an entry always exists). */
 export type ListFreshness = Exclude<FreshnessState, 'none'>;
-/** One row in `list --json` output. */
+/** One row in `list --json` output when `--full` is passed. */
 export interface ListRow {
     cacheKey: string;
     path: string;
@@ -48,6 +48,30 @@ export interface ListRow {
     fetchedAt: string | null;
     validatedAt: string | null;
 }
+/**
+ * Default `list --json`/`--toon` row: the fields an agent needs to judge relevance and act next
+ * (fetch/inspect the source, gauge freshness, budget tokens) without the full metadata dump.
+ * Pass `--full` for every field on {@link ListRow}.
+ */
+export interface ListRowMinimal {
+    sourceUrls: string[];
+    topic: string | null;
+    freshness: ListFreshness;
+    tokenEstimate: TokenEstimate;
+}
+/** Aggregate counts attached to `list`'s envelope so agents skip extra round trips. */
+export interface ListSummary {
+    /** Entries matching the given filters, before `--limit` truncation. */
+    total: number;
+    /** Entries actually returned in `data` (after `--limit`). */
+    shown: number;
+    limit: number;
+    /** True when `total > shown`, i.e. more entries matched than `--limit` allowed through. */
+    truncated: boolean;
+    /** Explicit signal for `total === 0`, so an empty `data: []` is never ambiguous. */
+    empty: boolean;
+    byFreshness: Record<ListFreshness, number>;
+}
 /** Section child summary nested under an inspect hit. */
 export interface InspectSectionRow {
     cacheKey: string;

package/dist/lib/config/index.d.ts

@@ -1,5 +1,5 @@
-export { type ConfigValues, type ResolvedConfig, type ConfigKey, type StorageMode, type SummaryLevel, type KeyMeta, SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
-export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
+export { type ConfigValues, type ResolvedConfig, type ConfigKey, type StorageMode, type SummaryLevel, type KeyMeta, SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, keyValuesHint, } from './schema.js';
+export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, invalidConfigFileWarnings, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
 export { resolveStorageMode, resolveSummaryLevel, resolveReadOnly, parseEnvStorage, parseEnvSummary, parseEnvBoolean, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, READ_ONLY_ENV_VAR, PLAN_MODE_ENV_VAR, type ResolveStorageInput, type ResolveSummaryInput, type ResolveReadOnlyInput, } from './resolve.js';
 import { type ConfigKey, type ConfigValues, type ResolvedConfig, type StorageMode, type SummaryLevel } from './schema.js';
 /**

package/dist/lib/config/index.js

@@ -1,5 +1,5 @@
-export { SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
-export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
+export { SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, keyValuesHint, } from './schema.js';
+export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, invalidConfigFileWarnings, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
 export { resolveStorageMode, resolveSummaryLevel, resolveReadOnly, parseEnvStorage, parseEnvSummary, parseEnvBoolean, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, READ_ONLY_ENV_VAR, PLAN_MODE_ENV_VAR, } from './resolve.js';
 import { readUserConfig, readProjectConfig } from './io.js';
 import { parseEnvStorage, parseEnvSummary, resolveStorageMode, resolveSummaryLevel, } from './resolve.js';

package/dist/lib/config/io.d.ts

@@ -4,5 +4,14 @@ export declare const USER_CONFIG_FILENAME = "config.json";
 export declare const PROJECT_CONFIG_FILENAME = ".bonsai.json";
 export declare function readUserConfig(configDir: string | undefined): Partial<ConfigValues>;
 export declare function readProjectConfig(cwd: string): Partial<ConfigValues>;
+/**
+ * Warnings for the user and project config files, so a corrupted or hand-edited file that would
+ * otherwise silently degrade to `{}` (or drop just the offending key) is never a silent surprise —
+ * mirrors {@link invalidEnvOverrideWarnings} for env vars. Empty when both files are missing,
+ * unreadable, or valid.
+ *
+ * @param bin - CLI binary name (`this.config.bin`) for the "fix it" suggestion in a warning.
+ */
+export declare function invalidConfigFileWarnings(configDir: string | undefined, cwd: string, bin: string): string[];
 export declare function writeUserConfig(configDir: string, patch: Partial<ConfigValues>): void;
 export declare function writeProjectConfig(cwd: string, patch: Partial<ConfigValues>): void;