@taurgis/bonsai 3.2.2 → 4.1.0

package/dist/commands/list.js

@@ -1,34 +1,49 @@
 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, resultListHeading } 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 { 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',
-    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,
+    };
+}
 /** 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,66 +61,36 @@ 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({
-            char: 't',
-            description: CLI_FLAG_DESCRIPTIONS.filterTopic,
-        }),
-        tags: Flags.string({
-            char: 'g',
-            description: CLI_FLAG_DESCRIPTIONS.filterTags,
-            multiple: true,
+        ...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,
         }),
-        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(100, 50, 'result count (default 50, max 100)'),
+        // 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;
-    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()));
+    /** 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 (!this.matchesTopic(meta, this.flags.topic)) {
-            return false;
-        }
-        if (!this.matchesTags(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.
@@ -116,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;
@@ -156,26 +133,22 @@ 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 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; --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;
-        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.';
@@ -184,12 +157,20 @@ 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' });
+        this.logIdentityHeader();
         const roots = loadStoreRoots({
             configDir: this.config.configDir,
             cwd: process.cwd(),
@@ -203,23 +184,31 @@ 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;
-        this.logListResults(finalResults, results.length);
-        return finalResults;
+        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,
+            empty: results.length === 0,
+            byFreshness: countByFreshness(results),
+            nextCommand,
+        };
+        this.logListResults(finalResults, results.length, nextCommand);
+        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/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>;
+}