@taurgis/bonsai 3.2.0 → 4.0.0

package/dist/lib/argv.js

@@ -1,51 +1,106 @@
-import { buildEnvelope } from './envelope.js';
+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) {
+        return {
+            code: 'MISSING_COMMAND',
+            message: [
+                `Missing URL or command. ${swallowed.flag} consumed ${swallowed.url} as its value, so there was no URL left to fetch.`,
+                `Run ${bin} --help for usage.`,
+            ].join('\n'),
+            suggestions: [
+                `Pass the URL as the command (flags after): ${bin} ${swallowed.url}`,
+                `Or a named command: ${bin} list`,
+            ],
+        };
+    }
+    return {
+        code: 'MISSING_COMMAND',
+        message: `Missing URL or command. Run ${bin} --help for usage.`,
+        suggestions: [`Pass a URL: ${bin} https://example.com`, `Or a command: ${bin} list`],
+    };
+}
+/**
+ * Boolean flags registered on every command via BaseCommand.baseFlags. oclif only merges those after
+ * 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', '--toon']);
 /**
- * Normalizes process.argv (excluding Node executable and script path) so the
- * oclif pipeline sees one consistent command structure.
+ * 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`).
  */
-function missingUsageJsonExit() {
+function findSwallowedUrlFlag(argv, valueTakingFlags) {
+    if (!argv?.length)
+        return null;
+    for (let i = 0; i < argv.length - 1; i++) {
+        const flag = argv[i];
+        if (!valueTakingFlags.has(flag))
+            continue;
+        const value = argv[i + 1];
+        if (value.startsWith('-'))
+            continue;
+        if (looksLikeUrl(value))
+            return { flag, url: value };
+    }
+    return null;
+}
+function missingUsageExit(json, 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: 2,
-        envelope: buildEnvelope({
+        exitCode: EXIT_USAGE,
+        json,
+        envelope: buildCliErrorEnvelope({
             command: 'bonsai',
-            ok: false,
-            exitCode: 2,
-            stderr: 'Missing URL or command. Run bonsai --help for usage.',
-            data: null,
+            message: details.message,
+            code: details.code,
+            suggestions: details.suggestions,
         }),
     };
 }
-const FLAGS_WITH_VALUES = new Set([
-    '--topic',
-    '-t',
-    '--tags',
-    '-g',
-    '--format',
-    '--tier',
-    '--ttl',
-    '--max-age',
-    '--storage',
-    '--file',
-    '-f',
-    '--input-format',
-    '--source-url',
-    '--freshness',
-    '--artifact-type',
-    '--capture-method',
-    '--older-than',
-    '--inactive',
-    '--domain',
-    '--remote',
-    '--limit',
-]);
-export function normalizeArgv(rawArgv) {
-    const onlyJsonFlags = rawArgv.length > 0 && rawArgv.every((arg) => arg === '--json');
-    if (onlyJsonFlags) {
-        return {
-            // bin/cli.mjs exits before applying argv when exitWithJson is set.
-            argv: ['--json'],
-            exitWithJson: missingUsageJsonExit(),
-        };
+/**
+ * Index of the first positional command/URL token, skipping flags (and value-flag operands)
+ * plus root meta tokens that never name a command (`--help`, `--json`, globals).
+ */
+function firstPositionalIndex(argv, valueTakingFlags) {
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--help' || token === '--json' || GLOBAL_BOOLEAN_FLAGS.has(token))
+            continue;
+        if (token.startsWith('-')) {
+            if (valueTakingFlags.has(token))
+                i++;
+            continue;
+        }
+        return i;
+    }
+    return -1;
+}
+/** True when argv selects a command, URL, or root `--version` action (not flag-only usage). */
+function hasCommandToken(argv, valueTakingFlags) {
+    return argv.includes('--version') || firstPositionalIndex(argv, valueTakingFlags) !== -1;
+}
+/**
+ * Normalize raw process argv for oclif. `valueTakingFlags` must come from the composition root
+ * (`cli-flag-manifest`) — this module stays free of command registry imports.
+ */
+export function normalizeArgv(rawArgv, 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
@@ -60,23 +115,28 @@ export function normalizeArgv(rawArgv) {
     }
     const helpRequested = tokens.includes('--help');
     let core = tokens.filter((arg) => arg !== '--help');
+    // Relocate base boolean flags so they survive command resolution (see GLOBAL_BOOLEAN_FLAGS).
+    const relocatedGlobals = [];
+    core = core.filter((arg) => {
+        if (!GLOBAL_BOOLEAN_FLAGS.has(arg))
+            return true;
+        if (!relocatedGlobals.includes(arg))
+            relocatedGlobals.push(arg);
+        return false;
+    });
     // Treat URL-shaped tokens as the `fetch` shorthand. Match both `https://...` and scheme-only
     // 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`.
-    let firstNonFlagArgIndex = -1;
-    for (let i = 0; i < core.length; i++) {
-        const token = core[i];
-        if (token.startsWith('-')) {
-            if (FLAGS_WITH_VALUES.has(token)) {
-                i++; // skip the value
-            }
-            continue;
-        }
-        firstNonFlagArgIndex = i;
-        break;
-    }
-    const rootFetchShape = firstNonFlagArgIndex !== -1 && looksLikeUrl(core[firstNonFlagArgIndex]);
+    // 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 firstArg = firstNonFlagArgIndex !== -1 ? core[firstNonFlagArgIndex] : undefined;
+    const rootFetchShape = firstArg !== undefined &&
+        looksLikeUrl(firstArg) &&
+        !knownCommandRoots.has(firstArg.split(':')[0]);
     if (rootFetchShape) {
         const url = core[firstNonFlagArgIndex];
         core = [
@@ -88,10 +148,43 @@ export function normalizeArgv(rawArgv) {
     }
     if (helpRequested)
         core.push('--help');
+    core.push(...relocatedGlobals);
     if (jsonMode)
         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.
+    // Truly empty argv already returned above; `--help`/`--version` stay with oclif here.
+    if (!helpRequested && core.length > 0 && !hasCommandToken(core, valueTakingFlags)) {
+        return {
+            argv: jsonMode ? ['--json'] : [],
+            earlyExit: missingUsageExit(jsonMode, rawArgv, valueTakingFlags),
+        };
+    }
     return { argv: core };
 }
+/**
+ * Non-flag positional tokens from a (typically already-normalized) argv. Skips `--help`/`--json`
+ * and any dash-prefixed flags so multi-segment command ids (`config get`) stay intact. Shared by
+ * help-preflight and json-meta — both run after `normalizeArgv` has already folded `help X` →
+ * `X --help` and `-h` → `--help`.
+ */
+export function positionalArgvTokens(argv, valueTakingFlags) {
+    const tokens = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--')
+            break;
+        if (arg === '--help' || arg === '--json')
+            continue;
+        if (arg.startsWith('-')) {
+            if (!arg.includes('=') && valueTakingFlags.has(arg))
+                i++;
+            continue;
+        }
+        tokens.push(arg);
+    }
+    return tokens;
+}
 function looksLikeUrl(arg) {
     return arg.includes('://') || /^[a-z][a-z0-9+.-]*:/i.test(arg);
 }

package/dist/lib/batch.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Collapse a multi-URL command's per-URL rows into the CLI's single-vs-array return
+ * contract, and mark {@link EXIT_RUNTIME_FAILURE} when any row is a failure outcome.
+ *
+ * @param results - Per-URL result rows.
+ * @param isFailure - Predicate marking a row as a failure outcome.
+ * @returns The sole row when there is one URL; otherwise the full array.
+ */
+export declare function finalizeBatch<T>(results: T[], isFailure: (row: T) => boolean): T | T[];
+/**
+ * status/inspect batch rows: a miss or a validation error row is a failure outcome.
+ *
+ * @param row - Batch row with a `status` field.
+ * @returns `true` when the row should fail the batch exit code.
+ */
+export declare function isBatchReadFailure(row: {
+    status: string;
+}): boolean;
+/**
+ * Sparse validation-failure row for multi-URL status/inspect. Only the fields agents need —
+ * no fake cacheKey/freshness/metadata padding.
+ *
+ * @param url - Input URL that failed validation.
+ * @param err - Error-like object with optional code/message/suggestions/ref.
+ * @returns Sparse error row for the batch result array.
+ */
+export declare function urlValidationErrorRow(url: string, err: {
+    code?: string;
+    message?: string;
+    suggestions?: string[];
+    ref?: string;
+}): {
+    status: "error";
+    normalizedUrl: string;
+    error: {
+        code: string;
+        message: string;
+        suggestions?: string[];
+        ref?: string;
+    };
+};

package/dist/lib/batch.js

@@ -0,0 +1,39 @@
+import { cliErrorFields } from './envelope.js';
+import { EXIT_RUNTIME_FAILURE } from './cli-error-policy.js';
+/**
+ * Collapse a multi-URL command's per-URL rows into the CLI's single-vs-array return
+ * contract, and mark {@link EXIT_RUNTIME_FAILURE} when any row is a failure outcome.
+ *
+ * @param results - Per-URL result rows.
+ * @param isFailure - Predicate marking a row as a failure outcome.
+ * @returns The sole row when there is one URL; otherwise the full array.
+ */
+export function finalizeBatch(results, isFailure) {
+    if (results.some(isFailure))
+        process.exitCode = EXIT_RUNTIME_FAILURE;
+    return results.length === 1 ? results[0] : results;
+}
+/**
+ * status/inspect batch rows: a miss or a validation error row is a failure outcome.
+ *
+ * @param row - Batch row with a `status` field.
+ * @returns `true` when the row should fail the batch exit code.
+ */
+export function isBatchReadFailure(row) {
+    return row.status === 'miss' || row.status === 'error';
+}
+/**
+ * Sparse validation-failure row for multi-URL status/inspect. Only the fields agents need —
+ * no fake cacheKey/freshness/metadata padding.
+ *
+ * @param url - Input URL that failed validation.
+ * @param err - Error-like object with optional code/message/suggestions/ref.
+ * @returns Sparse error row for the batch result array.
+ */
+export function urlValidationErrorRow(url, err) {
+    return {
+        status: 'error',
+        normalizedUrl: url,
+        error: cliErrorFields(err),
+    };
+}

package/dist/lib/cache-view.d.ts

@@ -0,0 +1,21 @@
+import { type HumanField } from './cli-presentation.js';
+/**
+ * Shared URL / cache-key / path header used by status and inspect human output, plus any
+ * command-specific extra rows, formatted as label/value lines.
+ *
+ * @param target - Normalized URL, cache key, and store roots.
+ * @param extra - Optional additional label/value rows.
+ * @param artifactPath - Optional explicit path; defaults to the write-root artifact path.
+ * @returns Formatted human-output lines.
+ */
+export declare function formatCacheTargetHeader(target: {
+    normalizedUrl: string;
+    cacheKey: string;
+    roots: {
+        writeRoot: string;
+    };
+}, extra?: HumanField[], artifactPath?: string): string[];
+/** Stderr tip pointing at the fetch shorthand when a URL has no cache entry. */
+export declare function cacheMissHint(cliBin: string, normalizedUrl: string): string;
+/** Visual row separator between per-URL blocks in multi-URL human output; null for single URLs. */
+export declare function batchSeparator(multi: boolean): string | null;

package/dist/lib/cache-view.js

@@ -0,0 +1,30 @@
+import { colors } from './color.js';
+import { formatHumanFields } from './cli-presentation.js';
+import { getArtifactPath } from './research/storage.js';
+/**
+ * Shared URL / cache-key / path header used by status and inspect human output, plus any
+ * command-specific extra rows, formatted as label/value lines.
+ *
+ * @param target - Normalized URL, cache key, and store roots.
+ * @param extra - Optional additional label/value rows.
+ * @param artifactPath - Optional explicit path; defaults to the write-root artifact path.
+ * @returns Formatted human-output lines.
+ */
+export function formatCacheTargetHeader(target, extra = [], artifactPath) {
+    const path = artifactPath ?? getArtifactPath(target.roots.writeRoot, target.cacheKey);
+    return formatHumanFields([
+        ['URL', colors.bold(target.normalizedUrl)],
+        ['Cache Key', colors.bold(target.cacheKey)],
+        ['Cache Path', colors.gray(path)],
+        ...extra,
+    ]);
+}
+/** Stderr tip pointing at the fetch shorthand when a URL has no cache entry. */
+export function cacheMissHint(cliBin, normalizedUrl) {
+    return `Cache miss — run: ${cliBin} ${normalizedUrl}`;
+}
+const BATCH_SEPARATOR_WIDTH = 40;
+/** Visual row separator between per-URL blocks in multi-URL human output; null for single URLs. */
+export function batchSeparator(multi) {
+    return multi ? '='.repeat(BATCH_SEPARATOR_WIDTH) : null;
+}

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

@@ -0,0 +1,28 @@
+/** Preflight early-exit payload used before oclif command dispatch. */
+export interface PreflightExit {
+    exitCode: number;
+    json: boolean;
+    envelope: Record<string, unknown>;
+}
+/**
+ * Print a preflight usage/error result (JSON envelope on stdout, or oclif-style human error) and exit.
+ *
+ * @param result - Exit code, JSON mode, and envelope to print.
+ * @returns Never — calls `process.exit()`.
+ */
+export declare function exitWithPreflight(result: PreflightExit): never;
+/**
+ * Command-not-found hook: print JSON error, set {@link EXIT_USAGE}, return envelope (no process.exit).
+ *
+ * @param options.command - Command id for the envelope.
+ * @param options.message - Human-readable error message.
+ * @param options.code - Stable error code.
+ * @param options.suggestions - Optional recovery tips.
+ * @returns The printed error envelope.
+ */
+export declare function writeCommandNotFoundJson(options: {
+    command: string;
+    message: string;
+    code: string;
+    suggestions?: string[];
+}): Record<string, unknown>;

package/dist/lib/cli-emit.js

@@ -0,0 +1,44 @@
+import { buildCliErrorEnvelope } from './envelope.js';
+import { EXIT_USAGE } from './cli-error-policy.js';
+const JSON_STDOUT_INDENT = 2;
+/** Print the envelope as pretty JSON on stdout (the machine-readable channel). */
+function printJsonEnvelope(envelope) {
+    console.log(JSON.stringify(envelope, null, JSON_STDOUT_INDENT));
+}
+/**
+ * Print a preflight usage/error result (JSON envelope on stdout, or oclif-style human error) and exit.
+ *
+ * @param result - Exit code, JSON mode, and envelope to print.
+ * @returns Never — calls `process.exit()`.
+ */
+export function exitWithPreflight(result) {
+    process.exitCode = result.exitCode;
+    const message = String(result.envelope.stderr ?? '');
+    if (result.json) {
+        printJsonEnvelope(result.envelope);
+    }
+    else if (message) {
+        console.error(` ›   Error: ${message.replaceAll('\n', '\n ›   ')}`);
+    }
+    process.exit();
+}
+/**
+ * Command-not-found hook: print JSON error, set {@link EXIT_USAGE}, return envelope (no process.exit).
+ *
+ * @param options.command - Command id for the envelope.
+ * @param options.message - Human-readable error message.
+ * @param options.code - Stable error code.
+ * @param options.suggestions - Optional recovery tips.
+ * @returns The printed error envelope.
+ */
+export function writeCommandNotFoundJson(options) {
+    const envelope = buildCliErrorEnvelope({
+        command: options.command,
+        message: options.message,
+        code: options.code,
+        suggestions: options.suggestions,
+    });
+    process.exitCode = EXIT_USAGE;
+    printJsonEnvelope(envelope);
+    return envelope;
+}

package/dist/lib/cli-error-policy.d.ts

@@ -0,0 +1,57 @@
+/** Process succeeded. */
+export declare const EXIT_OK = 0;
+/** Runtime / batch failure (agents treat as failed). */
+export declare const EXIT_RUNTIME_FAILURE = 1;
+/** Usage / validation failure (flags, URLs, missing args). */
+export declare const EXIT_USAGE = 2;
+/** Stale content served after failed revalidation; success envelope may still be `ok: true`. */
+export declare const EXIT_STALE_SERVED = 5;
+/**
+ * Resolves the process/envelope exit code from an oclif CLIError or plain Error.
+ *
+ * @param err - Error-like object with optional `oclif.exit` or `exitCode`.
+ * @returns Exit code; defaults to {@link EXIT_RUNTIME_FAILURE}.
+ */
+export declare function resolveExitCode(err: {
+    oclif?: {
+        exit?: number;
+    };
+    exitCode?: number;
+}): number;
+/** Normalized error fields shared by human pretty-print and the `--json` envelope. */
+export interface PreparedCliError {
+    exitCode: number;
+    code: string | undefined;
+    message: string | undefined;
+    suggestions: string[] | undefined;
+    ref: string | undefined;
+    stderr: string;
+}
+/**
+ * Normalize a thrown value into the fields humans and `--json` both need: stable code,
+ * suggestions (including fallbacks), and stderr lines that mirror human pretty-print.
+ *
+ * @param err - Thrown value (Error, CLIError, or unknown).
+ * @param options.bin - CLI binary name for help suggestions.
+ * @param options.command - Command id for help suggestions.
+ * @returns Prepared fields for exit handling and envelope construction.
+ */
+export declare function prepareCliError(err: unknown, options: {
+    bin: string;
+    command: string;
+}): PreparedCliError;
+/**
+ * Attach stable code + fallback suggestions onto a mutable error (human pretty-print path).
+ *
+ * @param err - Mutable error object receiving `code` / `suggestions`.
+ * @param options.bin - CLI binary name for help suggestions.
+ * @param options.command - Command id for help suggestions.
+ */
+export declare function enrichErrorForDisplay(err: {
+    code?: string;
+    suggestions?: string[];
+    message?: string;
+}, options: {
+    bin: string;
+    command: string;
+}): void;

package/dist/lib/cli-error-policy.js

@@ -0,0 +1,74 @@
+import { formatErrorForJson, normalizeCliErrorMessage, stableErrorCodeFrom, } from './envelope.js';
+/** Process succeeded. */
+export const EXIT_OK = 0;
+/** Runtime / batch failure (agents treat as failed). */
+export const EXIT_RUNTIME_FAILURE = 1;
+/** Usage / validation failure (flags, URLs, missing args). */
+export const EXIT_USAGE = 2;
+/** Stale content served after failed revalidation; success envelope may still be `ok: true`. */
+export const EXIT_STALE_SERVED = 5;
+/**
+ * Resolves the process/envelope exit code from an oclif CLIError or plain Error.
+ *
+ * @param err - Error-like object with optional `oclif.exit` or `exitCode`.
+ * @returns Exit code; defaults to {@link EXIT_RUNTIME_FAILURE}.
+ */
+export function resolveExitCode(err) {
+    return err?.oclif?.exit ?? err?.exitCode ?? EXIT_RUNTIME_FAILURE;
+}
+/** Default recovery tips when a throw site set a stable code but no suggestions. */
+function fallbackSuggestionsForCode(code, bin, command) {
+    const help = command === bin ? `${bin} --help` : `${bin} ${command} --help`;
+    switch (code) {
+        case 'UNKNOWN_FLAG':
+        case 'INVALID_FLAG_VALUE':
+        case 'MISSING_FLAG_VALUE':
+        case 'DUPLICATE_FLAG':
+        case 'MISSING_ARGUMENT':
+        case 'UNEXPECTED_ARGUMENT':
+            return [`Check usage: ${help}`];
+        case 'INVALID_DURATION':
+            return ['Use a whole number plus a unit, e.g. 2h, 7d, or 6m.'];
+        default:
+            return undefined;
+    }
+}
+/**
+ * Normalize a thrown value into the fields humans and `--json` both need: stable code,
+ * suggestions (including fallbacks), and stderr lines that mirror human pretty-print.
+ *
+ * @param err - Thrown value (Error, CLIError, or unknown).
+ * @param options.bin - CLI binary name for help suggestions.
+ * @param options.command - Command id for help suggestions.
+ * @returns Prepared fields for exit handling and envelope construction.
+ */
+export function prepareCliError(err, options) {
+    const e = err;
+    const exitCode = resolveExitCode(e);
+    const code = stableErrorCodeFrom(e);
+    const message = typeof e?.message === 'string' ? normalizeCliErrorMessage(e.message) : undefined;
+    const suggestions = e.suggestions?.length
+        ? e.suggestions
+        : fallbackSuggestionsForCode(code, options.bin, options.command);
+    const stderr = message || code || suggestions?.length || e?.ref
+        ? formatErrorForJson({ ...e, message, code, suggestions })
+        : String(err);
+    return { exitCode, code, message, suggestions, ref: e.ref, stderr };
+}
+/**
+ * Attach stable code + fallback suggestions onto a mutable error (human pretty-print path).
+ *
+ * @param err - Mutable error object receiving `code` / `suggestions`.
+ * @param options.bin - CLI binary name for help suggestions.
+ * @param options.command - Command id for help suggestions.
+ */
+export function enrichErrorForDisplay(err, options) {
+    if (!err.code) {
+        const code = stableErrorCodeFrom(err);
+        if (code)
+            err.code = code;
+    }
+    if (err.code && !err.suggestions?.length) {
+        err.suggestions = fallbackSuggestionsForCode(err.code, options.bin, options.command);
+    }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+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

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../base-command.js';
+import { commands } from '../commands.js';
+import { valueTakingFlagTokensFromCommands } from './value-flags.js';
+/**
+ * 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.
+ */
+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

@@ -0,0 +1,41 @@
+/** Shared flag/help copy so identical flags read identically across commands. */
+export declare const CLI_FLAG_DESCRIPTIONS: {
+    readonly freshnessTierPolicy: "freshness tier policy";
+    readonly statusFreshnessTierPolicy: "freshness tier policy to evaluate; when omitted, uses the cached entry's own tier";
+    readonly fetchTtl: "TTL duration for freshness (e.g. \"2h\", \"7d\", \"6m\")";
+    readonly importTtl: "TTL duration for imported note freshness (e.g. \"2h\", \"7d\", \"6m\")";
+    readonly statusTtl: "TTL duration to evaluate freshness (e.g. \"2h\", \"7d\", \"6m\")";
+    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 (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, 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];
+/**
+ * Format one cyan-padded label/value line for human CLI output.
+ *
+ * @param label - Field label (without trailing colon).
+ * @param value - Field value.
+ * @returns A single formatted line.
+ */
+export declare function formatHumanField(label: string, value: string): string;
+/**
+ * Format many label/value lines for human CLI output.
+ *
+ * @param fields - Label/value pairs.
+ * @returns Formatted lines in the same order.
+ */
+export declare function formatHumanFields(fields: readonly HumanField[]): string[];