@taurgis/bonsai 1.0.4 → 1.0.6

package/dist/commands/status.js

@@ -1,8 +1,8 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
+import { formatErrorForJson } from '../lib/envelope.js';
 import { getArtifactPath } from '../lib/research/storage.js';
-import { evaluateFreshness, checkMaxAgeExpired } from '../lib/research/freshness.js';
-import { resolveResearchTarget } from '../lib/research/resolve-target.js';
+import { evaluateFreshness, checkMaxAgeExpired, durationFlagError, } from '../lib/research/freshness.js';
 function resolveFreshness(cached, currentTime, ttl, maxAge) {
     const isMaxAgeExpired = maxAge ? checkMaxAgeExpired(cached, currentTime, maxAge) : false;
     return isMaxAgeExpired
@@ -11,7 +11,7 @@ function resolveFreshness(cached, currentTime, ttl, maxAge) {
 }
 function describeCacheStatus(cached, currentTime, ttl, maxAge) {
     if (!cached) {
-        return { status: 'miss', freshness: 'stale_expired', action: 'would_fetch' };
+        return { status: 'miss', freshness: 'none', action: 'would_fetch' };
     }
     const freshness = resolveFreshness(cached, currentTime, ttl, maxAge);
     return freshness === 'fresh'
@@ -22,65 +22,92 @@ export default class ResearchStatus extends BaseCommand {
     static id = 'status';
     static summary = 'Check the cache status of a URL without fetching or writing.';
     static description = 'Reports whether the URL is cached, its freshness state, and what action (fetch, revalidate, or cached return) the root fetch command would take.';
+    static examples = [
+        {
+            description: 'check if a URL is already in the cache',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs',
+        },
+        {
+            description: 'check status against a specific freshness tier and TTL',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs --tier volatile --ttl 2h',
+        },
+    ];
     static args = {
         url: Args.string({
             required: true,
-            description: 'The URL to check.',
+            description: 'the URL to check',
         }),
     };
     static flags = {
         tier: Flags.option({
-            description: 'Freshness tier policy to evaluate against.',
+            description: 'freshness tier policy to evaluate against',
             options: ['stable', 'standard', 'volatile'],
             default: 'standard',
         })(),
         ttl: Flags.string({
             char: 'l',
-            description: 'Custom TTL duration to evaluate against (e.g. "2h", "7d").',
+            description: 'custom TTL duration to evaluate against (e.g. "2h", "7d")',
         }),
         'max-age': Flags.string({
-            description: 'Maximum age of cache to accept (e.g. "1d", "30d").',
+            description: 'maximum age of cache to accept (e.g. "1d", "30d")',
         }),
     };
     static stdoutIsPrimaryData = true;
+    /** Enrich cache-miss envelopes with the same CACHE_MISS code and suggestions as inspect. */
+    toSuccessJson(data) {
+        const envelope = super.toSuccessJson(data);
+        const d = data;
+        if (d?.status !== 'miss')
+            return envelope;
+        const normalizedUrl = d.normalizedUrl ?? '';
+        const suggestions = [`Fetch and cache it first: ${this.config.bin} ${normalizedUrl}`];
+        const stderr = formatErrorForJson({
+            message: `Cache miss for ${normalizedUrl}`,
+            code: 'CACHE_MISS',
+            suggestions,
+        });
+        return { ...envelope, ok: false, exitCode: 1, stderr, code: 'CACHE_MISS', suggestions };
+    }
     async run() {
         const { url } = this.args;
         const { ttl, tier, 'max-age': maxAge } = this.flags;
-        let target;
-        try {
-            target = resolveResearchTarget({
-                configDir: this.config.configDir,
-                cwd: process.cwd(),
-                dataDir: this.config.dataDir,
-                url,
-            });
-        }
-        catch (err) {
-            this.error(`Invalid URL: ${err.message}`, { exit: 2 });
+        // Validate the duration flags up front so a malformed value reports the exact flag that is
+        // wrong, rather than later surfacing as a misattributed parse failure.
+        for (const msg of [durationFlagError('--ttl', ttl), durationFlagError('--max-age', maxAge)]) {
+            if (msg)
+                this.error(msg, { exit: 2, code: 'INVALID_DURATION' });
         }
+        const target = this.resolveResearchTargetOrFail(url);
         const { cacheKey, located, normalizedUrl, roots } = target;
         const cached = located?.artifact ?? null;
         const currentTime = new Date();
-        let result;
-        try {
-            result = describeCacheStatus(cached, currentTime, ttl, maxAge);
-        }
-        catch (err) {
-            this.error(`Invalid max-age: ${err.message}`, { exit: 2 });
-        }
+        // Both duration flags were validated above, so freshness resolution cannot throw on a parse error.
+        const result = describeCacheStatus(cached, currentTime, ttl, maxAge);
         // On a hit, report where it actually lives; on a miss, where a fetch would write it.
         const artifactPath = located?.path ?? getArtifactPath(roots.writeRoot, cacheKey);
         if (!this.jsonEnabled()) {
-            this.log(`URL: ${normalizedUrl}`);
-            this.log(`Cache Key: ${cacheKey}`);
-            this.log(`Cache Path: ${artifactPath}`);
-            this.log(`Status: ${result.status}`);
-            this.log(`Freshness: ${result.freshness}`);
-            this.log(`Action: ${result.action}`);
+            this.log(`${'URL:'.padEnd(25)} ${normalizedUrl}`);
+            this.log(`${'Cache Key:'.padEnd(25)} ${cacheKey}`);
+            this.log(`${'Cache Path:'.padEnd(25)} ${artifactPath}`);
+            this.log(`${'Status:'.padEnd(25)} ${result.status}`);
+            this.log(`${'Freshness:'.padEnd(25)} ${result.freshness}`);
+            this.log(`${'Action:'.padEnd(25)} ${result.action}`);
+        }
+        // Align with inspect's CACHE_MISS contract: a miss is actionable, not a usage error. Exit 1
+        // lets scripts branch on $? while JSON still returns the structured status payload. Unlike
+        // inspect, we do not throw here — status must always return structured data even on a miss.
+        if (result.status === 'miss') {
+            // Human mode: actionable hint on stderr. JSON mode: same info lives in the envelope (see
+            // toSuccessJson) so agents get code/suggestions without parsing warn() line wraps.
+            if (!this.jsonEnabled()) {
+                this.warn(`Cache miss — run: ${this.config.bin} ${normalizedUrl}`);
+            }
+            process.exitCode = 1;
         }
         return {
             cacheKey,
             cachePath: artifactPath,
+            normalizedUrl,
             status: result.status,
             freshness: result.freshness,
             action: result.action,

package/dist/commands.d.ts

@@ -1,4 +1,5 @@
 import ConfigGet from './commands/config/get.js';
+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';
@@ -17,6 +18,7 @@ export declare const commands: {
     prune: typeof PruneCommand;
     search: typeof SearchCommand;
     status: typeof StatusCommand;
+    config: typeof ConfigIndex;
     'config:get': typeof ConfigGet;
     'config:list': typeof ConfigList;
     'config:set': typeof ConfigSet;

package/dist/commands.js

@@ -1,4 +1,5 @@
 import ConfigGet from './commands/config/get.js';
+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';
@@ -17,6 +18,7 @@ export const commands = {
     prune: PruneCommand,
     search: SearchCommand,
     status: StatusCommand,
+    config: ConfigIndex,
     'config:get': ConfigGet,
     'config:list': ConfigList,
     'config:set': ConfigSet,

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

@@ -0,0 +1,9 @@
+import { type Hook } from '@oclif/core';
+/**
+ * Typo-aware "command not found" handler. oclif fires this before printing its own terse error;
+ * throwing here (via `this.error`) replaces that default with a more helpful message. A correction
+ * is offered only when the nearest command is a close match, and it is never auto-run — the user
+ * re-runs the corrected command themselves, so they learn the right syntax (clig.dev guidance).
+ */
+declare const hook: Hook<'command_not_found'>;
+export default hook;

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

@@ -0,0 +1,122 @@
+import { toConfiguredId } from '@oclif/core';
+import { closestMatch } from '../../lib/text.js';
+import { buildEnvelope, formatErrorForJson } from '../../lib/envelope.js';
+// Nearest command must be close enough to be useful. A fixed threshold of 3 is too generous for
+// very short inputs (`wat` should not suggest `list`), while still reasonable for longer topic ids.
+function maxSuggestionDistance(input) {
+    if (input.length <= 3)
+        return 1;
+    if (input.length <= 5)
+        return 2;
+    return 3;
+}
+/**
+ * The nearest visible command to a typo, plus how many leading segments of the attempted id name
+ * the command. With `topicSeparator: ' '`, oclif folds every leading token of an unknown command
+ * into one colon-delimited id, so `bonsai serch hello` arrives as `serch:hello`. Matching that whole
+ * string never finds a short command, so walk prefixes longest→shortest and suggest off the closest:
+ * `serch:hello` resolves to nothing, but its prefix `serch` resolves to `search`. The matched prefix
+ * length doubles as the command-segment count, so a folded-in positional arg is dropped from display.
+ */
+function findSuggestion(segments, visibleIds) {
+    for (let n = segments.length; n >= 1; n--) {
+        const attempted = segments.slice(0, n).join(':');
+        const suggestion = closestMatch(attempted, visibleIds, maxSuggestionDistance(attempted));
+        if (suggestion)
+            return { suggestion, commandSegments: n };
+    }
+    return { suggestion: null, commandSegments: 0 };
+}
+/**
+ * How many leading segments name the command when no suggestion exists: the known-topic chain plus
+ * the first unknown segment. Keeps `config frobnicate` from rendering as the misleading bare `config`
+ * (a real topic) while still dropping a positional arg from `frobnicate banana`.
+ */
+function topicChainLength(segments, config) {
+    let i = 0;
+    while (i < segments.length - 1 && config.findTopic(segments.slice(0, i + 1).join(':')))
+        i++;
+    return i + 1;
+}
+// Dot-separated, non-empty labels: a real domain (`docs.nestjs.com`) or IPv4 (`192.168.1.1`). The
+// URL parser also accepts a leading-dot filename (`.env`) or a relative path (`./x`) as a "host",
+// whose suggestion would be a nonsense `https://.env`; requiring well-formed labels rejects those.
+// Anchored with no overlapping quantifiers, so it is ReDoS-safe on the (already length-bounded) host.
+const DOMAIN_OR_IPV4 = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i;
+/**
+ * The input as-typed when it looks like a URL missing its scheme (`example.com`,
+ * `docs.nestjs.com/guide`), else null. `bonsai <url>` is the headline command, but bin/cli.mjs only
+ * routes args carrying a `://` scheme to the fetch shorthand — so a scheme-less URL falls through to
+ * `command_not_found`. A domain-shaped host separates a forgotten-scheme URL from an ordinary command
+ * typo: `statuss` has no dot and never matches, while `config:frobnicate` fails to parse (the second
+ * segment becomes a non-numeric port), so neither is misread as a URL.
+ */
+function bareUrlInput(id) {
+    if (id.includes('://'))
+        return null;
+    let hostname;
+    try {
+        hostname = new URL(`https://${id}`).hostname;
+    }
+    catch {
+        return null;
+    }
+    return DOMAIN_OR_IPV4.test(hostname) ? id : null;
+}
+function isJsonMode(argv) {
+    return argv?.includes('--json') ?? false;
+}
+function emitJsonError(command, message, code) {
+    const envelope = buildEnvelope({
+        command,
+        ok: false,
+        exitCode: 2,
+        stderr: formatErrorForJson({ message, code }),
+        data: null,
+        code,
+    });
+    process.exitCode = 2;
+    console.log(JSON.stringify(envelope, null, 2));
+    return envelope;
+}
+/**
+ * Typo-aware "command not found" handler. oclif fires this before printing its own terse error;
+ * throwing here (via `this.error`) replaces that default with a more helpful message. A correction
+ * is offered only when the nearest command is a close match, and it is never auto-run — the user
+ * re-runs the corrected command themselves, so they learn the right syntax (clig.dev guidance).
+ */
+const hook = async function (opts) {
+    const hiddenIds = new Set(opts.config.commands.filter((c) => c.hidden).map((c) => c.id));
+    const visibleIds = opts.config.commandIDs.filter((id) => !hiddenIds.has(id));
+    // A scheme-less URL is the most common "not a command" mistake for this CLI, so steer the user to
+    // the `bonsai <url>` shorthand with a scheme before falling back to nearest-command matching (which
+    // never finds a command for a hostname). The correction is shown, never auto-run (clig.dev).
+    const bareUrl = bareUrlInput(opts.id);
+    if (bareUrl) {
+        const message = [
+            `${bareUrl} is not a ${opts.config.bin} command.`,
+            `Run ${opts.config.bin} help for a list of available commands.`,
+            `Did you mean ${opts.config.bin} https://${bareUrl}? URLs need an http:// or https:// scheme.`,
+        ].join('\n');
+        if (isJsonMode(opts.argv))
+            return emitJsonError(bareUrl, message, 'MISSING_URL_SCHEME');
+        this.error(message, { exit: 2 });
+    }
+    const segments = opts.id.split(':');
+    const { suggestion, commandSegments } = findSuggestion(segments, visibleIds);
+    // Show only the segments that name the command, never the positional args oclif folded into the id
+    // (which would otherwise glue the arg on and turn `://` into ` //`).
+    const displaySegments = commandSegments || topicChainLength(segments, opts.config);
+    const attempted = toConfiguredId(segments.slice(0, displaySegments).join(':'), opts.config);
+    // Order so the most actionable line lands last, where the eye rests (clig.dev): the help pointer
+    // is the floor, and a concrete "Did you mean …?" correction — when we have one — goes below it.
+    const lines = [`${attempted} is not a ${opts.config.bin} command.`];
+    lines.push(`Run ${opts.config.bin} help for a list of available commands.`);
+    if (suggestion)
+        lines.push(`Did you mean ${toConfiguredId(suggestion, opts.config)}?`);
+    const message = lines.join('\n');
+    if (isJsonMode(opts.argv))
+        return emitJsonError(attempted, message, 'COMMAND_NOT_FOUND');
+    this.error(message, { exit: 2 });
+};
+export default hook;

package/dist/lib/argv.d.ts

@@ -0,0 +1,10 @@
+export interface NormalizationResult {
+    /** The normalized argv array to set on process.argv. */
+    argv: string[];
+    /** Optional metadata indicating the shim should exit early with a JSON envelope. */
+    exitWithJson?: {
+        exitCode: number;
+        envelope: Record<string, unknown>;
+    };
+}
+export declare function normalizeArgv(rawArgv: string[]): NormalizationResult;

package/dist/lib/argv.js

@@ -0,0 +1,53 @@
+import { buildEnvelope } from './envelope.js';
+/**
+ * Normalizes process.argv (excluding Node executable and script path) so the
+ * oclif pipeline sees one consistent command structure.
+ */
+function missingUsageJsonExit() {
+    return {
+        exitCode: 2,
+        envelope: buildEnvelope({
+            command: 'bonsai',
+            ok: false,
+            exitCode: 2,
+            stderr: 'Missing URL or command. Run bonsai --help for usage.',
+            data: null,
+        }),
+    };
+}
+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(),
+        };
+    }
+    // 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
+    // dedupe repeats like `bonsai --json --json list`.
+    const jsonMode = rawArgv.includes('--json');
+    let tokens = rawArgv.filter((arg) => arg !== '--json');
+    // clig.dev: -h and --help must always work at any level.
+    tokens = tokens.map((arg) => (arg === '-h' ? '--help' : arg));
+    if (tokens[0] === 'help') {
+        tokens = [...tokens.slice(1), '--help'];
+    }
+    const helpRequested = tokens.includes('--help');
+    let core = tokens.filter((arg) => arg !== '--help');
+    const firstArg = core[0];
+    // Treat any first arg that looks like a URL (carries a scheme) 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".
+    const looksLikeUrl = firstArg != null && (firstArg.includes('://') || /^[a-z][a-z0-9+.-]*:/i.test(firstArg));
+    if (looksLikeUrl) {
+        core = ['fetch', ...core];
+    }
+    if (helpRequested)
+        core.push('--help');
+    if (jsonMode)
+        core.push('--json');
+    return { argv: core };
+}

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

@@ -1,6 +1,6 @@
 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 { resolveStorageMode, resolveSummaryLevel, parseEnvStorage, parseEnvSummary, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, type ResolveStorageInput, type ResolveSummaryInput, } from './resolve.js';
+export { resolveStorageMode, resolveSummaryLevel, parseEnvStorage, parseEnvSummary, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, type ResolveStorageInput, type ResolveSummaryInput, } from './resolve.js';
 import type { ConfigValues, ResolvedConfig, StorageMode, SummaryLevel } from './schema.js';
 /**
  * Read both config files once and resolve the effective storage mode.

package/dist/lib/config/index.js

@@ -1,6 +1,6 @@
 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 { resolveStorageMode, resolveSummaryLevel, parseEnvStorage, parseEnvSummary, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, } from './resolve.js';
+export { resolveStorageMode, resolveSummaryLevel, parseEnvStorage, parseEnvSummary, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, } from './resolve.js';
 import { readUserConfig, readProjectConfig } from './io.js';
 import { resolveStorageMode, resolveSummaryLevel } from './resolve.js';
 /**

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

@@ -2,6 +2,13 @@ import type { ConfigValues, StorageMode, SummaryLevel } from './schema.js';
 /** Scoped env override, following oclif's `<BIN>_*` env-var convention for this CLI. */
 export declare const STORAGE_ENV_VAR = "BONSAI_STORAGE";
 export declare const SUMMARY_ENV_VAR = "BONSAI_SUMMARY";
+/**
+ * Warnings for Bonsai env overrides that are set but hold an unrecognized value. Such a value is
+ * dropped during resolution (falling back to config/default), which would otherwise silently mask
+ * a typo like `BONSAI_SUMMARY=agressive`. Callers surface these on stderr so the misconfiguration
+ * is visible without breaking the run. Returns one message per offending variable, or empty.
+ */
+export declare function invalidEnvOverrideWarnings(env: Record<string, string | undefined>): string[];
 export declare function parseEnvStorage(env: Record<string, string | undefined>): StorageMode | undefined;
 export declare function parseEnvSummary(env: Record<string, string | undefined>): SummaryLevel | undefined;
 export interface ResolveStorageInput {

package/dist/lib/config/resolve.js

@@ -2,6 +2,29 @@ import { BUILT_IN_DEFAULTS, STORAGE_MODES, SUMMARY_LEVELS } from './schema.js';
 /** Scoped env override, following oclif's `<BIN>_*` env-var convention for this CLI. */
 export const STORAGE_ENV_VAR = 'BONSAI_STORAGE';
 export const SUMMARY_ENV_VAR = 'BONSAI_SUMMARY';
+/**
+ * Warnings for Bonsai env overrides that are set but hold an unrecognized value. Such a value is
+ * dropped during resolution (falling back to config/default), which would otherwise silently mask
+ * a typo like `BONSAI_SUMMARY=agressive`. Callers surface these on stderr so the misconfiguration
+ * is visible without breaking the run. Returns one message per offending variable, or empty.
+ */
+export function invalidEnvOverrideWarnings(env) {
+    const checks = [
+        [STORAGE_ENV_VAR, STORAGE_MODES],
+        [SUMMARY_ENV_VAR, SUMMARY_LEVELS],
+    ];
+    const warnings = [];
+    for (const [name, valid] of checks) {
+        // After trim, an empty/whitespace-only value is falsy and treated as "unset" (no warning),
+        // matching parseEnv*; matching is case-sensitive, so a wrong-case value is invalid and warns.
+        const raw = env[name]?.trim();
+        if (raw && !valid.includes(raw)) {
+            warnings.push(`Ignoring ${name}="${raw}": not one of ${valid.join(', ')}. ` +
+                `Using the configured value or default instead.`);
+        }
+    }
+    return warnings;
+}
 export function parseEnvStorage(env) {
     const raw = env[STORAGE_ENV_VAR]?.trim();
     return STORAGE_MODES.includes(raw ?? '')

package/dist/lib/envelope.d.ts

@@ -0,0 +1,36 @@
+/** Fields oclif attaches to CLIError that human pretty-print surfaces but JSON mode must mirror. */
+export interface CliErrorShape {
+    message?: string;
+    code?: string;
+    suggestions?: string[];
+    ref?: string;
+}
+/** Map oclif parse-time errors to stable Bonsai codes when the throw site did not set one. */
+export declare function stableErrorCodeFrom(err: unknown): string | undefined;
+/** Strip oclif's generic help suffix from JSON stderr — agents already have structured codes. */
+export declare function normalizeCliErrorMessage(message: string): string;
+export interface EnvelopeParts {
+    command: string;
+    ok: boolean;
+    exitCode: number;
+    stderr: string;
+    data: unknown;
+    /** Stable machine-readable error code when the failure is a CLIError with `code`. */
+    code?: string;
+    suggestions?: string[];
+    ref?: string;
+}
+/**
+ * Formats a CLI error for the JSON envelope `stderr` field — same lines as human pretty-print,
+ * without ANSI or the leading "Error:" prefix (the message is already the primary line).
+ */
+export declare function formatErrorForJson(err: CliErrorShape): string;
+/**
+ * Builds the standard Bonsai CLI JSON envelope structure.
+ * This is the single source of truth for the output envelope schema.
+ */
+export declare function buildEnvelope(parts: EnvelopeParts): Record<string, unknown>;
+/**
+ * Formats a JSON envelope to a string with indentation.
+ */
+export declare function formatEnvelope(parts: EnvelopeParts): string;

package/dist/lib/envelope.js

@@ -0,0 +1,76 @@
+/** Map oclif parse-time errors to stable Bonsai codes when the throw site did not set one. */
+export function stableErrorCodeFrom(err) {
+    const e = err;
+    if (typeof e?.code === 'string' && e.code)
+        return e.code;
+    switch (e?.constructor?.name) {
+        case 'RequiredArgsError':
+            return 'MISSING_ARGUMENT';
+        case 'FlagInvalidOptionError':
+        case 'ArgInvalidOptionError':
+            return 'INVALID_FLAG_VALUE';
+        case 'NonExistentFlagsError':
+            return 'UNKNOWN_FLAG';
+        case 'UnexpectedArgsError':
+            return 'UNEXPECTED_ARGUMENT';
+        default:
+            return undefined;
+    }
+}
+/** Strip oclif's generic help suffix from JSON stderr — agents already have structured codes. */
+export function normalizeCliErrorMessage(message) {
+    const suffix = '\nSee more help with --help';
+    return message.endsWith(suffix) ? message.slice(0, -suffix.length) : message;
+}
+/**
+ * Formats a CLI error for the JSON envelope `stderr` field — same lines as human pretty-print,
+ * without ANSI or the leading "Error:" prefix (the message is already the primary line).
+ */
+export function formatErrorForJson(err) {
+    const lines = [];
+    if (err.message)
+        lines.push(err.message);
+    if (err.code)
+        lines.push(`Code: ${err.code}`);
+    if (err.suggestions?.length) {
+        if (err.suggestions.length === 1) {
+            lines.push(`Try this: ${err.suggestions[0]}`);
+        }
+        else {
+            lines.push('Try this:');
+            for (const suggestion of err.suggestions)
+                lines.push(`* ${suggestion}`);
+        }
+    }
+    if (err.ref)
+        lines.push(`Reference: ${err.ref}`);
+    return lines.join('\n');
+}
+/**
+ * Builds the standard Bonsai CLI JSON envelope structure.
+ * This is the single source of truth for the output envelope schema.
+ */
+export function buildEnvelope(parts) {
+    const envelope = {
+        schemaVersion: 1,
+        command: parts.command,
+        ok: parts.ok,
+        exitCode: parts.exitCode,
+        stdout: '',
+        stderr: parts.stderr,
+        data: parts.data,
+    };
+    if (parts.code)
+        envelope.code = parts.code;
+    if (parts.suggestions?.length)
+        envelope.suggestions = parts.suggestions;
+    if (parts.ref)
+        envelope.ref = parts.ref;
+    return envelope;
+}
+/**
+ * Formats a JSON envelope to a string with indentation.
+ */
+export function formatEnvelope(parts) {
+    return JSON.stringify(buildEnvelope(parts), null, 2);
+}

package/dist/lib/json-meta.d.ts

@@ -0,0 +1,10 @@
+/** True when argv asks for help or version together with --json. */
+export declare function isJsonMetaRequest(argv: readonly string[]): boolean;
+/**
+ * When `--json` is combined with `--help` or `--version`, oclif would print human text to stdout.
+ * Render the same content inside the standard Bonsai JSON envelope instead.
+ */
+export declare function tryJsonMetaOutput(argv: readonly string[], root: string): Promise<{
+    exitCode: number;
+    envelope: Record<string, unknown>;
+} | null>;

package/dist/lib/json-meta.js

@@ -0,0 +1,98 @@
+import { Config, Help, toConfiguredId } from '@oclif/core';
+import { buildEnvelope } from './envelope.js';
+/** Strip ANSI color codes so JSON help text stays machine-stable. */
+function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\x1b\[[0-9;]*m/g, '');
+}
+/** True when argv asks for help or version together with --json. */
+export function isJsonMetaRequest(argv) {
+    if (!argv.includes('--json'))
+        return false;
+    return argv.includes('--help') || argv.includes('--version');
+}
+class CaptureHelp extends Help {
+    lines = [];
+    log(...args) {
+        for (const line of args) {
+            // oclif emits section separators as log(''); drop empties so data.help stays compact.
+            if (line)
+                this.lines.push(line);
+        }
+    }
+}
+function helpSubject(argv) {
+    for (const arg of argv) {
+        if (arg === '--' || arg === '--help' || arg === 'help')
+            continue;
+        if (arg.startsWith('-'))
+            return;
+        return arg;
+    }
+    return undefined;
+}
+function envelopeCommandId(config, argv) {
+    const subject = helpSubject(argv);
+    if (!subject)
+        return config.bin;
+    const command = config.findCommand(subject);
+    if (command?.id)
+        return toConfiguredId(command.id, config);
+    const topic = config.findTopic(subject);
+    if (topic)
+        return topic.name;
+    return subject;
+}
+/**
+ * When `--json` is combined with `--help` or `--version`, oclif would print human text to stdout.
+ * Render the same content inside the standard Bonsai JSON envelope instead.
+ */
+export async function tryJsonMetaOutput(argv, root) {
+    if (!isJsonMetaRequest(argv))
+        return null;
+    try {
+        const config = await Config.load({ root });
+        if (argv.includes('--version')) {
+            return {
+                exitCode: 0,
+                envelope: buildEnvelope({
+                    command: config.bin,
+                    ok: true,
+                    exitCode: 0,
+                    stderr: '',
+                    data: {
+                        version: config.version,
+                        userAgent: config.userAgent,
+                    },
+                }),
+            };
+        }
+        const help = new CaptureHelp(config, config.pjson.oclif?.helpOptions ?? {});
+        await help.showHelp([...argv]);
+        const helpText = stripAnsi(help.lines.join('\n').trimEnd());
+        return {
+            exitCode: 0,
+            envelope: buildEnvelope({
+                command: envelopeCommandId(config, argv),
+                ok: true,
+                exitCode: 0,
+                stderr: '',
+                data: { help: helpText },
+            }),
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            exitCode: 1,
+            envelope: buildEnvelope({
+                command: 'bonsai',
+                ok: false,
+                exitCode: 1,
+                stderr: message,
+                data: null,
+                code: 'META_RENDER_FAILED',
+            }),
+        };
+    }
+}