@taurgis/bonsai 3.2.0 → 4.0.0

package/README.md

@@ -110,7 +110,7 @@ Common flags:
 * `--max-age`: Read-time freshness threshold.
 * `--force`: Force a fresh fetch.
 * `--dry-run`: Scrape and validate without writing to cache.
-* `--allow-stale`: Serve stale cache if the remote site is offline.
+* `--allow-stale`: Suppress the exit `5` signal when a within-grace stale entry is served after failed revalidation (see [Freshness and Cache Rules](#freshness-and-cache-rules) below). Stale content is served within the grace window regardless of this flag; it does not extend serving beyond the grace window.
 * `--rendered`: Use browser-rendered extraction for SPA pages.
 * `--read-only` (alias `--plan`): Block all filesystem writes/deletes across every command; network fetches still run. See [Read-only / plan mode](#read-only--plan-mode) below.
 * `--json`: Return structured machine-readable output.
@@ -141,7 +141,7 @@ npx @taurgis/bonsai inspect <url>
 
 ### `list`
 
-List cached artifacts by metadata filters (`--topic`, `--tags`, `--freshness`, `--artifact-type`, `--capture-method`, `--limit`), newest first, without printing content.
+List cached artifacts by metadata filters (`--topic`, `--tags`, `--url`, `--freshness`, `--artifact-type`, `--capture-method`, `--limit`), newest first, without printing content. The default `--json`/`--toon` row is a minimal 4-field shape (`sourceUrls`, `topic`, `freshness`, `tokenEstimate`); pass `--full` for every metadata field. Running `bonsai` with no arguments at all is shorthand for `bonsai list`.
 
 ```bash
 npx @taurgis/bonsai list [flags]
@@ -149,7 +149,7 @@ npx @taurgis/bonsai list [flags]
 
 ### `prune`
 
-Delete old or inactive cache entries. Requires a filter (`--older-than`, `--inactive`, `--artifact-type`, or `--url`) and exactly one of `--dry-run` or `--yes` (passing both is a usage error). In [read-only mode](#read-only--plan-mode), `--yes` is rejected and the safety check is implicitly satisfied by a preview.
+Delete old or inactive cache entries. Requires a filter (`--older-than`, `--inactive`, `--artifact-type`, `--url`, `--topic`, or `--tags`) and exactly one of `--dry-run` or `--yes` (passing both is a usage error). In [read-only mode](#read-only--plan-mode), `--yes` is rejected and the safety check is implicitly satisfied by a preview.
 
 ```bash
 npx @taurgis/bonsai prune --older-than 90d --dry-run
@@ -181,7 +181,7 @@ npx @taurgis/bonsai import https://example.com/docs --file notes.md --read-only
 npx @taurgis/bonsai prune --older-than 90d --plan
 ```
 
-It can also be set via the `BONSAI_READ_ONLY` or `BONSAI_PLAN_MODE` environment variables (both are equivalent). Composition is OR, not override: read-only mode is active if *either* env var or the flag is set, and there is no way to force writes back on once one of them is — this is a safety gate, not a preference. Commands that already expose `--dry-run` (`fetch`, `prune`, `config set`/`unset`) treat it the same as an explicit `--dry-run`; `import` (which has no `--dry-run` of its own) previews the write and reports `dryRun: true` instead of persisting.
+It can also be set via the `BONSAI_READ_ONLY` or `BONSAI_PLAN_MODE` environment variables (both are equivalent). Composition is OR, not override: read-only mode is active if *either* env var or the flag is set, and there is no way to force writes back on once one of them is — this is a safety gate, not a preference. Commands that expose `--dry-run` (`fetch`, `import`, `prune`, `config set`/`unset`) treat global read-only the same as an explicit `--dry-run` and report `dryRun: true` (with `would_*` cache statuses where applicable) instead of persisting.
 
 ---
 
@@ -235,7 +235,10 @@ If no `--ttl` is specified, freshness is computed from the tier:
 | `standard` | 30 days | 14 days | General API docs and developer guides |
 | `stable` | 180 days | 60 days | RFCs, standards, long-lived references |
 
-When stale entries still have `ETag` or `Last-Modified` metadata, Bonsai attempts cheap revalidation before a full refetch. If revalidation fails and `--allow-stale` is omitted, the CLI can serve the stale content while exiting with code `5`.
+When stale entries still have `ETag` or `Last-Modified` metadata, Bonsai attempts cheap revalidation before a full refetch. If revalidation fails:
+
+* **Within the grace window**, the stale content is served either way. By default this exits with code `5` so a caller can detect "this result may be outdated"; `--allow-stale` suppresses that signal and exits `0` instead, since the caller has already said outdated content is acceptable.
+* **Past the grace window**, the entry is expired and revalidation failure is always a hard error (exit `1`) — `--allow-stale` has no effect here, since there is no fresher fallback to serve.
 
 ---
 
@@ -303,7 +306,7 @@ When run with `--json`, commands return a stable envelope:
 | `0` | Success. |
 | `1` | Runtime failure (network error, fetch failed, file read error). |
 | `2` | Usage error (invalid flag, bad URL, missing required argument). |
-| `5` | Stale content served — the cache entry is past its grace window but `--allow-stale` is set. The returned content is still usable. |
+| `5` | Stale content served — revalidation failed within the grace window and `--allow-stale` was omitted. The returned content is still usable. |
 
 ---
 

package/agents/agents/salesforce-docs-researcher.agent.md

@@ -5,7 +5,7 @@ model: 'Auto'
 tools: ['vscode/askQuestions', 'execute', 'read', 'search', 'web', 'vscode/memory']
 argument-hint: 'What Salesforce topic should I research in official docs?'
 metadata:
-  version: '2.0.0'
+  version: '2.2.0'
 ---
 
 # Salesforce Docs Researcher Agent
@@ -20,7 +20,9 @@ Do not research from memory alone. Training-data knowledge does not satisfy this
 
 ## Invocation
 
-Run Bonsai as `npx @taurgis/bonsai ...`. Add `--json` when you need structured output.
+Run Bonsai as `npx @taurgis/bonsai ...`. Add `--toon` when you need structured output at a lower token cost; `--json` is also available if you specifically need JSON (mutually exclusive with `--toon`).
+
+If you are operating in a read-only/plan mode (no filesystem writes allowed), add `--read-only` (alias `--plan`) to every Bonsai call, or export `BONSAI_READ_ONLY=1` (or `BONSAI_PLAN_MODE=1`) once for the session — fetches still run, but nothing is persisted to the local cache or config. See "Read-only / Plan Mode" below.
 
 ## Default Workflow
 
@@ -43,7 +45,7 @@ Run Bonsai as `npx @taurgis/bonsai ...`. Add `--json` when you need structured o
 For structured output:
 
 ```bash
-npx @taurgis/bonsai <official-url> --format detailed --json
+npx @taurgis/bonsai <official-url> --format detailed --toon
 ```
 
 ## Working with Salesforce Sites
@@ -68,6 +70,17 @@ Choose the freshness tier based on the source:
 
 Stale volatile sources must be revalidated before they are trusted. Never overwrite a good cache entry with an error response.
 
+## Read-only / Plan Mode
+
+Bonsai supports a global `--read-only` flag (alias `--plan`), also honored via the `BONSAI_READ_ONLY`/`BONSAI_PLAN_MODE` environment variables, that blocks all filesystem writes and deletes (cache persistence, config writes, `prune` deletions) while still allowing network fetches to run. Use it whenever you are invoked under a read-only/plan-mode harness so this research workflow stays non-destructive:
+
+- Research fetches (`npx @taurgis/bonsai <url>`), including the rendered Salesforce site-module fetches above, still hit the network and return content normally; they just skip writing the result to the local cache.
+- `import` previews the write and reports `dryRun: true` instead of persisting.
+- `config set` / `config unset` preview the write and report `would_set` / `would_unset`.
+- `prune` treats `--read-only` like an implicit dry run; combining it with `--yes` is rejected.
+
+Composition is OR: once read-only mode is active (flag or either env var), there is no per-call way to force writes back on.
+
 ## Fallbacks
 
 If direct web access was unavoidable because Bonsai could not fetch the content, import the synthesized notes back into Bonsai before returning:
@@ -96,4 +109,4 @@ Return:
 - Cache status or validation timestamp when Bonsai output provides it.
 - Gaps or uncertainty where official docs do not answer the question.
 
-Keep stdout clean when using `--json`; warnings and diagnostic notes belong in stderr or in the final prose summary.
+Keep stdout clean when using `--toon`/`--json`; warnings and diagnostic notes belong in stderr or in the final prose summary.

package/agents/instructions/salesforce-research.instructions.md

@@ -4,7 +4,7 @@ applyTo: '**'
 skills:
   - web-research
 metadata:
-  version: '2.0.0'
+  version: '2.1.0'
 ---
 
 # Web Research Requirement (Salesforce)
@@ -29,6 +29,7 @@ metadata:
 - **Browse cached entries**: Use `npx @taurgis/bonsai list` when you need to see what is already cached by topic, tags, or freshness.
 - If Bonsai is configured for project storage and `.bonsai/research/` is not ignored by git, treat those cache artifacts as intentional shared project files. It is OK to check them in, and agents must not delete them as incidental generated output without an explicit request.
 - Re-running on a recent topic is cheap — research the topic rather than skipping it to "save" a fetch.
+- If you are operating under a read-only/plan-mode harness, add `--read-only` (alias `--plan`) to Bonsai calls, or rely on `BONSAI_READ_ONLY`/`BONSAI_PLAN_MODE` if the harness sets it — fetches still run, but nothing is persisted to the local cache or config; `config set` / `config unset` preview with `would_set` / `would_unset`.
 
 ## Working with Salesforce Sites
 

package/bin/cli.mjs

@@ -7,6 +7,8 @@ import updateNotifier from 'update-notifier';
 import { createRequire } from 'node:module';
 
 import { normalizeArgv } from '../dist/lib/argv.js';
+import { VALUE_TAKING_FLAG_TOKENS, KNOWN_COMMAND_ROOT_TOKENS } from '../dist/lib/cli-flag-manifest.js';
+import { exitWithPreflight } from '../dist/lib/cli-emit.js';
 import { tryUnknownHelpOutput } from '../dist/lib/help-preflight.js';
 import { tryJsonMetaOutput } from '../dist/lib/json-meta.js';
 
@@ -21,36 +23,29 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // trying to resolve the bare URL as a command — which crashes with a stack trace. Rewrite
 // process.argv itself so both the run path and the help/error path agree.
 const rawArgv = process.argv.slice(2);
-const result = normalizeArgv(rawArgv);
+const result = normalizeArgv(rawArgv, {
+  valueTakingFlags: VALUE_TAKING_FLAG_TOKENS,
+  knownCommandRoots: KNOWN_COMMAND_ROOT_TOKENS,
+});
 const root = __dirname + '/../';
 
-if (result.exitWithJson) {
-  process.exitCode = result.exitWithJson.exitCode;
-  console.log(JSON.stringify(result.exitWithJson.envelope, null, 2));
-  process.exit();
+if (result.earlyExit) {
+  exitWithPreflight(result.earlyExit);
 }
 
 const unknownHelp = await tryUnknownHelpOutput(result.argv, root);
 if (unknownHelp) {
-  process.exitCode = unknownHelp.exitCode;
-  if (unknownHelp.kind === 'json') {
-    console.log(JSON.stringify(unknownHelp.envelope, null, 2));
-  } else {
-    console.error(` ›   Error: ${unknownHelp.message.replaceAll('\n', '\n ›   ')}`);
-  }
-  process.exit();
+  exitWithPreflight(unknownHelp);
 }
 
 const jsonMeta = await tryJsonMetaOutput(result.argv, root);
 if (jsonMeta) {
-  process.exitCode = jsonMeta.exitCode;
-  console.log(JSON.stringify(jsonMeta.envelope, null, 2));
-  process.exit();
+  exitWithPreflight({ ...jsonMeta, json: true });
 }
 
-// Only notify after the exitWithJson fast-path so the notifier never fires before
-// a JSON envelope exits. Also skip under --json so agent callers never see stderr noise.
-if (!process.argv.includes('--json')) {
+// Only notify after the earlyExit fast-path so the notifier never fires before
+// a usage-error envelope exits. Also skip under --json/--toon so agent callers never see stderr noise.
+if (!process.argv.includes('--json') && !process.argv.includes('--toon')) {
   updateNotifier({ pkg }).notify();
 }
 

package/dist/base-command.d.ts

@@ -1,5 +1,6 @@
-import { Command, Interfaces } from '@oclif/core';
+import { Command, Errors, Interfaces } from '@oclif/core';
 import { type ResolveResearchTargetOptions, type ResolvedResearchTarget } from './lib/research/resolve-target.js';
+import { type CliIo } from './lib/research/cli-io.js';
 /**
  * Shared base for every Bonsai command. Enables oclif's native `--json` flag,
  * parses args/flags once in `init()` so commands read `this.args`/`this.flags`
@@ -16,11 +17,24 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      */
     static baseFlags: {
         'read-only': Interfaces.BooleanFlag<boolean>;
+        toon: Interfaces.BooleanFlag<boolean>;
     };
     flags: Interfaces.InferredFlags<T['flags']>;
     args: Interfaces.InferredArgs<T['args']>;
     parsedArgv: string[];
     init(): Promise<void>;
+    /**
+     * Treat `--toon` as machine mode too, so every existing `!this.jsonEnabled()` human-output branch
+     * across every command (table rendering, tips, empty-state guidance) is suppressed under `--toon`
+     * for free, exactly as it already is under `--json`.
+     */
+    jsonEnabled(): boolean;
+    /**
+     * Real `--json` keeps oclif's own colorized-JSON rendering untouched (zero regression risk).
+     * `--toon` (and no real `--json`) re-encodes the identical envelope as TOON instead — same data,
+     * ~40% fewer tokens for callers who opted in.
+     */
+    protected logJson(json: unknown): void;
     /**
      * Always surface warnings on stderr, even under `--json`. oclif silences `warn()` in JSON mode,
      * but our warnings (secret-redirect, stale-serve, prune failures) are
@@ -28,6 +42,30 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      * JSON envelope, so machine output stays clean.
      */
     warn(input: string | Error): string | Error;
+    /**
+     * Sanitize the human-readable error surface before handing off to oclif. Error text throughout
+     * this CLI routinely echoes raw user input back (a rejected URL, `--ttl`, an unknown config key)
+     * so the message stays actionable, but that value is untrusted per the repo's trust-boundary
+     * rules — the same reasoning that already strips ANSI/control bytes from cached content before
+     * terminal render (see `sanitizeForTerminal`). Left unsanitized, a value containing raw escape
+     * bytes would replay as a terminal-injection attack the moment the rejected command's own error
+     * is printed. `--json` is untouched: `JSON.stringify` already escapes control characters, and the
+     * raw value there preserves exact input for programmatic callers.
+     */
+    error(input: string | Error, options: {
+        code?: string;
+        exit: false;
+    } & Errors.PrettyPrintableError): void;
+    error(input: string | Error, options?: {
+        code?: string;
+        exit?: number;
+    } & Errors.PrettyPrintableError): never;
+    /**
+     * Human-mode-only contextual next-step suggestion after a successful command, mirroring the
+     * "Try this:" pattern already used on errors. A no-op under `--json`/`--toon`: the envelope's
+     * `data` is self-describing, so machine callers get no prose.
+     */
+    protected tip(message: string): void;
     /** Whether read-only/plan mode is active for this invocation (flag OR either env var). */
     protected get readOnly(): boolean;
     /**
@@ -36,12 +74,6 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      * write, so a skipped write is never a silent surprise to the caller.
      */
     protected effectiveDryRun(explicitDryRun: boolean): boolean;
-    /**
-     * The exit code an error maps to. oclif `CLIError`s carry it in `err.oclif.exit`; other errors may
-     * expose `err.exitCode`. Defined once so the process exit code (`catch`) and the JSON envelope
-     * (`toErrorJson`) can never disagree — a mismatch between these two was itself the bug this fixes.
-     */
-    private static exitCodeOf;
     /**
      * Align the process exit code with the code reported in the JSON envelope. oclif's default
      * `catch` sets `process.exitCode = err.exitCode ?? 1`, but oclif `CLIError`s carry their code in
@@ -56,6 +88,7 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
         };
         exitCode?: number;
         code?: string;
+        suggestions?: string[];
     }): Promise<any>;
     /** Command id for the JSON envelope; falls back to the binary name when a command has no id. */
     protected envelopeCommandId(): string;
@@ -66,16 +99,30 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      * stays INVALID_URL.
      */
     protected resolveResearchTargetOrFail(url: string, extra?: Pick<ResolveResearchTargetOptions, 'flagOverride' | 'lookup'>): ResolvedResearchTarget;
-    /**
-     * Single exit point for a URL that failed normalization, shared by every URL-accepting command.
-     * The scheme-less message is already self-contained and actionable, so it is surfaced as-is;
-     * other parse failures keep the "Invalid URL:" prefix for context.
-     */
+    /** Exit for a URL that failed normalization; see {@link failInvalidUrl} for the code contract. */
     protected failInvalidUrl(url: string, message: string): never;
+    /** Command context handed to command services (fetch/import) so they stay oclif-free. */
+    protected cliIo(): CliIo;
     /** Single source of truth for the `--json` envelope shape, shared by success and error output. */
     private envelope;
+    /**
+     * Base success envelope from `process.exitCode` (including exit 5 = served stale / ok).
+     * Subclasses that overlay batch failures must call this — not `toSuccessJson` — to avoid
+     * recursing through their own override.
+     */
+    protected baseSuccessJson(data: unknown): Record<string, unknown>;
     /** Wrap a command's return value in the machine-readable envelope emitted under `--json`. */
     protected toSuccessJson(data: unknown): Record<string, unknown>;
+    /**
+     * Success overlay for multi-URL read commands (`status`, `inspect`). Apply CACHE_MISS first,
+     * then row `.error` so validation failures win when both appear in one batch.
+     */
+    protected batchReadSuccessJson(data: unknown): Record<string, unknown>;
+    /**
+     * Map each URL through `fn`. In a multi-URL batch, per-URL CLIErrors become failure rows so
+     * prior hits are kept — matching fetch's INVALID_URL / MISSING_URL_SCHEME batch contract.
+     */
+    protected mapUrlsAllowingBatchErrors<T, F>(urls: string[], fn: (url: string) => T, failureRow: (url: string, err: InstanceType<typeof Errors.CLIError>) => F): Array<T | F>;
     /** Mirror the success envelope for failures so JSON consumers get one consistent shape. */
     protected toErrorJson(err: unknown): Record<string, unknown>;
 }

package/dist/base-command.js

@@ -1,8 +1,24 @@
-import { Command, Errors, Flags, toConfiguredId } from '@oclif/core';
-import { invalidEnvOverrideWarnings, resolveReadOnly } from './lib/config/index.js';
-import { buildEnvelope, formatErrorForJson, normalizeCliErrorMessage, stableErrorCodeFrom, } from './lib/envelope.js';
+import { Command, Errors, Flags, toConfiguredId, ux } from '@oclif/core';
+import { encode } from '@toon-format/toon';
+import { invalidConfigFileWarnings, invalidEnvOverrideWarnings, resolveReadOnly, } from './lib/config/index.js';
+import { CLI_FLAG_DESCRIPTIONS } from './lib/cli-presentation.js';
+import { formatTip, sanitizeForTerminal } from './lib/text.js';
+import { enrichErrorForDisplay, resolveExitCode, prepareCliError, EXIT_OK, EXIT_STALE_SERVED, } from './lib/cli-error-policy.js';
+import { buildEnvelope, enrichCacheMissEnvelope, enrichRowErrorEnvelope } from './lib/envelope.js';
+import { enrichParseError } from './lib/parse-error-ux.js';
 import { resolveResearchTarget, } from './lib/research/resolve-target.js';
-import { looksLikeSchemelessUrl } from './lib/research/url.js';
+import { failInvalidUrl } from './lib/research/cli-io.js';
+/**
+ * Mirrors oclif's own `--json` argv-scan (respecting a `--` pass-through boundary) so `--toon`
+ * gets identical treatment: present in argv, regardless of parse state.
+ */
+function argvHasFlag(argv, flag) {
+    const passThroughIndex = argv.indexOf('--');
+    const flagIndex = argv.indexOf(flag);
+    return passThroughIndex === -1
+        ? flagIndex !== -1
+        : flagIndex !== -1 && flagIndex < passThroughIndex;
+}
 /**
  * Shared base for every Bonsai command. Enables oclif's native `--json` flag,
  * parses args/flags once in `init()` so commands read `this.args`/`this.flags`
@@ -21,8 +37,11 @@ export class BaseCommand extends Command {
         'read-only': Flags.boolean({
             aliases: ['plan'],
             default: false,
-            description: 'Block all filesystem writes/deletes (cache and config); network fetches still run. ' +
-                'Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.',
+            description: CLI_FLAG_DESCRIPTIONS.readOnly,
+        }),
+        toon: Flags.boolean({
+            default: false,
+            description: CLI_FLAG_DESCRIPTIONS.toon,
         }),
     };
     flags;
@@ -40,11 +59,52 @@ export class BaseCommand extends Command {
         this.flags = flags;
         this.args = args;
         this.parsedArgv = argv;
+        // --json and --toon both claim the machine-output seat; picking one silently over the other
+        // would surprise a caller who set both by mistake, so reject the combination outright. Reuses
+        // the existing CONFLICTING_FLAGS code (not a new one) — the catalog already documents it as the
+        // one code for "choose one of the mutually exclusive options", regardless of which flags.
+        if (this.flags?.['json'] && this.flags?.['toon']) {
+            this.error('Cannot combine --json and --toon: pick one output format.', {
+                exit: 2,
+                code: 'CONFLICTING_FLAGS',
+                suggestions: ['Pass only one of --json or --toon'],
+            });
+        }
         // Surface a set-but-invalid BONSAI_* override once per run. Resolution silently drops such a
         // value, so without this a typo'd env var would take no effect with no signal. Warnings go to
         // stderr (even under --json), so machine output stays clean.
         for (const warning of invalidEnvOverrideWarnings(process.env))
             this.warn(warning);
+        // Same signal for a corrupted or hand-edited config file: parsing silently degrades to `{}`
+        // (or drops just the offending key), which would otherwise mask the problem entirely.
+        for (const warning of invalidConfigFileWarnings(this.config.configDir, process.cwd(), this.config.bin)) {
+            this.warn(warning);
+        }
+    }
+    /**
+     * Treat `--toon` as machine mode too, so every existing `!this.jsonEnabled()` human-output branch
+     * across every command (table rendering, tips, empty-state guidance) is suppressed under `--toon`
+     * for free, exactly as it already is under `--json`.
+     */
+    jsonEnabled() {
+        // Mirrors oclif's own enableJsonFlag guard (every command in this CLI sets it, but the base
+        // class's contract shouldn't silently break if a future command ever opts out).
+        return (super.jsonEnabled() ||
+            (Boolean(this.ctor?.enableJsonFlag) && argvHasFlag(this.argv, '--toon')));
+    }
+    /**
+     * Real `--json` keeps oclif's own colorized-JSON rendering untouched (zero regression risk).
+     * `--toon` (and no real `--json`) re-encodes the identical envelope as TOON instead — same data,
+     * ~40% fewer tokens for callers who opted in.
+     */
+    logJson(json) {
+        if (super.jsonEnabled()) {
+            super.logJson(json);
+            return;
+        }
+        // this.log() no-ops whenever jsonEnabled() is true (by design, everywhere else in this CLI) —
+        // ux.stdout writes directly, matching how oclif's own default logJson bypasses that guard too.
+        ux.stdout(encode(json));
     }
     /**
      * Always surface warnings on stderr, even under `--json`. oclif silences `warn()` in JSON mode,
@@ -56,6 +116,35 @@ export class BaseCommand extends Command {
         Errors.warn(input);
         return input;
     }
+    error(input, options = {}) {
+        if (!this.jsonEnabled()) {
+            if (typeof input === 'string')
+                input = sanitizeForTerminal(input);
+            if (options.suggestions) {
+                options = { ...options, suggestions: options.suggestions.map(sanitizeForTerminal) };
+            }
+        }
+        // `exit: false` is oclif's non-throwing error render (see `errorRow` on the CliIo port and
+        // `mapUrlsAllowingBatchErrors`/prune's per-row failures, all of which route through here for the
+        // same terminal-injection sanitization above). Destructure `exit` into its own binding so
+        // narrowing it to the `false` literal actually narrows the object passed to `super.error()` into
+        // each of oclif's two overloads — narrowing a property read alone (`options.exit === false`)
+        // doesn't narrow the enclosing object's type, only a local variable's.
+        const { exit, ...rest } = options;
+        if (exit === false)
+            return super.error(input, { ...rest, exit });
+        return super.error(input, { ...rest, exit });
+    }
+    /**
+     * Human-mode-only contextual next-step suggestion after a successful command, mirroring the
+     * "Try this:" pattern already used on errors. A no-op under `--json`/`--toon`: the envelope's
+     * `data` is self-describing, so machine callers get no prose.
+     */
+    tip(message) {
+        if (this.jsonEnabled())
+            return;
+        this.warn(formatTip(message));
+    }
     /** Whether read-only/plan mode is active for this invocation (flag OR either env var). */
     get readOnly() {
         return resolveReadOnly({ flag: Boolean(this.flags?.['read-only']), env: process.env });
@@ -71,14 +160,6 @@ export class BaseCommand extends Command {
         }
         return explicitDryRun || this.readOnly;
     }
-    /**
-     * The exit code an error maps to. oclif `CLIError`s carry it in `err.oclif.exit`; other errors may
-     * expose `err.exitCode`. Defined once so the process exit code (`catch`) and the JSON envelope
-     * (`toErrorJson`) can never disagree — a mismatch between these two was itself the bug this fixes.
-     */
-    static exitCodeOf(err) {
-        return err?.oclif?.exit ?? err?.exitCode ?? 1;
-    }
     /**
      * Align the process exit code with the code reported in the JSON envelope. oclif's default
      * `catch` sets `process.exitCode = err.exitCode ?? 1`, but oclif `CLIError`s carry their code in
@@ -92,16 +173,10 @@ export class BaseCommand extends Command {
         // [UnparsedCommand] warning to stderr even under `--json`. CLIParseError subclasses carry `parse`.
         if (err && typeof err === 'object' && 'parse' in err)
             this.parsed = true;
-        // Attach the stable code to the error itself so oclif's human pretty-print renders the same
-        // `Code:` line that `--json` already reports via stableErrorCodeFrom. Without this, built-in
-        // oclif parse errors (invalid enum value, missing arg, unknown flag) printed a code under
-        // --json but not for humans — the two output modes disagreed on whether an error had a code.
-        if (err && typeof err === 'object' && !err.code) {
-            const code = stableErrorCodeFrom(err);
-            if (code)
-                err.code = code;
-        }
-        process.exitCode = process.exitCode ?? BaseCommand.exitCodeOf(err);
+        // Unwrap / fuzzy tips are no-ops when not applicable (including non-Error throws with no message).
+        enrichParseError(err);
+        enrichErrorForDisplay(err, { bin: this.config.bin, command: this.envelopeCommandId() });
+        process.exitCode = process.exitCode ?? resolveExitCode(err);
         return super.catch(err);
     }
     /** Command id for the JSON envelope; falls back to the binary name when a command has no id. */
@@ -120,6 +195,7 @@ export class BaseCommand extends Command {
                 configDir: this.config.configDir,
                 cwd: process.cwd(),
                 dataDir: this.config.dataDir,
+                readOnly: this.readOnly,
                 url,
                 ...extra,
             });
@@ -128,16 +204,23 @@ export class BaseCommand extends Command {
             this.failInvalidUrl(url, err.message);
         }
     }
-    /**
-     * Single exit point for a URL that failed normalization, shared by every URL-accepting command.
-     * The scheme-less message is already self-contained and actionable, so it is surfaced as-is;
-     * other parse failures keep the "Invalid URL:" prefix for context.
-     */
+    /** Exit for a URL that failed normalization; see {@link failInvalidUrl} for the code contract. */
     failInvalidUrl(url, message) {
-        if (looksLikeSchemelessUrl(url)) {
-            this.error(message, { exit: 2, code: 'MISSING_URL_SCHEME' });
-        }
-        this.error(`Invalid URL: ${message}`, { exit: 2, code: 'INVALID_URL' });
+        failInvalidUrl((msg, opts) => this.error(msg, opts), url, message);
+    }
+    /** Command context handed to command services (fetch/import) so they stay oclif-free. */
+    cliIo() {
+        return {
+            bin: this.config.bin,
+            configDir: this.config.configDir,
+            dataDir: this.config.dataDir,
+            cwd: process.cwd(),
+            json: this.jsonEnabled(),
+            warn: (msg) => void this.warn(msg),
+            log: (msg) => this.log(msg),
+            error: (msg, opts) => this.error(msg, opts),
+            errorRow: (msg, opts) => this.error(msg, { ...opts, exit: false }),
+        };
     }
     /** Single source of truth for the `--json` envelope shape, shared by success and error output. */
     envelope(parts) {
@@ -149,33 +232,78 @@ export class BaseCommand extends Command {
             data: parts.data,
         });
     }
+    /**
+     * Base success envelope from `process.exitCode` (including exit 5 = served stale / ok).
+     * Subclasses that overlay batch failures must call this — not `toSuccessJson` — to avoid
+     * recursing through their own override.
+     */
+    baseSuccessJson(data) {
+        // ponytail: the stale-serve path signals EXIT_STALE_SERVED by setting process.exitCode inside
+        // run() (e.g. fetch's handleStaleRevalidationResult); this reads it back to mark the envelope.
+        // If that signalling moves off process.exitCode, update here too. Number() normalizes Node's
+        // string codes.
+        const exitCode = Number(process.exitCode ?? EXIT_OK);
+        // EXIT_STALE_SERVED means "served stale" — a successful, usable result, so it reports ok.
+        return this.envelope({
+            ok: exitCode === EXIT_OK || exitCode === EXIT_STALE_SERVED,
+            exitCode,
+            stderr: '',
+            data,
+        });
+    }
     /** Wrap a command's return value in the machine-readable envelope emitted under `--json`. */
     toSuccessJson(data) {
-        // ponytail: the stale-serve path signals "exit 5" by setting process.exitCode inside run()
-        // (e.g. fetch's handleStaleRevalidationResult); this reads it back to mark the envelope. If that
-        // signalling moves off process.exitCode, update here too. Number() normalizes Node's string codes.
-        const exitCode = Number(process.exitCode ?? 0);
-        // Exit 5 means "served stale" — a successful, usable result, so it reports ok.
-        return this.envelope({ ok: exitCode === 0 || exitCode === 5, exitCode, stderr: '', data });
+        return this.baseSuccessJson(data);
+    }
+    /**
+     * Success overlay for multi-URL read commands (`status`, `inspect`). Apply CACHE_MISS first,
+     * then row `.error` so validation failures win when both appear in one batch.
+     */
+    batchReadSuccessJson(data) {
+        return enrichRowErrorEnvelope(enrichCacheMissEnvelope(this.baseSuccessJson(data), data, this.config.bin), data);
+    }
+    /**
+     * Map each URL through `fn`. In a multi-URL batch, per-URL CLIErrors become failure rows so
+     * prior hits are kept — matching fetch's INVALID_URL / MISSING_URL_SCHEME batch contract.
+     */
+    mapUrlsAllowingBatchErrors(urls, fn, failureRow) {
+        const batch = urls.length > 1;
+        const results = [];
+        for (const url of urls) {
+            try {
+                results.push(fn(url));
+            }
+            catch (err) {
+                if (!batch || !(err instanceof Errors.CLIError))
+                    throw err;
+                // Render with the same "Error:" formatting as a single-URL failure (this.error's exit:false
+                // form prints the CLIError's own message/Code/Try this and returns instead of throwing) rather
+                // than this.warn, since a row failure still fails the command overall (status/inspect batch
+                // exit code, JSON ok:false) and should never read as merely a warning.
+                if (!this.jsonEnabled())
+                    this.error(err, { exit: false });
+                results.push(failureRow(url, err));
+            }
+        }
+        return results;
     }
     /** Mirror the success envelope for failures so JSON consumers get one consistent shape. */
     toErrorJson(err) {
-        const e = err;
-        const exitCode = BaseCommand.exitCodeOf(e);
-        const code = stableErrorCodeFrom(e);
-        const message = typeof e?.message === 'string' ? normalizeCliErrorMessage(e.message) : undefined;
-        const stderr = message || code || e?.suggestions?.length || e?.ref
-            ? formatErrorForJson({ ...e, message, code })
-            : String(err);
+        const prepared = prepareCliError(err, {
+            bin: this.config.bin,
+            command: this.envelopeCommandId(),
+        });
+        // oclif prints the returned object to stdout; error text lives in envelope.stderr only
+        // so process stderr stays clean under `--json` (CACHE_MISS / batch overlays + oclif JSON log suppression).
         return buildEnvelope({
             command: this.envelopeCommandId(),
             ok: false,
-            exitCode,
-            stderr,
+            exitCode: prepared.exitCode,
+            stderr: prepared.stderr,
             data: null,
-            code,
-            suggestions: e.suggestions?.length ? e.suggestions : undefined,
-            ref: e.ref,
+            code: prepared.code,
+            suggestions: prepared.suggestions,
+            ref: prepared.ref,
         });
     }
 }

package/dist/commands/config/base.js

@@ -1,4 +1,4 @@
-import { Flags } from '@oclif/core';
+import { Flags, toConfiguredId } from '@oclif/core';
 import { BaseCommand } from '../../base-command.js';
 import { isKnownKey, suggestKey, validKeysHint } from '../../lib/config/index.js';
 /**
@@ -11,6 +11,7 @@ export class ConfigCommand extends BaseCommand {
             this.error('--global and --local are mutually exclusive.', {
                 exit: 2,
                 code: 'CONFLICTING_FLAGS',
+                suggestions: ['Pass --global or --local, not both.'],
             });
         }
     }
@@ -30,15 +31,24 @@ export class ConfigCommand extends BaseCommand {
         if (!isKnownKey(keyArg)) {
             const suggestion = suggestKey(keyArg);
             const hint = suggestion ? ` Did you mean: ${suggestion}?` : '';
+            const command = this.ctor.id ? toConfiguredId(this.ctor.id, this.config) : 'config';
             this.error(`Unknown config key: "${keyArg}".${hint} Valid keys: ${validKeysHint()}.`, {
                 exit: 2,
                 code: 'UNKNOWN_KEY',
+                suggestions: suggestion
+                    ? [`Use "${suggestion}": ${this.config.bin} ${command} ${suggestion}`]
+                    : [`Use one of: ${validKeysHint()}`],
             });
         }
     }
     requireConfigKey(key) {
         if (!key) {
-            this.error('Missing required argument: key', { exit: 2, code: 'MISSING_ARGUMENT' });
+            const command = this.ctor.id ? toConfiguredId(this.ctor.id, this.config) : 'config';
+            this.error('Missing required argument: key', {
+                exit: 2,
+                code: 'MISSING_ARGUMENT',
+                suggestions: [`Choose a key: ${this.config.bin} ${command} storage`],
+            });
         }
         this.assertKnownKey(key);
     }