@taurgis/bonsai 3.1.0 → 3.2.2

package/dist/lib/config/resolve.js

@@ -2,6 +2,26 @@ 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';
+/** Two names for the same safety switch: `PLAN_MODE` mirrors agent-harness "plan mode" terminology. */
+export const READ_ONLY_ENV_VAR = 'BONSAI_READ_ONLY';
+export const PLAN_MODE_ENV_VAR = 'BONSAI_PLAN_MODE';
+const BOOLEAN_TRUE_VALUES = ['1', 'true', 'yes'];
+const BOOLEAN_FALSE_VALUES = ['0', 'false', 'no'];
+/**
+ * Parses a boolean-ish env value. Empty/unset is `undefined` (not present); an unrecognized
+ * non-empty value is also `undefined` (invalid — see {@link invalidEnvOverrideWarnings}), so a
+ * typo never silently reads as `true`.
+ */
+export function parseEnvBoolean(raw) {
+    const v = raw?.trim().toLowerCase();
+    if (!v)
+        return undefined;
+    if (BOOLEAN_TRUE_VALUES.includes(v))
+        return true;
+    if (BOOLEAN_FALSE_VALUES.includes(v))
+        return false;
+    return undefined;
+}
 /**
  * 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
@@ -9,18 +29,36 @@ export const SUMMARY_ENV_VAR = 'BONSAI_SUMMARY';
  * is visible without breaking the run. Returns one message per offending variable, or empty.
  */
 export function invalidEnvOverrideWarnings(env) {
+    // Each check names the var, how to tell a value is invalid, and the hint to show when it is.
     const checks = [
-        [STORAGE_ENV_VAR, STORAGE_MODES],
-        [SUMMARY_ENV_VAR, SUMMARY_LEVELS],
+        [
+            STORAGE_ENV_VAR,
+            (raw) => STORAGE_MODES.includes(raw),
+            `not one of ${STORAGE_MODES.join(', ')}. Using the configured value or default instead.`,
+        ],
+        [
+            SUMMARY_ENV_VAR,
+            (raw) => SUMMARY_LEVELS.includes(raw),
+            `not one of ${SUMMARY_LEVELS.join(', ')}. Using the configured value or default instead.`,
+        ],
+        [
+            READ_ONLY_ENV_VAR,
+            (raw) => parseEnvBoolean(raw) !== undefined,
+            'expected 1/true/yes or 0/false/no. Read-only mode was not toggled by this value.',
+        ],
+        [
+            PLAN_MODE_ENV_VAR,
+            (raw) => parseEnvBoolean(raw) !== undefined,
+            'expected 1/true/yes or 0/false/no. Read-only mode was not toggled by this value.',
+        ],
     ];
     const warnings = [];
-    for (const [name, valid] of checks) {
+    for (const [name, isValid, hint] 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.`);
+        if (raw && !isValid(raw)) {
+            warnings.push(`Ignoring ${name}="${raw}": ${hint}`);
         }
     }
     return warnings;
@@ -59,3 +97,14 @@ export function resolveSummaryLevel(input) {
         input.userConfig.summary ??
         BUILT_IN_DEFAULTS.summary);
 }
+/**
+ * Resolve whether read-only (plan) mode is active. Unlike storage/summary, this is a safety gate
+ * rather than a preference: composition is OR, not override-by-precedence — if the flag or either
+ * env var says read-only, the run is read-only. There is no way to force writes back on when an
+ * ambient `BONSAI_READ_ONLY`/`BONSAI_PLAN_MODE` is set, by design.
+ */
+export function resolveReadOnly(input) {
+    return Boolean(input.flag ||
+        parseEnvBoolean(input.env[READ_ONLY_ENV_VAR]) ||
+        parseEnvBoolean(input.env[PLAN_MODE_ENV_VAR]));
+}

package/dist/lib/config-persist.d.ts

@@ -0,0 +1,28 @@
+import { type ConfigKey, type ConfigValues } from './config/index.js';
+/** Scope for config writes (`user` = XDG config dir; `project` = cwd `.bonsai`). */
+export type ConfigWriteScope = 'user' | 'project';
+/** Successful config persist outcome. */
+export interface ConfigPersistResult {
+    ok: true;
+}
+/** Failed config persist outcome with stable code and recovery tips. */
+export interface ConfigPersistFailure {
+    ok: false;
+    code: 'CONFIG_DIR_UNAVAILABLE';
+    message: string;
+    suggestions: string[];
+}
+/**
+ * Persist a config patch to user or project scope. Pure of oclif — callers map failures to
+ * this.error(...). Shared by config set and unset so the write branch cannot drift.
+ */
+export declare function persistConfigPatch(opts: {
+    scope: ConfigWriteScope;
+    cwd: string;
+    configDir: string | undefined;
+    patch: Partial<ConfigValues>;
+    /** Used in failure suggestions (set vs unset). */
+    action: 'set' | 'unset';
+    bin: string;
+    key: ConfigKey;
+}): ConfigPersistResult | ConfigPersistFailure;

package/dist/lib/config-persist.js

@@ -0,0 +1,29 @@
+import { writeUserConfig, writeProjectConfig, } from './config/index.js';
+/**
+ * Persist a config patch to user or project scope. Pure of oclif — callers map failures to
+ * this.error(...). Shared by config set and unset so the write branch cannot drift.
+ */
+export function persistConfigPatch(opts) {
+    if (opts.scope === 'project') {
+        writeProjectConfig(opts.cwd, opts.patch);
+        return { ok: true };
+    }
+    if (!opts.configDir) {
+        const verb = opts.action === 'set' ? 'write' : 'remove';
+        const example = opts.action === 'set'
+            ? `${opts.bin} config set ${opts.key} <value> --local`
+            : `${opts.bin} config unset ${opts.key} --local`;
+        return {
+            ok: false,
+            code: 'CONFIG_DIR_UNAVAILABLE',
+            message: `Could not determine user config directory. Use --local to ${verb} project config.`,
+            suggestions: [
+                opts.action === 'set'
+                    ? `Write project config instead: ${example}`
+                    : `Remove project config instead: ${example}`,
+            ],
+        };
+    }
+    writeUserConfig(opts.configDir, opts.patch);
+    return { ok: true };
+}

package/dist/lib/envelope.d.ts

@@ -7,8 +7,12 @@ export interface CliErrorShape {
 }
 /** 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. */
+/**
+ * Strip oclif's generic help suffix and the `Parsing --flag` wrapper so agents and humans see the
+ * actionable message we threw (e.g. `Limit must be between 1 and 100.`) instead of the wrapper.
+ */
 export declare function normalizeCliErrorMessage(message: string): string;
+/** Machine-readable envelope fields for `--json` success and error paths. */
 export interface EnvelopeParts {
     command: string;
     ok: boolean;
@@ -25,12 +29,46 @@ export interface EnvelopeParts {
  * without ANSI or the leading "Error:" prefix (the message is already the primary line).
  */
 export declare function formatErrorForJson(err: CliErrorShape): string;
+/** Stable CLIError fields for batch failure rows (status/inspect/fetch). */
+export declare function cliErrorFields(err: {
+    code?: string;
+    message?: string;
+    suggestions?: string[];
+    ref?: string;
+}, fallbackCode?: string): {
+    code: string;
+    message: string;
+    suggestions?: string[];
+    ref?: string;
+};
+/**
+ * CACHE_MISS overlay. Message wording is fixed so status/inspect cannot drift.
+ */
+export declare function enrichCacheMissEnvelope(envelope: Record<string, unknown>, data: unknown, bin: string): Record<string, unknown>;
+/**
+ * Per-row `.error` overlay for multi-URL batches (fetch, status, inspect).
+ * Keeps prior successes in `data` and surfaces the first row's code/message.
+ */
+export declare function enrichRowErrorEnvelope(envelope: Record<string, unknown>, data: unknown): Record<string, unknown>;
+/**
+ * Partial prune unlink failure: candidates remain in `data`, envelope reports the stable code.
+ */
+export declare function enrichPrunePartialEnvelope(envelope: Record<string, unknown>, data: unknown): Record<string, unknown>;
 /**
  * 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.
+ * Usage/not-found style error envelope: message + Code (+ Try this) in `stderr`, stable `code`,
+ * and top-level `suggestions` when present. Shared by argv preflight, help-preflight, and the
+ * command_not_found hook so those paths cannot drift.
  */
-export declare function formatEnvelope(parts: EnvelopeParts): string;
+export declare function buildCliErrorEnvelope(opts: {
+    command: string;
+    message: string;
+    code: string;
+    suggestions?: string[];
+    exitCode?: number;
+    ref?: string;
+}): Record<string, unknown>;

package/dist/lib/envelope.js

@@ -1,3 +1,4 @@
+import { EXIT_RUNTIME_FAILURE } from './cli-error-policy.js';
 /** Map oclif parse-time errors to stable Bonsai codes when the throw site did not set one. */
 export function stableErrorCodeFrom(err) {
     const e = err;
@@ -21,10 +22,23 @@ export function stableErrorCodeFrom(err) {
         /^Flag --\S+ expects (a value$|one of these values:)/.test(e.message)) {
         return 'MISSING_FLAG_VALUE';
     }
+    // Repeating a single-value flag (e.g. `--topic a --topic b`) is also a plain CLIError with no
+    // dedicated class — oclif's parser rejects it before any flag-specific validation runs.
+    if (typeof e?.message === 'string' && /^Flag --\S+ can only be specified once$/.test(e.message)) {
+        return 'DUPLICATE_FLAG';
+    }
     return undefined;
 }
-/** Strip oclif's generic help suffix from JSON stderr — agents already have structured codes. */
+/** oclif wraps custom flag parse failures as `Parsing --name \n\t…\nSee more help with --help`. */
+const PARSING_WRAPPER = /^Parsing --\S+ \n\t([\s\S]*?)(?:\nSee more help with --help)?$/;
+/**
+ * Strip oclif's generic help suffix and the `Parsing --flag` wrapper so agents and humans see the
+ * actionable message we threw (e.g. `Limit must be between 1 and 100.`) instead of the wrapper.
+ */
 export function normalizeCliErrorMessage(message) {
+    const wrapped = message.match(PARSING_WRAPPER);
+    if (wrapped?.[1])
+        return wrapped[1];
     const suffix = '\nSee more help with --help';
     return message.endsWith(suffix) ? message.slice(0, -suffix.length) : message;
 }
@@ -52,6 +66,119 @@ export function formatErrorForJson(err) {
         lines.push(`Reference: ${err.ref}`);
     return lines.join('\n');
 }
+/** Stable CLIError fields for batch failure rows (status/inspect/fetch). */
+export function cliErrorFields(err, fallbackCode = 'INVALID_URL') {
+    return {
+        code: typeof err.code === 'string' && err.code ? err.code : fallbackCode,
+        message: typeof err.message === 'string' ? err.message : String(err),
+        suggestions: err.suggestions,
+        ref: err.ref,
+    };
+}
+/**
+ * Overlay a batch failure onto a success envelope while keeping per-row `data`.
+ * Shared by multi-URL status/inspect (CACHE_MISS) and fetch/row errors.
+ */
+function enrichBatchFailureEnvelope(envelope, data, opts) {
+    const list = Array.isArray(data) ? data : [data];
+    const failures = list.map(opts.pick).filter(Boolean);
+    if (failures.length === 0)
+        return envelope;
+    const first = failures[0];
+    const code = typeof opts.code === 'function' ? opts.code(first, failures) : opts.code;
+    const suggestions = opts.suggestions?.(failures);
+    const ref = opts.ref?.(first);
+    const stderr = formatErrorForJson({
+        message: opts.message(first, failures),
+        code,
+        suggestions,
+        ref,
+    });
+    return {
+        ...envelope,
+        ok: false,
+        exitCode: opts.exitCode ?? 1,
+        stderr,
+        code,
+        suggestions,
+        ref,
+    };
+}
+/**
+ * CACHE_MISS overlay. Message wording is fixed so status/inspect cannot drift.
+ */
+export function enrichCacheMissEnvelope(envelope, data, bin) {
+    return enrichBatchFailureEnvelope(envelope, data, {
+        pick: (row) => {
+            const r = row;
+            return r?.status === 'miss' ? r : null;
+        },
+        code: 'CACHE_MISS',
+        exitCode: EXIT_RUNTIME_FAILURE,
+        message: (first, failures) => {
+            const url = first.normalizedUrl ?? '';
+            return failures.length > 1
+                ? `Cache miss for ${url} and ${failures.length - 1} other URLs`
+                : `Cache miss for ${url}`;
+        },
+        // A URL that is already a secondary source of a different cached artifact must not be pointed
+        // at a plain fetch — that would create an unrelated duplicate entry instead of finding the
+        // note that already covers it.
+        suggestions: (failures) => failures.map((m) => m.partOfExistingNote
+            ? `Find it with: ${bin} list --url "${m.normalizedUrl}"`
+            : `Fetch and cache it first: ${bin} ${m.normalizedUrl}`),
+    });
+}
+/**
+ * Per-row `.error` overlay for multi-URL batches (fetch, status, inspect).
+ * Keeps prior successes in `data` and surfaces the first row's code/message.
+ */
+export function enrichRowErrorEnvelope(envelope, data) {
+    return enrichBatchFailureEnvelope(envelope, data, {
+        pick: (row) => {
+            if (!row || typeof row !== 'object')
+                return null;
+            return row.error ?? null;
+        },
+        code: (first) => first.code ?? 'FETCH_FAILED',
+        message: (first, failures) => (first.message ?? '') +
+            (failures.length > 1 ? `\n…and ${failures.length - 1} other URL failure(s)` : ''),
+        suggestions: (failures) => failures[0]?.suggestions,
+        ref: (first) => first.ref,
+        exitCode: EXIT_RUNTIME_FAILURE,
+    });
+}
+/**
+ * Partial prune unlink failure: candidates remain in `data`, envelope reports the stable code.
+ */
+export function enrichPrunePartialEnvelope(envelope, data) {
+    if (!isPruneCounts(data))
+        return envelope;
+    // A dry run never deletes anything, so prunedCount is always 0 by design — that is a preview,
+    // not a partial failure, and must never be reported as one.
+    if (data.dryRun)
+        return envelope;
+    if (data.candidateCount <= 0 || data.prunedCount >= data.candidateCount)
+        return envelope;
+    const failed = data.candidateCount - data.prunedCount;
+    const code = 'PRUNE_PARTIAL_FAILURE';
+    const message = `Failed to delete ${failed} of ${data.candidateCount} cache ${failed === 1 ? 'entry' : 'entries'}.`;
+    return {
+        ...envelope,
+        ok: false,
+        exitCode: EXIT_RUNTIME_FAILURE,
+        code,
+        stderr: formatErrorForJson({ message, code }),
+    };
+}
+function isPruneCounts(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const d = data;
+    return (typeof d.prunedCount === 'number' &&
+        typeof d.candidateCount === 'number' &&
+        typeof d.dryRun === 'boolean');
+}
 /**
  * Builds the standard Bonsai CLI JSON envelope structure.
  * This is the single source of truth for the output envelope schema.
@@ -75,8 +202,24 @@ export function buildEnvelope(parts) {
     return envelope;
 }
 /**
- * Formats a JSON envelope to a string with indentation.
+ * Usage/not-found style error envelope: message + Code (+ Try this) in `stderr`, stable `code`,
+ * and top-level `suggestions` when present. Shared by argv preflight, help-preflight, and the
+ * command_not_found hook so those paths cannot drift.
  */
-export function formatEnvelope(parts) {
-    return JSON.stringify(buildEnvelope(parts), null, 2);
+export function buildCliErrorEnvelope(opts) {
+    return buildEnvelope({
+        command: opts.command,
+        ok: false,
+        exitCode: opts.exitCode ?? 2,
+        stderr: formatErrorForJson({
+            message: opts.message,
+            code: opts.code,
+            suggestions: opts.suggestions,
+            ref: opts.ref,
+        }),
+        data: null,
+        code: opts.code,
+        suggestions: opts.suggestions?.length ? opts.suggestions : undefined,
+        ref: opts.ref,
+    });
 }

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

@@ -1,15 +1,12 @@
-type UnknownHelpResult = {
-    exitCode: 2;
-    kind: 'human';
-    message: string;
-} | {
+import { EXIT_USAGE } from './cli-error-policy.js';
+/** Always an envelope — human and JSON share one formatted stderr (Code + Try this). */
+export type UnknownHelpResult = {
+    exitCode: typeof EXIT_USAGE;
     envelope: Record<string, unknown>;
-    exitCode: 2;
-    kind: 'json';
+    json: boolean;
 };
 /**
  * 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

@@ -1,22 +1,12 @@
 import { Config } from '@oclif/core';
-import { buildEnvelope } from './envelope.js';
+import { positionalArgvTokens } from './argv.js';
+import { EXIT_USAGE } from './cli-error-policy.js';
+import { VALUE_TAKING_FLAG_TOKENS } from './cli-flag-manifest.js';
+import { buildCliErrorEnvelope } 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++) {
@@ -51,7 +41,7 @@ function hasValidHelpTarget(tokens, config) {
 export async function tryUnknownHelpOutput(argv, root) {
     if (!argv.includes('--help'))
         return null;
-    const tokens = positionalTokens(argv);
+    const tokens = positionalArgvTokens(argv, VALUE_TAKING_FLAG_TOKENS);
     if (tokens.length === 0)
         return null;
     const config = await Config.load({ root });
@@ -59,23 +49,14 @@ export async function tryUnknownHelpOutput(argv, root) {
         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}`,
+        exitCode: EXIT_USAGE,
+        json: argv.includes('--json'),
+        envelope: buildCliErrorEnvelope({
+            command: details.command,
+            message: details.message,
+            code: details.code,
+            suggestions: details.suggestions,
+        }),
     };
 }

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

@@ -1,5 +1,3 @@
-/** 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.

package/dist/lib/json-meta.js

@@ -1,12 +1,14 @@
 import { Config, Help, toConfiguredId } from '@oclif/core';
+import { positionalArgvTokens } from './argv.js';
+import { EXIT_OK, EXIT_RUNTIME_FAILURE } from './cli-error-policy.js';
+import { VALUE_TAKING_FLAG_TOKENS } from './cli-flag-manifest.js';
 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) {
+function isJsonMetaRequest(argv) {
     if (!argv.includes('--json'))
         return false;
     return argv.includes('--help') || argv.includes('--version');
@@ -21,27 +23,21 @@ class CaptureHelp extends Help {
         }
     }
 }
-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)
+    const tokens = positionalArgvTokens(argv, VALUE_TAKING_FLAG_TOKENS);
+    if (tokens.length === 0)
         return config.bin;
-    const command = config.findCommand(subject);
-    if (command?.id)
-        return toConfiguredId(command.id, config);
-    const topic = config.findTopic(subject);
+    // Longest matching command id wins (`config:get` over topic `config`).
+    for (let n = tokens.length; n >= 1; n--) {
+        const id = tokens.slice(0, n).join(':');
+        const command = config.findCommand(id);
+        if (command?.id)
+            return toConfiguredId(command.id, config);
+    }
+    const topic = config.findTopic(tokens[0]);
     if (topic)
         return topic.name;
-    return subject;
+    return tokens[0];
 }
 /**
  * When `--json` is combined with `--help` or `--version`, oclif would print human text to stdout.
@@ -54,11 +50,11 @@ export async function tryJsonMetaOutput(argv, root) {
         const config = await Config.load({ root });
         if (argv.includes('--version')) {
             return {
-                exitCode: 0,
+                exitCode: EXIT_OK,
                 envelope: buildEnvelope({
                     command: config.bin,
                     ok: true,
-                    exitCode: 0,
+                    exitCode: EXIT_OK,
                     stderr: '',
                     data: {
                         version: config.version,
@@ -71,11 +67,11 @@ export async function tryJsonMetaOutput(argv, root) {
         await help.showHelp([...argv]);
         const helpText = stripAnsi(help.lines.join('\n').trimEnd());
         return {
-            exitCode: 0,
+            exitCode: EXIT_OK,
             envelope: buildEnvelope({
                 command: envelopeCommandId(config, argv),
                 ok: true,
-                exitCode: 0,
+                exitCode: EXIT_OK,
                 stderr: '',
                 data: { help: helpText },
             }),
@@ -84,11 +80,11 @@ export async function tryJsonMetaOutput(argv, root) {
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return {
-            exitCode: 1,
+            exitCode: EXIT_RUNTIME_FAILURE,
             envelope: buildEnvelope({
                 command: 'bonsai',
                 ok: false,
-                exitCode: 1,
+                exitCode: EXIT_RUNTIME_FAILURE,
                 stderr: message,
                 data: null,
                 code: 'META_RENDER_FAILED',

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

@@ -1 +1,11 @@
-export declare function limitFlag(max: number, defaultValue: number, description: string): import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+/**
+ * Build an oclif integer `--limit` flag capped at `maxLimit`.
+ *
+ * @param maxLimit - Inclusive upper bound for accepted values.
+ * @param defaultValue - Default when the flag is omitted.
+ * @param description - Help text for the flag.
+ * @returns An oclif custom flag definition.
+ * @throws {Errors.CLIError} With code `INVALID_LIMIT` and exit {@link EXIT_USAGE} on bad input
+ *   (thrown by oclif during parse, not by this factory itself).
+ */
+export declare function limitFlag(maxLimit: number, defaultValue: number, description: string): import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;

package/dist/lib/limit-flag.js

@@ -1,18 +1,31 @@
 import { Errors, Flags } from '@oclif/core';
-export function limitFlag(max, defaultValue, description) {
+import { EXIT_USAGE } from './cli-error-policy.js';
+/**
+ * Build an oclif integer `--limit` flag capped at `maxLimit`.
+ *
+ * @param maxLimit - Inclusive upper bound for accepted values.
+ * @param defaultValue - Default when the flag is omitted.
+ * @param description - Help text for the flag.
+ * @returns An oclif custom flag definition.
+ * @throws {Errors.CLIError} With code `INVALID_LIMIT` and exit {@link EXIT_USAGE} on bad input
+ *   (thrown by oclif during parse, not by this factory itself).
+ */
+export function limitFlag(maxLimit, 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,
+                throw new Errors.CLIError(`Limit must be an integer between 1 and ${maxLimit}.`, {
+                    exit: EXIT_USAGE,
                     code: 'INVALID_LIMIT',
+                    suggestions: [`Use an integer from 1 to ${maxLimit}.`],
                 });
             }
             const value = Number(input);
-            if (value < 1 || value > max) {
-                throw new Errors.CLIError(`Limit must be between 1 and ${max}.`, {
-                    exit: 2,
+            if (value < 1 || value > maxLimit) {
+                throw new Errors.CLIError(`Limit must be between 1 and ${maxLimit}.`, {
+                    exit: EXIT_USAGE,
                     code: 'INVALID_LIMIT',
+                    suggestions: [`Use a value from 1 to ${maxLimit}.`],
                 });
             }
             return value;

package/dist/lib/parse-error-ux.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Improve oclif parse-time errors in place: unwrap wrapper text, then suggest flag/option typos.
+ * Accepts `unknown` because `catch` can receive non-Error throws (bare strings, etc.).
+ */
+export declare function enrichParseError(err: unknown): void;