@taurgis/bonsai 1.0.6 → 3.0.0

package/dist/commands/status.d.ts

@@ -7,6 +7,7 @@ export default class ResearchStatus extends BaseCommand<typeof ResearchStatus> {
         description: string;
         command: string;
     }[];
+    static strict: boolean;
     static args: {
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
@@ -19,4 +20,5 @@ export default class ResearchStatus extends BaseCommand<typeof ResearchStatus> {
     /** Enrich cache-miss envelopes with the same CACHE_MISS code and suggestions as inspect. */
     protected toSuccessJson(data: unknown): Record<string, unknown>;
     run(): Promise<unknown>;
+    private checkSingleStatus;
 }

package/dist/commands/status.js

@@ -3,6 +3,7 @@ import { BaseCommand } from '../base-command.js';
 import { formatErrorForJson } from '../lib/envelope.js';
 import { getArtifactPath } from '../lib/research/storage.js';
 import { evaluateFreshness, checkMaxAgeExpired, durationFlagError, } from '../lib/research/freshness.js';
+import { colors } from '../lib/color.js';
 function resolveFreshness(cached, currentTime, ttl, maxAge) {
     const isMaxAgeExpired = maxAge ? checkMaxAgeExpired(cached, currentTime, maxAge) : false;
     return isMaxAgeExpired
@@ -32,6 +33,7 @@ export default class ResearchStatus extends BaseCommand {
             command: '<%= config.bin %> <%= command.id %> https://example.com/docs --tier volatile --ttl 2h',
         },
     ];
+    static strict = false;
     static args = {
         url: Args.string({
             required: true,
@@ -56,20 +58,23 @@ export default class ResearchStatus extends BaseCommand {
     /** 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')
+        const list = Array.isArray(data) ? data : [data];
+        const misses = list.filter((d) => d && d.status === 'miss');
+        if (misses.length === 0)
             return envelope;
-        const normalizedUrl = d.normalizedUrl ?? '';
-        const suggestions = [`Fetch and cache it first: ${this.config.bin} ${normalizedUrl}`];
+        const firstMiss = misses[0];
+        const normalizedUrl = firstMiss.normalizedUrl ?? '';
+        const suggestions = misses.map((m) => `Fetch and cache it first: ${this.config.bin} ${m.normalizedUrl}`);
         const stderr = formatErrorForJson({
-            message: `Cache miss for ${normalizedUrl}`,
+            message: `Cache miss for ${normalizedUrl}` +
+                (misses.length > 1 ? ` and ${misses.length - 1} other URLs` : ''),
             code: 'CACHE_MISS',
             suggestions,
         });
         return { ...envelope, ok: false, exitCode: 1, stderr, code: 'CACHE_MISS', suggestions };
     }
     async run() {
-        const { url } = this.args;
+        const urls = this.parsedArgv;
         const { ttl, tier, 'max-age': maxAge } = this.flags;
         // 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.
@@ -77,32 +82,59 @@ export default class ResearchStatus extends BaseCommand {
             if (msg)
                 this.error(msg, { exit: 2, code: 'INVALID_DURATION' });
         }
+        const results = [];
+        let hasMiss = false;
+        const currentTime = new Date();
+        for (const url of urls) {
+            const res = this.checkSingleStatus(url, currentTime, ttl, maxAge, urls.length > 1);
+            if (res.status === 'miss') {
+                hasMiss = true;
+            }
+            results.push(res);
+        }
+        if (hasMiss) {
+            process.exitCode = 1;
+        }
+        return urls.length === 1 ? results[0] : results;
+    }
+    checkSingleStatus(url, currentTime, ttl, maxAge, showSeparator) {
         const target = this.resolveResearchTargetOrFail(url);
         const { cacheKey, located, normalizedUrl, roots } = target;
         const cached = located?.artifact ?? null;
-        const currentTime = new Date();
-        // 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:'.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}`);
+            const statusColorMap = {
+                hit: colors.green,
+                stale: colors.yellow,
+                miss: colors.red,
+            };
+            const freshnessColorMap = {
+                fresh: colors.green,
+                stale_grace: colors.yellow,
+                stale_expired: colors.red,
+                none: colors.gray,
+            };
+            const actionColorMap = {
+                would_return_cached: colors.green,
+                would_revalidate: colors.yellow,
+                would_fetch: colors.red,
+            };
+            const statusColor = statusColorMap[result.status] || ((t) => t);
+            const freshnessColor = freshnessColorMap[result.freshness] || ((t) => t);
+            const actionColor = actionColorMap[result.action] || ((t) => t);
+            this.log(`${colors.cyan('URL:'.padEnd(25))} ${colors.bold(normalizedUrl)}`);
+            this.log(`${colors.cyan('Cache Key:'.padEnd(25))} ${colors.bold(cacheKey)}`);
+            this.log(`${colors.cyan('Cache Path:'.padEnd(25))} ${colors.gray(artifactPath)}`);
+            this.log(`${colors.cyan('Status:'.padEnd(25))} ${statusColor(result.status)}`);
+            this.log(`${colors.cyan('Freshness:'.padEnd(25))} ${freshnessColor(result.freshness)}`);
+            this.log(`${colors.cyan('Action:'.padEnd(25))} ${actionColor(result.action)}`);
+            if (showSeparator) {
+                this.log('-'.repeat(40));
             }
-            process.exitCode = 1;
+        }
+        if (result.status === 'miss' && !this.jsonEnabled()) {
+            this.warn(`Cache miss — run: ${this.config.bin} ${normalizedUrl}`);
         }
         return {
             cacheKey,

package/dist/commands.d.ts

@@ -8,7 +8,6 @@ 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 StatusCommand from './commands/status.js';
 export declare const commands: {
     fetch: typeof FetchCommand;
@@ -16,7 +15,6 @@ export declare const commands: {
     inspect: typeof InspectCommand;
     list: typeof ListCommand;
     prune: typeof PruneCommand;
-    search: typeof SearchCommand;
     status: typeof StatusCommand;
     config: typeof ConfigIndex;
     'config:get': typeof ConfigGet;

package/dist/commands.js

@@ -8,7 +8,6 @@ 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 StatusCommand from './commands/status.js';
 export const commands = {
     fetch: FetchCommand,
@@ -16,7 +15,6 @@ export const commands = {
     inspect: InspectCommand,
     list: ListCommand,
     prune: PruneCommand,
-    search: SearchCommand,
     status: StatusCommand,
     config: ConfigIndex,
     'config:get': ConfigGet,

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

@@ -1,4 +1,10 @@
-import { type Hook } from '@oclif/core';
+import { type Hook, type Interfaces } from '@oclif/core';
+export declare function buildCommandNotFoundDetails(id: string, argv: string[] | undefined, config: Interfaces.Config): {
+    code: 'COMMAND_NOT_FOUND' | 'MISSING_URL_SCHEME' | 'UNEXPECTED_ARGUMENT';
+    command: string;
+    jsonMode: boolean;
+    message: string;
+};
 /**
  * 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

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

@@ -1,27 +1,24 @@
 import { toConfiguredId } from '@oclif/core';
-import { closestMatch } from '../../lib/text.js';
+import { closestMatch, maxFuzzyDistance } 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;
-}
+import { looksLikeSchemelessUrl } from '../../lib/research/url.js';
 /**
  * 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
+ * into one colon-delimited id, so `bonsai lisst extra` arrives as `lisst:extra`. 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
+ * `lisst:extra` resolves to nothing, but its prefix `lisst` resolves to `list`. 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));
+        const suggestion = closestMatch(attempted, visibleIds, maxFuzzyDistance(attempted));
+        if (suggestion === attempted &&
+            n < segments.length &&
+            visibleIds.some((id) => id.startsWith(`${attempted}:`))) {
+            continue;
+        }
         if (suggestion)
             return { suggestion, commandSegments: n };
     }
@@ -38,30 +35,35 @@ function topicChainLength(segments, config) {
         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;
+function exactZeroArgCommandPrefix(segments, visibleIds, config) {
+    for (let n = segments.length - 1; n >= 1; n--) {
+        const candidate = segments.slice(0, n).join(':');
+        if (!visibleIds.includes(candidate))
+            continue;
+        if (visibleIds.some((id) => id.startsWith(`${candidate}:`)))
+            continue;
+        const command = config.commands.find((entry) => entry.id === candidate);
+        const args = Object.keys(command?.args ?? {});
+        if (args.length > 0)
+            continue;
+        const extra = segments[n];
+        if (extra === undefined)
+            continue;
+        return { commandId: candidate, extra };
+    }
+    return null;
+}
 /**
  * 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.
+ * segment becomes a non-numeric port), so neither is misread as a URL. The same domain-shape test
+ * powers normalizeUrl's "missing scheme" hint, so the two entry paths stay in lockstep.
  */
 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;
+    return looksLikeSchemelessUrl(id) ? id : null;
 }
 function isJsonMode(argv) {
     return argv?.includes('--json') ?? false;
@@ -79,44 +81,67 @@ function emitJsonError(command, message, code) {
     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));
+export function buildCommandNotFoundDetails(id, argv, config) {
+    const hiddenIds = new Set(config.commands.filter((c) => c.hidden).map((c) => c.id));
+    const visibleIds = config.commandIDs.filter((commandId) => !hiddenIds.has(commandId));
     // 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);
+    const bareUrl = bareUrlInput(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 });
+        return {
+            code: 'MISSING_URL_SCHEME',
+            command: bareUrl,
+            jsonMode: isJsonMode(argv),
+            message: [
+                `${bareUrl} is not a ${config.bin} command.`,
+                `Run ${config.bin} help for a list of available commands.`,
+                `Did you mean ${config.bin} https://${bareUrl}? URLs need an http:// or https:// scheme.`,
+            ].join('\n'),
+        };
+    }
+    const segments = id.split(':');
+    const unexpected = exactZeroArgCommandPrefix(segments, visibleIds, config);
+    if (unexpected) {
+        const command = toConfiguredId(unexpected.commandId, config);
+        return {
+            code: 'UNEXPECTED_ARGUMENT',
+            command,
+            jsonMode: isJsonMode(argv),
+            message: [
+                `Unexpected argument: ${unexpected.extra}`,
+                `Run ${config.bin} ${command} --help for usage.`,
+            ].join('\n'),
+        };
     }
-    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);
+    const displaySegments = commandSegments || topicChainLength(segments, config);
+    const attempted = toConfiguredId(segments.slice(0, displaySegments).join(':'), 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.`);
+    const lines = [`${attempted} is not a ${config.bin} command.`];
+    lines.push(`Run ${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 });
+        lines.push(`Did you mean ${toConfiguredId(suggestion, config)}?`);
+    return {
+        code: 'COMMAND_NOT_FOUND',
+        command: attempted,
+        jsonMode: isJsonMode(argv),
+        message: lines.join('\n'),
+    };
+}
+/**
+ * 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 details = buildCommandNotFoundDetails(opts.id, opts.argv, opts.config);
+    if (details.jsonMode)
+        return emitJsonError(details.command, details.message, details.code);
+    this.error(details.message, { exit: 2, code: details.code });
 };
 export default hook;

package/dist/lib/argv.js

@@ -15,6 +15,29 @@ function missingUsageJsonExit() {
         }),
     };
 }
+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) {
@@ -37,13 +60,31 @@ export function normalizeArgv(rawArgv) {
     }
     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];
+    // 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]);
+    if (rootFetchShape) {
+        const url = core[firstNonFlagArgIndex];
+        core = [
+            'fetch',
+            url,
+            ...core.slice(0, firstNonFlagArgIndex),
+            ...core.slice(firstNonFlagArgIndex + 1),
+        ];
     }
     if (helpRequested)
         core.push('--help');
@@ -51,3 +92,6 @@ export function normalizeArgv(rawArgv) {
         core.push('--json');
     return { argv: core };
 }
+function looksLikeUrl(arg) {
+    return arg.includes('://') || /^[a-z][a-z0-9+.-]*:/i.test(arg);
+}

package/dist/lib/color.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether ANSI color should be emitted, per the clig.dev / no-color.org rules:
+ * - `FORCE_COLOR` (set to any value other than an explicit off) forces color on, ignoring detection.
+ * - `NO_COLOR` set to a non-empty value disables color, regardless of that value. An empty
+ *   `NO_COLOR` is treated as unset (the spec keys off "present and not empty").
+ * - `TERM=dumb` cannot render ANSI, so color is disabled.
+ * - Otherwise color follows whether stdout is an interactive terminal.
+ * See https://clig.dev/#output and https://no-color.org/.
+ */
+export declare function isColorEnabled(): boolean;
+export declare function color(text: string, colorCode: string): string;
+export declare const colors: {
+    bold: (t: string) => string;
+    green: (t: string) => string;
+    yellow: (t: string) => string;
+    red: (t: string) => string;
+    cyan: (t: string) => string;
+    gray: (t: string) => string;
+    magenta: (t: string) => string;
+};

package/dist/lib/color.js

@@ -0,0 +1,36 @@
+/**
+ * Whether ANSI color should be emitted, per the clig.dev / no-color.org rules:
+ * - `FORCE_COLOR` (set to any value other than an explicit off) forces color on, ignoring detection.
+ * - `NO_COLOR` set to a non-empty value disables color, regardless of that value. An empty
+ *   `NO_COLOR` is treated as unset (the spec keys off "present and not empty").
+ * - `TERM=dumb` cannot render ANSI, so color is disabled.
+ * - Otherwise color follows whether stdout is an interactive terminal.
+ * See https://clig.dev/#output and https://no-color.org/.
+ */
+export function isColorEnabled() {
+    if (typeof process === 'undefined' || !process.env)
+        return false;
+    const env = process.env;
+    const force = env.FORCE_COLOR;
+    if (force !== undefined && force !== '' && force !== '0' && force !== 'false')
+        return true;
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== '')
+        return false;
+    if (env.TERM === 'dumb')
+        return false;
+    return Boolean(process.stdout && process.stdout.isTTY);
+}
+export function color(text, colorCode) {
+    if (!isColorEnabled())
+        return text;
+    return `${colorCode}${text}\x1b[0m`;
+}
+export const colors = {
+    bold: (t) => color(t, '\x1b[1m'),
+    green: (t) => color(t, '\x1b[32m'),
+    yellow: (t) => color(t, '\x1b[33m'),
+    red: (t) => color(t, '\x1b[31m'),
+    cyan: (t) => color(t, '\x1b[36m'),
+    gray: (t) => color(t, '\x1b[90m'),
+    magenta: (t) => color(t, '\x1b[35m'),
+};

package/dist/lib/envelope.js

@@ -13,9 +13,15 @@ export function stableErrorCodeFrom(err) {
             return 'UNKNOWN_FLAG';
         case 'UnexpectedArgsError':
             return 'UNEXPECTED_ARGUMENT';
-        default:
-            return undefined;
     }
+    // A flag supplied without its value throws a plain CLIError with no dedicated class to switch on,
+    // so it would otherwise reach agents with no stable code. oclif phrases it two ways: "expects a
+    // value" for a free-form flag, "expects one of these values: …" for an options-constrained flag.
+    if (typeof e?.message === 'string' &&
+        /^Flag --\S+ expects (a value$|one of these values:)/.test(e.message)) {
+        return 'MISSING_FLAG_VALUE';
+    }
+    return undefined;
 }
 /** Strip oclif's generic help suffix from JSON stderr — agents already have structured codes. */
 export function normalizeCliErrorMessage(message) {

package/dist/lib/help-preflight.d.ts

@@ -0,0 +1,15 @@
+type UnknownHelpResult = {
+    exitCode: 2;
+    kind: 'human';
+    message: string;
+} | {
+    envelope: Record<string, unknown>;
+    exitCode: 2;
+    kind: 'json';
+};
+/**
+ * oclif resolves help before its command_not_found hook, so `bonsai config gett --help` otherwise
+ * falls back to a terse framework error. Catch that narrow case and reuse the normal typo guidance.
+ */
+export declare function tryUnknownHelpOutput(argv: readonly string[], root: string): Promise<UnknownHelpResult | null>;
+export {};

package/dist/lib/help-preflight.js

@@ -0,0 +1,81 @@
+import { Config } from '@oclif/core';
+import { buildEnvelope } from './envelope.js';
+import { buildCommandNotFoundDetails } from '../hooks/command-not-found/suggest.js';
+function commandId(parts) {
+    return parts.join(':');
+}
+function positionalTokens(argv) {
+    const tokens = [];
+    for (const arg of argv) {
+        if (arg === '--')
+            break;
+        if (arg === '--help' || arg === '--json')
+            continue;
+        if (arg.startsWith('-'))
+            continue;
+        tokens.push(arg);
+    }
+    return tokens;
+}
+function commandPrefixLength(tokens, config) {
+    let longest = 0;
+    for (let n = 1; n <= tokens.length; n++) {
+        if (config.commandIDs.includes(commandId(tokens.slice(0, n))))
+            longest = n;
+    }
+    return longest;
+}
+function branchPrefixLength(tokens, config) {
+    let longest = 0;
+    for (let n = 1; n <= tokens.length; n++) {
+        const id = commandId(tokens.slice(0, n));
+        if (config.commandIDs.some((command) => command.startsWith(`${id}:`)))
+            longest = n;
+    }
+    return longest;
+}
+function hasValidHelpTarget(tokens, config) {
+    const commandLength = commandPrefixLength(tokens, config);
+    const branchLength = branchPrefixLength(tokens, config);
+    if (commandLength === tokens.length || branchLength === tokens.length)
+        return true;
+    if (branchLength > 0 && tokens.length > branchLength) {
+        return commandLength > branchLength;
+    }
+    return commandLength > 0;
+}
+/**
+ * oclif resolves help before its command_not_found hook, so `bonsai config gett --help` otherwise
+ * falls back to a terse framework error. Catch that narrow case and reuse the normal typo guidance.
+ */
+export async function tryUnknownHelpOutput(argv, root) {
+    if (!argv.includes('--help'))
+        return null;
+    const tokens = positionalTokens(argv);
+    if (tokens.length === 0)
+        return null;
+    const config = await Config.load({ root });
+    if (hasValidHelpTarget(tokens, config))
+        return null;
+    const attemptedId = commandId(tokens);
+    const details = buildCommandNotFoundDetails(attemptedId, [...argv], config);
+    if (argv.includes('--json')) {
+        return {
+            kind: 'json',
+            exitCode: 2,
+            envelope: buildEnvelope({
+                command: details.command,
+                ok: false,
+                exitCode: 2,
+                stderr: `${details.message}\nCode: ${details.code}`,
+                data: null,
+                code: details.code,
+            }),
+        };
+    }
+    return {
+        kind: 'human',
+        exitCode: 2,
+        message: `${details.message}\nCode: ${details.code}`,
+    };
+}

package/dist/lib/limit-flag.d.ts

@@ -0,0 +1 @@
+export declare function limitFlag(max: number, defaultValue: number, description: string): import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;

package/dist/lib/limit-flag.js

@@ -0,0 +1,24 @@
+import { Errors, Flags } from '@oclif/core';
+export function limitFlag(max, defaultValue, description) {
+    return Flags.custom({
+        parse: async (input) => {
+            if (!/^\d+$/.test(input)) {
+                throw new Errors.CLIError(`Limit must be an integer between 1 and ${max}.`, {
+                    exit: 2,
+                    code: 'INVALID_LIMIT',
+                });
+            }
+            const value = Number(input);
+            if (value < 1 || value > max) {
+                throw new Errors.CLIError(`Limit must be between 1 and ${max}.`, {
+                    exit: 2,
+                    code: 'INVALID_LIMIT',
+                });
+            }
+            return value;
+        },
+    })({
+        default: defaultValue,
+        description,
+    });
+}