@taurgis/bonsai 4.0.0 → 4.1.1

package/dist/commands/search.js

@@ -0,0 +1,233 @@
+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';
+import { formatTip, resultListHeading, sanitizeForTerminal, } from '../lib/text.js';
+import { limitFlag } from '../lib/limit-flag.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 { tokenizeSearchQuery, emptySearchQueryError, scoreSearchMatch, extractSearchSnippet, } from '../lib/research/search-match.js';
+import { colors, FRESHNESS_COLOR } from '../lib/color.js';
+import { CLI_FLAG_DESCRIPTIONS, formatResultRowHeader, formatResultRowSourceUrls, formatResultRowTokens, } from '../lib/cli-presentation.js';
+const SEARCH_DEFAULT_MAX_LIMIT = 100;
+// A small default (matching `list`'s) keeps a broad query from flooding an agent's context;
+// `summary.truncated`/`nextCommand` (and the human-mode tip) make raising --limit an explicit,
+// deliberate next step rather than a silent, unbounded dump.
+const SEARCH_DEFAULT_LIMIT = 10;
+const NO_MATCH_SCORE = { score: 0, matchedFields: [] };
+/** Project a full row down to the default minimal shape (see {@link SearchRowMinimal}). */
+function toMinimalSearchRow(row) {
+    return {
+        sourceUrls: row.sourceUrls,
+        topic: row.topic,
+        freshness: row.freshness,
+        tokenEstimate: row.tokenEstimate,
+        score: row.score,
+        matchedFields: row.matchedFields,
+        snippet: row.snippet,
+    };
+}
+/** Search cached research artifacts by tag/content keywords and metadata filters. */
+export default class ResearchSearch extends BaseCommand {
+    static id = 'search';
+    static summary = 'Search cached research artifacts by tags and content';
+    static description = 'Rank cached page-level artifacts by a --query matched against topic, tags, summary, and ' +
+        'compressed content, plus the same metadata filters as `list` (topic, tags, URL, freshness, ' +
+        'artifact type, capture method). Reads only the token-cheap indexed summary/compressed text, ' +
+        'never the full detailed body, so ranking a large cache stays fast. Pass --full for every ' +
+        'metadata field.';
+    /** Aggregate counts (and an explicit empty/truncation signal); see `list.ts`'s equivalent. */
+    jsonSummary = null;
+    static examples = [
+        {
+            description: 'search content and tags for a keyword',
+            command: '<%= config.bin %> search --query "suspense boundary"',
+        },
+        {
+            description: 'match any of several terms instead of requiring all',
+            command: '<%= config.bin %> search --query "suspense streaming" --match-any',
+        },
+        {
+            description: 'combine a query with metadata filters',
+            command: '<%= config.bin %> search --query cache --tags react --freshness fresh',
+        },
+        {
+            description: 'filter by tags/topic alone, ranked like list (no --query)',
+            command: '<%= config.bin %> search --tags node --json',
+        },
+    ];
+    static flags = {
+        query: Flags.string({
+            char: 'q',
+            description: CLI_FLAG_DESCRIPTIONS.searchQuery,
+        }),
+        'match-any': Flags.boolean({
+            default: false,
+            description: CLI_FLAG_DESCRIPTIONS.searchMatchAny,
+        }),
+        ...commonMetadataFilterFlags(CLI_FLAG_DESCRIPTIONS.searchArtifactType),
+        limit: limitFlag(SEARCH_DEFAULT_MAX_LIMIT, SEARCH_DEFAULT_LIMIT, `result count (max ${SEARCH_DEFAULT_MAX_LIMIT}, default ${SEARCH_DEFAULT_LIMIT})`),
+        full: Flags.boolean({
+            default: false,
+            description: CLI_FLAG_DESCRIPTIONS.searchFull,
+        }),
+    };
+    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,
+        };
+    }
+    matchesMetadataFilters(meta, freshness) {
+        return matchesCommonMetadataFilters(meta, freshness, this.metadataFilterFlags());
+    }
+    scanCacheDirForSearch(readRoots, currentTime, terms) {
+        const matchAny = this.flags['match-any'];
+        // Honor effective read-only: searching must not persist the derived search-index sidecar.
+        return scanCacheDirs(readRoots, (artifact, filePath) => {
+            if (artifact.metadata.status !== 'active')
+                return null;
+            // Page-level only, same reasoning as `list`: sections are sub-chunks of a page, not
+            // artifacts a user "has" — find them via `inspect` instead.
+            if (artifact.metadata.artifact_type === 'section')
+                return null;
+            const freshness = evaluateFreshness(artifact.metadata, currentTime, null);
+            if (!this.matchesMetadataFilters(artifact.metadata, freshness))
+                return null;
+            let match = NO_MATCH_SCORE;
+            let snippet = null;
+            if (terms.length > 0) {
+                const scored = scoreSearchMatch({
+                    topic: artifact.metadata.topic,
+                    tags: artifact.metadata.tags,
+                    summary: artifact.summary,
+                    compressed: artifact.compressed,
+                }, terms, matchAny);
+                if (!scored)
+                    return null;
+                match = scored;
+                snippet = extractSearchSnippet({ summary: artifact.summary, compressed: artifact.compressed }, terms);
+            }
+            return {
+                ...toListRow(artifact, filePath, freshness),
+                score: match.score,
+                matchedFields: match.matchedFields,
+                snippet,
+            };
+        }, { persistIndex: !this.readOnly });
+    }
+    /** Newest-first (no query) or highest-score-first (query given), both tie-broken by cache key. */
+    sortResults(results, queried) {
+        results.sort((a, b) => {
+            if (queried && b.score !== a.score)
+                return b.score - a.score;
+            const timeA = new Date(a.validatedAt || a.fetchedAt || 0).getTime();
+            const timeB = new Date(b.validatedAt || b.fetchedAt || 0).getTime();
+            if (timeB !== timeA)
+                return timeB - timeA;
+            return a.cacheKey.localeCompare(b.cacheKey);
+        });
+    }
+    hasActiveFilters() {
+        return Boolean(this.flags.query) || hasActiveMetadataFilters(this.metadataFilterFlags());
+    }
+    logSearchResults(finalResults, totalMatched, queried, nextCommand) {
+        if (finalResults.length === 0) {
+            this.emitEmptySearchGuidance();
+            return;
+        }
+        if (this.jsonEnabled())
+            return;
+        const labels = queried
+            ? { noun: 'matching cached research', order: 'top' }
+            : { noun: 'cached research', order: 'first' };
+        this.log(`${resultListHeading(totalMatched, finalResults.length, labels)}\n`);
+        finalResults.forEach((res, index) => {
+            this.log(formatResultRowHeader(index, res.topic, res.cacheKey));
+            const freshnessStr = FRESHNESS_COLOR[res.freshness](res.freshness);
+            const scoreStr = queried ? ` | Score: ${colors.bold(String(res.score))}` : '';
+            this.log(`   Type: ${colors.bold(res.artifactType)} | Freshness: ${freshnessStr}${scoreStr}`);
+            if (queried && res.matchedFields.length > 0) {
+                this.log(`   Matched: ${colors.gray(res.matchedFields.join(', '))}`);
+            }
+            if (res.snippet) {
+                this.log(`   Snippet: ${colors.gray(sanitizeForTerminal(res.snippet))}`);
+            }
+            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
+     * `summary.empty: true` instead of prose — see {@link toSuccessJson}.
+     */
+    emitEmptySearchGuidance() {
+        if (this.jsonEnabled())
+            return;
+        const filtered = this.hasActiveFilters();
+        const headline = filtered
+            ? 'No cached research entries match the given search.'
+            : 'No cached research entries found.';
+        const tipCmd = filtered ? `${this.config.bin} search` : `${this.config.bin} <url>`;
+        const tipLead = filtered
+            ? 'try a broader --query, --match-any, or relax other filters: '
+            : 'populate the cache first: ';
+        this.log(headline);
+        this.log(`\n${formatTip(`${tipLead}${colors.cyan(tipCmd)}`)}`);
+    }
+    async run() {
+        const flagErr = emptyUrlFilterError(this.flags.url) ??
+            emptyTopicFilterError(this.flags.topic) ??
+            emptyTagsFilterError(this.flags.tags) ??
+            emptySearchQueryError(this.flags.query);
+        if (flagErr)
+            this.error(flagErr, { exit: 2, code: 'INVALID_FLAG_VALUE' });
+        const roots = loadStoreRoots({
+            configDir: this.config.configDir,
+            cwd: process.cwd(),
+            dataDir: this.config.dataDir,
+        });
+        const currentTime = new Date();
+        const terms = this.flags.query ? tokenizeSearchQuery(this.flags.query) : [];
+        const queried = terms.length > 0;
+        const results = this.scanCacheDirForSearch(roots.readRoots, currentTime, terms);
+        this.sortResults(results, queried);
+        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, 'search', this.argv, Math.min(results.length, SEARCH_DEFAULT_MAX_LIMIT))
+            : null;
+        this.jsonSummary = {
+            total: results.length,
+            shown: finalResults.length,
+            limit: this.flags.limit,
+            truncated,
+            empty: results.length === 0,
+            byFreshness: countByFreshness(results),
+            queried,
+            nextCommand,
+        };
+        this.logSearchResults(finalResults, results.length, queried, nextCommand);
+        return this.flags.full ? finalResults : finalResults.map(toMinimalSearchRow);
+    }
+    /** Attach the aggregate `summary` computed in `run()` (see {@link SearchSummary}). */
+    toSuccessJson(data) {
+        const envelope = this.baseSuccessJson(data);
+        if (!this.jsonSummary)
+            return envelope;
+        return { ...envelope, summary: this.jsonSummary };
+    }
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,27 @@
+import { BaseCommand } from '../base-command.js';
+import type { SetupResult } from '../lib/cli-result-types.js';
+/**
+ * Installs (or repairs) a `SessionStart` hook that runs `bonsai context` at the start of every
+ * agent session, so the cache's current state is visible before the agent takes any action (AXI
+ * principle 7: ambient context via session integrations).
+ */
+export default class Setup extends BaseCommand<typeof Setup> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static args: {
+        agent: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static stdoutIsPrimaryData: boolean;
+    private assertKnownAgent;
+    run(): Promise<SetupResult>;
+}

package/dist/commands/setup.js

@@ -0,0 +1,148 @@
+import { Args, Flags } from '@oclif/core';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { BaseCommand } from '../base-command.js';
+import { atomicWriteFile } from '../lib/atomic-write.js';
+import { resolveBinCommand } from '../lib/setup/bin-command.js';
+import { SETUP_AGENTS, SETUP_AGENT_TARGETS, SETUP_HOOK_COMMAND_SUFFIX, SETUP_HOOK_MANAGED_BY, } from '../lib/setup/agents.js';
+import { InvalidHookFileError, planSessionStartHookInstall, } from '../lib/setup/hook-file-io.js';
+import { closestMatch, maxFuzzyDistance } from '../lib/text.js';
+import { assertScopeFlagsExclusive, scopeFlags } from '../lib/scope-flags.js';
+function isSetupAgent(value) {
+    return SETUP_AGENTS.includes(value);
+}
+/**
+ * Nearest known agent for a typo'd `agentArg`, or `null` if nothing plausible matches. Checks a
+ * prefix relationship first (either direction) so a short, valid-looking typo like `claude` for
+ * `claude-code` is caught even though its edit distance to the full name exceeds the general
+ * Levenshtein threshold; falls back to edit distance for closer misspellings like `codexx`.
+ */
+function suggestAgent(agentArg) {
+    const prefixMatch = SETUP_AGENTS.find((agent) => agent.startsWith(agentArg) || agentArg.startsWith(agent));
+    if (prefixMatch)
+        return prefixMatch;
+    // closestMatch's candidates are exactly SETUP_AGENTS, so any non-null result is a SetupAgent.
+    return closestMatch(agentArg, SETUP_AGENTS, maxFuzzyDistance(agentArg));
+}
+/** Maps a plan outcome to the reported status, remapping write outcomes to `would_*` under dry-run. */
+function reportSetupStatus(planStatus, dryRun) {
+    if (!dryRun)
+        return planStatus;
+    if (planStatus === 'unchanged')
+        return 'unchanged';
+    return planStatus === 'repaired' ? 'would_repair' : 'would_install';
+}
+const SETUP_STATUS_LABEL = {
+    installed: 'Installed',
+    repaired: 'Repaired',
+    unchanged: 'Already up to date:',
+    would_install: '[dry-run] Would install',
+    would_repair: '[dry-run] Would repair',
+};
+/**
+ * Installs (or repairs) a `SessionStart` hook that runs `bonsai context` at the start of every
+ * agent session, so the cache's current state is visible before the agent takes any action (AXI
+ * principle 7: ambient context via session integrations).
+ */
+export default class Setup extends BaseCommand {
+    static id = 'setup';
+    static summary = 'Install a SessionStart hook that shows live cache context';
+    static description = 'Writes (or repairs) a SessionStart hook entry that runs `bonsai context` at the start of ' +
+        'every session, so the agent sees the cache state before doing anything. Project-scoped by ' +
+        'default (shareable via version control); pass --global for a user-level, machine-only install. ' +
+        'Re-running is idempotent: an unchanged install is a no-op, and a stale executable path is repaired.';
+    static examples = [
+        {
+            description: 'install the hook for this project (Claude Code)',
+            command: '<%= config.bin %> setup claude-code',
+        },
+        {
+            description: 'install the hook for this project (Codex)',
+            command: '<%= config.bin %> setup codex',
+        },
+        {
+            description: 'preview a user-level install without writing anything',
+            command: '<%= config.bin %> setup claude-code --global --dry-run --json',
+        },
+    ];
+    static args = {
+        agent: Args.string({
+            required: true,
+            description: `agent to install the hook for (${SETUP_AGENTS.join(', ')})`,
+        }),
+    };
+    static flags = {
+        ...scopeFlags({
+            global: 'install to the user-level config instead of the project (default: project)',
+            local: 'install to the project config (default; explicit form of the default)',
+        }),
+        'dry-run': Flags.boolean({
+            description: 'preview the install without writing anything',
+            default: false,
+        }),
+    };
+    static stdoutIsPrimaryData = true;
+    assertKnownAgent(agentArg) {
+        if (isSetupAgent(agentArg))
+            return;
+        if (agentArg === 'opencode') {
+            this.error('OpenCode is not supported by `setup` yet: its plugin hook signature for injecting ' +
+                "session-start context isn't confirmed in official docs, so Bonsai won't guess at one. " +
+                'See the "Ambient session context" docs for status.', { exit: 2, code: 'UNKNOWN_AGENT', suggestions: [`Use one of: ${SETUP_AGENTS.join(', ')}`] });
+        }
+        const suggestion = suggestAgent(agentArg);
+        const hint = suggestion ? ` Did you mean "${suggestion}"?` : '';
+        this.error(`Unknown agent: "${agentArg}".${hint} Supported agents: ${SETUP_AGENTS.join(', ')}.`, {
+            exit: 2,
+            code: 'UNKNOWN_AGENT',
+            suggestions: suggestion
+                ? [`Use "${suggestion}": ${this.config.bin} setup ${suggestion}`]
+                : [`Use one of: ${SETUP_AGENTS.join(', ')}`],
+        });
+    }
+    async run() {
+        const agentArg = this.args.agent;
+        this.assertKnownAgent(agentArg);
+        assertScopeFlagsExclusive(this.error.bind(this), this.flags.global, this.flags.local);
+        const target = SETUP_AGENT_TARGETS[agentArg];
+        const scope = this.flags.global ? 'user' : 'project';
+        const root = scope === 'user' ? homedir() : process.cwd();
+        const path = join(root, target.relativePath);
+        const binCommand = resolveBinCommand(process.argv[1] ?? this.config.bin);
+        const command = `${binCommand} ${SETUP_HOOK_COMMAND_SUFFIX}`;
+        const existingContent = existsSync(path) ? readFileSync(path, 'utf-8') : null;
+        let plan;
+        try {
+            plan = planSessionStartHookInstall(existingContent, {
+                eventName: target.eventName,
+                matcher: target.matcher,
+                command,
+                timeout: target.timeout,
+                managedBy: SETUP_HOOK_MANAGED_BY,
+            });
+        }
+        catch (err) {
+            if (err instanceof InvalidHookFileError) {
+                this.error(`Cannot install into ${path}: ${err.message}.`, {
+                    exit: 1,
+                    code: 'INVALID_HOOK_FILE',
+                    suggestions: [
+                        'Fix or remove the existing file so it contains a single JSON object, then re-run setup.',
+                    ],
+                });
+            }
+            throw err;
+        }
+        const dryRun = this.effectiveDryRun(this.flags['dry-run']);
+        const status = reportSetupStatus(plan.status, dryRun);
+        if (!dryRun && plan.status !== 'unchanged') {
+            mkdirSync(dirname(path), { recursive: true });
+            atomicWriteFile(path, plan.content);
+        }
+        if (!this.jsonEnabled()) {
+            this.log(`${SETUP_STATUS_LABEL[status]} ${agentArg} SessionStart hook at ${path} (${scope})`);
+        }
+        return { agent: agentArg, scope, path, binCommand, status, dryRun };
+    }
+}

package/dist/commands.d.ts

@@ -3,18 +3,24 @@ import ConfigIndex from './commands/config/index.js';
 import ConfigList from './commands/config/list.js';
 import ConfigSet from './commands/config/set.js';
 import ConfigUnset from './commands/config/unset.js';
+import ContextCommand from './commands/context.js';
 import FetchCommand from './commands/fetch.js';
 import ImportCommand from './commands/import.js';
 import InspectCommand from './commands/inspect.js';
 import ListCommand from './commands/list.js';
 import PruneCommand from './commands/prune.js';
+import SearchCommand from './commands/search.js';
+import SetupCommand from './commands/setup.js';
 import StatusCommand from './commands/status.js';
 export declare const commands: {
+    context: typeof ContextCommand;
     fetch: typeof FetchCommand;
     import: typeof ImportCommand;
     inspect: typeof InspectCommand;
     list: typeof ListCommand;
     prune: typeof PruneCommand;
+    search: typeof SearchCommand;
+    setup: typeof SetupCommand;
     status: typeof StatusCommand;
     config: typeof ConfigIndex;
     'config:get': typeof ConfigGet;

package/dist/commands.js

@@ -3,18 +3,24 @@ import ConfigIndex from './commands/config/index.js';
 import ConfigList from './commands/config/list.js';
 import ConfigSet from './commands/config/set.js';
 import ConfigUnset from './commands/config/unset.js';
+import ContextCommand from './commands/context.js';
 import FetchCommand from './commands/fetch.js';
 import ImportCommand from './commands/import.js';
 import InspectCommand from './commands/inspect.js';
 import ListCommand from './commands/list.js';
 import PruneCommand from './commands/prune.js';
+import SearchCommand from './commands/search.js';
+import SetupCommand from './commands/setup.js';
 import StatusCommand from './commands/status.js';
 export const commands = {
+    context: ContextCommand,
     fetch: FetchCommand,
     import: ImportCommand,
     inspect: InspectCommand,
     list: ListCommand,
     prune: PruneCommand,
+    search: SearchCommand,
+    setup: SetupCommand,
     status: StatusCommand,
     config: ConfigIndex,
     'config:get': ConfigGet,

package/dist/lib/argv.js

@@ -99,8 +99,11 @@ export function normalizeArgv(rawArgv, options) {
     // 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.
+    // The hidden `--identity` flag (AXI principle 10) tells `list` to also identify the tool (bin
+    // path, one-sentence description) before the live data — only the true bare invocation gets it,
+    // not an explicit `bonsai list`.
     if (rawArgv.length === 0) {
-        return { argv: ['list'] };
+        return { argv: ['list', '--identity'] };
     }
     // oclif's JSON flag is command-scoped, so `bonsai list --json` works but
     // `bonsai --json list` is otherwise parsed as an unknown command named

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

@@ -1,6 +1,6 @@
 /**
- * Composition-root flag manifest: every CLI token that consumes a following argv value.
- * Built from command class metadata so argv normalization stays free of command imports.
+ * Every CLI token that consumes a following argv value, from the shipped oclif manifest.
+ * Argv normalization stays off the command-class import graph.
  */
 export declare const VALUE_TAKING_FLAG_TOKENS: ReadonlySet<string>;
 /**

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

@@ -1,15 +1,23 @@
-import { BaseCommand } from '../base-command.js';
-import { commands } from '../commands.js';
-import { valueTakingFlagTokensFromCommands } from './value-flags.js';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { valueTakingFlagTokensFromFlagMaps } from './value-flags.js';
+// Startup reads the generated manifest instead of importing every command class. Importing the
+// registry pulls the fetch stack (Readability, Turndown, the browser fallback) into --help.
+function readOclifManifest() {
+    const manifestPath = join(dirname(fileURLToPath(import.meta.url)), '../../oclif.manifest.json');
+    return JSON.parse(readFileSync(manifestPath, 'utf8'));
+}
+const manifest = readOclifManifest();
 /**
- * Composition-root flag manifest: every CLI token that consumes a following argv value.
- * Built from command class metadata so argv normalization stays free of command imports.
+ * Every CLI token that consumes a following argv value, from the shipped oclif manifest.
+ * Argv normalization stays off the command-class import graph.
  */
-export const VALUE_TAKING_FLAG_TOKENS = valueTakingFlagTokensFromCommands(commands, BaseCommand.baseFlags);
+export const VALUE_TAKING_FLAG_TOKENS = valueTakingFlagTokensFromFlagMaps(Object.values(manifest.commands).map((command) => command.flags));
 /**
  * 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]));
+export const KNOWN_COMMAND_ROOT_TOKENS = new Set(Object.keys(manifest.commands).map((id) => id.split(':')[0]));

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

@@ -1,3 +1,4 @@
+import type { TokenEstimate } from './research/schema.js';
 /** Shared flag/help copy so identical flags read identically across commands. */
 export declare const CLI_FLAG_DESCRIPTIONS: {
     readonly freshnessTierPolicy: "freshness tier policy";
@@ -21,6 +22,10 @@ export declare const CLI_FLAG_DESCRIPTIONS: {
     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)";
+    readonly searchQuery: "keyword(s) to search across topic, tags, summary, and compressed content (case-insensitive); every term must match somewhere unless --match-any is set";
+    readonly searchMatchAny: "match any query term instead of requiring all of them (OR instead of AND)";
+    readonly searchArtifactType: "artifact type; section children are omitted from search - use inspect to see them";
+    readonly searchFull: "include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps) alongside score/matchedFields/snippet; default output is a minimal row (source URLs, topic, freshness, token estimate, score, matchedFields, snippet)";
 };
 /** One human-readable label/value pair for CLI stdout. */
 export type HumanField = readonly [label: string, value: string];
@@ -39,3 +44,17 @@ export declare function formatHumanField(label: string, value: string): string;
  * @returns Formatted lines in the same order.
  */
 export declare function formatHumanFields(fields: readonly HumanField[]): string[];
+/**
+ * The "N. [Topic] Key: <key>" header line shared by `list`/`search` human-mode row rendering —
+ * same topic coloring, ANSI-sanitization, and "(no topic)" fallback either way.
+ *
+ * @param index - Zero-based row index; displayed as `index + 1`.
+ * @param topic - The row's topic, or `null` to show {@link NO_TOPIC_LABEL}.
+ * @param cacheKey - The row's cache key.
+ * @returns A single formatted line.
+ */
+export declare function formatResultRowHeader(index: number, topic: string | null, cacheKey: string): string;
+/** The "Tokens: compressed=N, detailed=N" line shared by `list`/`search` human-mode row rendering. */
+export declare function formatResultRowTokens(tokenEstimate: TokenEstimate): string;
+/** The "Source URLs: ..." line shared by `list`/`search` human-mode row rendering. */
+export declare function formatResultRowSourceUrls(sourceUrls: readonly string[]): string;

package/dist/lib/cli-presentation.js

@@ -1,5 +1,6 @@
 import { colors } from './color.js';
 import { MAX_TAG_LENGTH, MAX_TOPIC_LENGTH } from './research/metadata-flags.js';
+import { NO_TOPIC_LABEL, sanitizeForTerminal } from './text.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"';
@@ -27,6 +28,10 @@ export const CLI_FLAG_DESCRIPTIONS = {
     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)',
+    searchQuery: 'keyword(s) to search across topic, tags, summary, and compressed content (case-insensitive); every term must match somewhere unless --match-any is set',
+    searchMatchAny: 'match any query term instead of requiring all of them (OR instead of AND)',
+    searchArtifactType: 'artifact type; section children are omitted from search - use inspect to see them',
+    searchFull: 'include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps) alongside score/matchedFields/snippet; default output is a minimal row (source URLs, topic, freshness, token estimate, score, matchedFields, snippet)',
 };
 function formatHumanLabel(label) {
     const text = `${label}:`;
@@ -51,3 +56,25 @@ export function formatHumanField(label, value) {
 export function formatHumanFields(fields) {
     return fields.map(([label, value]) => formatHumanField(label, value));
 }
+/**
+ * The "N. [Topic] Key: <key>" header line shared by `list`/`search` human-mode row rendering —
+ * same topic coloring, ANSI-sanitization, and "(no topic)" fallback either way.
+ *
+ * @param index - Zero-based row index; displayed as `index + 1`.
+ * @param topic - The row's topic, or `null` to show {@link NO_TOPIC_LABEL}.
+ * @param cacheKey - The row's cache key.
+ * @returns A single formatted line.
+ */
+export function formatResultRowHeader(index, topic, cacheKey) {
+    const topicStr = topic ? colors.cyan(sanitizeForTerminal(topic)) : colors.gray(NO_TOPIC_LABEL);
+    const keyStr = colors.bold(cacheKey);
+    return `${index + 1}. [${topicStr}] Key: ${keyStr}`;
+}
+/** The "Tokens: compressed=N, detailed=N" line shared by `list`/`search` human-mode row rendering. */
+export function formatResultRowTokens(tokenEstimate) {
+    return `   Tokens: compressed=${colors.bold(String(tokenEstimate?.compressed || 0))}, detailed=${colors.bold(String(tokenEstimate?.detailed || 0))}`;
+}
+/** The "Source URLs: ..." line shared by `list`/`search` human-mode row rendering. */
+export function formatResultRowSourceUrls(sourceUrls) {
+    return `   Source URLs: ${colors.gray(sourceUrls.join(', '))}\n`;
+}