@taurgis/bonsai 3.2.0 → 3.2.2

package/dist/commands/status.js

@@ -1,35 +1,35 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../base-command.js';
-import { formatErrorForJson } from '../lib/envelope.js';
+import { finalizeBatch, isBatchReadFailure, urlValidationErrorRow } from '../lib/batch.js';
 import { getArtifactPath } from '../lib/research/storage.js';
-import { evaluateFreshness, checkMaxAgeExpired, durationFlagError, } from '../lib/research/freshness.js';
+import { durationFlagError, evaluateFreshnessWithMaxAge } from '../lib/research/freshness.js';
+import { CLI_FLAG_DESCRIPTIONS } from '../lib/cli-presentation.js';
+import { batchSeparator, cacheMissHint, formatCacheTargetHeader } from '../lib/cache-view.js';
 import { colors } from '../lib/color.js';
-function resolveFreshness(cached, currentTime, ttl, maxAge) {
-    const isMaxAgeExpired = maxAge ? checkMaxAgeExpired(cached, currentTime, maxAge) : false;
-    return isMaxAgeExpired
-        ? 'stale_expired'
-        : evaluateFreshness(cached.metadata, currentTime, ttl || cached.metadata.ttl);
+function resolveFreshness(cached, currentTime, ttl, maxAge, tier) {
+    return evaluateFreshnessWithMaxAge(cached, currentTime, { ttl, maxAge, tier });
 }
-function describeCacheStatus(cached, currentTime, ttl, maxAge) {
+function describeCacheStatus(cached, currentTime, ttl, maxAge, tier) {
     if (!cached) {
         return { status: 'miss', freshness: 'none', action: 'would_fetch' };
     }
-    const freshness = resolveFreshness(cached, currentTime, ttl, maxAge);
+    const freshness = resolveFreshness(cached, currentTime, ttl, maxAge, tier);
     return freshness === 'fresh'
         ? { status: 'hit', freshness, action: 'would_return_cached' }
         : { status: 'stale', freshness, action: 'would_revalidate' };
 }
+/** Report cache hit/miss and freshness without writing. */
 export default class ResearchStatus extends BaseCommand {
     static id = 'status';
-    static summary = 'Check the cache status of a URL without fetching or writing.';
-    static description = 'Reports whether the URL is cached, its freshness state, and what action (fetch, revalidate, or cached return) the root fetch command would take.';
+    static summary = 'Check cache status without fetching or writing';
+    static description = 'Report cache hit/miss state, freshness, and the action the URL shorthand would take.';
     static examples = [
         {
-            description: 'check if a URL is already in the cache',
+            description: 'check whether a URL is cached',
             command: '<%= config.bin %> <%= command.id %> https://example.com/docs',
         },
         {
-            description: 'check status against a specific freshness tier and TTL',
+            description: 'evaluate status with a specific tier and TTL',
             command: '<%= config.bin %> <%= command.id %> https://example.com/docs --tier volatile --ttl 2h',
         },
     ];
@@ -37,41 +37,27 @@ export default class ResearchStatus extends BaseCommand {
     static args = {
         url: Args.string({
             required: true,
-            description: 'the URL to check',
+            description: 'URL to check',
         }),
     };
     static flags = {
+        // No default: omitting --tier evaluates against the artifact's stored tier. A default of
+        // `standard` would silently re-grade stable/volatile entries and lie about planned action.
         tier: Flags.option({
-            description: 'freshness tier policy to evaluate against',
+            description: CLI_FLAG_DESCRIPTIONS.statusFreshnessTierPolicy,
             options: ['stable', 'standard', 'volatile'],
-            default: 'standard',
         })(),
         ttl: Flags.string({
             char: 'l',
-            description: 'custom TTL duration to evaluate against (e.g. "2h", "7d")',
+            description: CLI_FLAG_DESCRIPTIONS.statusTtl,
         }),
         'max-age': Flags.string({
-            description: 'maximum age of cache to accept (e.g. "1d", "30d")',
+            description: CLI_FLAG_DESCRIPTIONS.maxAge,
         }),
     };
     static stdoutIsPrimaryData = true;
-    /** Enrich cache-miss envelopes with the same CACHE_MISS code and suggestions as inspect. */
     toSuccessJson(data) {
-        const envelope = super.toSuccessJson(data);
-        const list = Array.isArray(data) ? data : [data];
-        const misses = list.filter((d) => d && d.status === 'miss');
-        if (misses.length === 0)
-            return envelope;
-        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}` +
-                (misses.length > 1 ? ` and ${misses.length - 1} other URLs` : ''),
-            code: 'CACHE_MISS',
-            suggestions,
-        });
-        return { ...envelope, ok: false, exitCode: 1, stderr, code: 'CACHE_MISS', suggestions };
+        return this.batchReadSuccessJson(data);
     }
     async run() {
         const urls = this.parsedArgv;
@@ -82,60 +68,22 @@ 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;
+        const results = this.mapUrlsAllowingBatchErrors(urls, (url) => this.checkSingleStatus(url, currentTime, { ttl, maxAge, tier }), urlValidationErrorRow);
+        return finalizeBatch(results, isBatchReadFailure);
     }
-    checkSingleStatus(url, currentTime, ttl, maxAge, showSeparator) {
+    checkSingleStatus(url, currentTime, policy) {
         const target = this.resolveResearchTargetOrFail(url);
         const { cacheKey, located, normalizedUrl, roots } = target;
         const cached = located?.artifact ?? null;
-        const result = describeCacheStatus(cached, currentTime, ttl, maxAge);
+        const result = describeCacheStatus(cached, currentTime, policy.ttl, policy.maxAge, policy.tier);
         const artifactPath = located?.path ?? getArtifactPath(roots.writeRoot, cacheKey);
         if (!this.jsonEnabled()) {
-            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));
+            this.logStatusTable(target, artifactPath, result);
+            if (result.status === 'miss') {
+                this.warn(cacheMissHint(this.config.bin, normalizedUrl));
             }
         }
-        if (result.status === 'miss' && !this.jsonEnabled()) {
-            this.warn(`Cache miss — run: ${this.config.bin} ${normalizedUrl}`);
-        }
         return {
             cacheKey,
             cachePath: artifactPath,
@@ -145,4 +93,29 @@ export default class ResearchStatus extends BaseCommand {
             action: result.action,
         };
     }
+    logStatusTable(target, artifactPath, result) {
+        const colorOf = (map, key) => map[key] ?? ((t) => t);
+        const statusColor = colorOf({ hit: colors.green, stale: colors.yellow, miss: colors.red }, result.status);
+        const freshnessColor = colorOf({
+            fresh: colors.green,
+            stale_grace: colors.yellow,
+            stale_expired: colors.red,
+            none: colors.gray,
+        }, result.freshness);
+        const actionColor = colorOf({
+            would_return_cached: colors.green,
+            would_revalidate: colors.yellow,
+            would_fetch: colors.red,
+        }, result.action);
+        for (const line of formatCacheTargetHeader(target, [
+            ['Status', statusColor(result.status)],
+            ['Freshness', freshnessColor(result.freshness)],
+            ['Action', actionColor(result.action)],
+        ], artifactPath)) {
+            this.log(line);
+        }
+        const sep = batchSeparator(this.parsedArgv.length > 1);
+        if (sep)
+            this.log(sep);
+    }
 }

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

@@ -4,6 +4,7 @@ export declare function buildCommandNotFoundDetails(id: string, argv: string[] |
     command: string;
     jsonMode: boolean;
     message: string;
+    suggestions?: string[];
 };
 /**
  * Typo-aware "command not found" handler. oclif fires this before printing its own terse error;

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

@@ -1,6 +1,6 @@
 import { toConfiguredId } from '@oclif/core';
 import { closestMatch, maxFuzzyDistance } from '../../lib/text.js';
-import { buildEnvelope, formatErrorForJson } from '../../lib/envelope.js';
+import { writeCommandNotFoundJson } from '../../lib/cli-emit.js';
 import { looksLikeSchemelessUrl } from '../../lib/research/url.js';
 /**
  * The nearest visible command to a typo, plus how many leading segments of the attempted id name
@@ -10,13 +10,13 @@ import { looksLikeSchemelessUrl } from '../../lib/research/url.js';
  * `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) {
+function findSuggestion(segments, commandIds) {
     for (let n = segments.length; n >= 1; n--) {
         const attempted = segments.slice(0, n).join(':');
-        const suggestion = closestMatch(attempted, visibleIds, maxFuzzyDistance(attempted));
+        const suggestion = closestMatch(attempted, commandIds, maxFuzzyDistance(attempted));
         if (suggestion === attempted &&
             n < segments.length &&
-            visibleIds.some((id) => id.startsWith(`${attempted}:`))) {
+            commandIds.some((id) => id.startsWith(`${attempted}:`))) {
             continue;
         }
         if (suggestion)
@@ -35,12 +35,12 @@ function topicChainLength(segments, config) {
         i++;
     return i + 1;
 }
-function exactZeroArgCommandPrefix(segments, visibleIds, config) {
+function exactZeroArgCommandPrefix(segments, commandIds, config) {
     for (let n = segments.length - 1; n >= 1; n--) {
         const candidate = segments.slice(0, n).join(':');
-        if (!visibleIds.includes(candidate))
+        if (!commandIds.includes(candidate))
             continue;
-        if (visibleIds.some((id) => id.startsWith(`${candidate}:`)))
+        if (commandIds.some((id) => id.startsWith(`${candidate}:`)))
             continue;
         const command = config.commands.find((entry) => entry.id === candidate);
         const args = Object.keys(command?.args ?? {});
@@ -65,43 +65,54 @@ function exactZeroArgCommandPrefix(segments, visibleIds, config) {
 function bareUrlInput(id) {
     return looksLikeSchemelessUrl(id) ? id : null;
 }
+/**
+ * The id's colon-joined segments when every one individually looks like a URL missing its scheme,
+ * else null. Covers the multi-URL batch-fetch typo (`bonsai example.com example.org` folds into one
+ * id, "example.com:example.org") that {@link bareUrlInput} misses: parsed as a single URL, the colon
+ * between two hostnames reads as an invalid port, so the whole-string check fails even though each
+ * segment on its own is a plain scheme-less host.
+ */
+function bareUrlSegments(id) {
+    const segments = id.split(':');
+    return segments.length > 1 && segments.every((segment) => looksLikeSchemelessUrl(segment))
+        ? segments
+        : null;
+}
 function isJsonMode(argv) {
-    return argv?.includes('--json') ?? false;
+    return (argv?.includes('--json') ?? false) || process.argv.includes('--json');
 }
-function emitJsonError(command, message, code) {
-    const envelope = buildEnvelope({
-        command,
-        ok: false,
-        exitCode: 2,
-        stderr: formatErrorForJson({ message, code }),
-        data: null,
-        code,
-    });
-    process.exitCode = 2;
-    console.log(JSON.stringify(envelope, null, 2));
-    return envelope;
+/** Shared "did you mean https://…?" response for one or several scheme-less URLs. */
+function missingUrlSchemeDetails(urls, argv, config) {
+    const attempted = urls.join(' ');
+    const suggestion = `${config.bin} ${urls.map((url) => `https://${url}`).join(' ')}`;
+    return {
+        code: 'MISSING_URL_SCHEME',
+        command: attempted,
+        jsonMode: isJsonMode(argv),
+        message: [
+            `${attempted} is not a ${config.bin} command.`,
+            `Run ${config.bin} help for a list of available commands.`,
+            `Did you mean ${suggestion}? URLs need an http:// or https:// scheme.`,
+        ].join('\n'),
+        suggestions: [suggestion],
+    };
 }
 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));
+    // Match against every loaded command id — including hidden ones that stay invokable
+    // (`fetch`, plugin internals). Root `--help` hides them; typo recovery should not.
+    const commandIds = config.commandIDs;
     // 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).
+    // Flag-only argv never reaches here — normalizeArgv early-exits those as MISSING_COMMAND.
     const bareUrl = bareUrlInput(id);
-    if (bareUrl) {
-        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'),
-        };
-    }
+    if (bareUrl)
+        return missingUrlSchemeDetails([bareUrl], argv, config);
+    const bareUrls = bareUrlSegments(id);
+    if (bareUrls)
+        return missingUrlSchemeDetails(bareUrls, argv, config);
     const segments = id.split(':');
-    const unexpected = exactZeroArgCommandPrefix(segments, visibleIds, config);
+    const unexpected = exactZeroArgCommandPrefix(segments, commandIds, config);
     if (unexpected) {
         const command = toConfiguredId(unexpected.commandId, config);
         return {
@@ -114,7 +125,7 @@ export function buildCommandNotFoundDetails(id, argv, config) {
             ].join('\n'),
         };
     }
-    const { suggestion, commandSegments } = findSuggestion(segments, visibleIds);
+    const { suggestion, commandSegments } = findSuggestion(segments, commandIds);
     // 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, config);
@@ -123,6 +134,9 @@ export function buildCommandNotFoundDetails(id, argv, config) {
     // is the floor, and a concrete "Did you mean …?" correction — when we have one — goes below it.
     const lines = [`${attempted} is not a ${config.bin} command.`];
     lines.push(`Run ${config.bin} help for a list of available commands.`);
+    const suggestions = suggestion
+        ? [`${config.bin} ${toConfiguredId(suggestion, config)}`]
+        : undefined;
     if (suggestion)
         lines.push(`Did you mean ${toConfiguredId(suggestion, config)}?`);
     return {
@@ -130,6 +144,7 @@ export function buildCommandNotFoundDetails(id, argv, config) {
         command: attempted,
         jsonMode: isJsonMode(argv),
         message: lines.join('\n'),
+        suggestions,
     };
 }
 /**
@@ -140,8 +155,20 @@ export function buildCommandNotFoundDetails(id, argv, config) {
  */
 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 });
+    if (details.jsonMode) {
+        return writeCommandNotFoundJson({
+            command: details.command,
+            message: details.message,
+            code: details.code,
+            suggestions: details.suggestions,
+        });
+    }
+    // Hook context typings omit `suggestions` even though CLIError accepts them; cast keeps the
+    // human pretty-print "Try this:" lines aligned with the JSON envelope.
+    this.error(details.message, {
+        exit: 2,
+        code: details.code,
+        suggestions: details.suggestions,
+    });
 };
 export default hook;

package/dist/lib/argv.d.ts

@@ -1,10 +1,31 @@
+/** Result of argv normalization before oclif command dispatch. */
 export interface NormalizationResult {
     /** The normalized argv array to set on process.argv. */
     argv: string[];
-    /** Optional metadata indicating the shim should exit early with a JSON envelope. */
-    exitWithJson?: {
+    /**
+     * Exit before oclif runs. Used for flag-only / bare `--json` usage errors so human and JSON
+     * callers share one path (no "leave a flag token for command_not_found" hack).
+     */
+    earlyExit?: {
         exitCode: number;
         envelope: Record<string, unknown>;
+        json: boolean;
     };
 }
-export declare function normalizeArgv(rawArgv: string[]): NormalizationResult;
+/** Options for {@link normalizeArgv}. */
+export interface ArgvNormalizeOptions {
+    /** Tokens that consume the next argv value (`--topic`, `-t`, …). From cli-flag-manifest. */
+    valueTakingFlags: ReadonlySet<string>;
+}
+/**
+ * Normalize raw process argv for oclif. `valueTakingFlags` must come from the composition root
+ * (`cli-flag-manifest`) — this module stays free of command registry imports.
+ */
+export declare function normalizeArgv(rawArgv: string[], options: ArgvNormalizeOptions): NormalizationResult;
+/**
+ * Non-flag positional tokens from a (typically already-normalized) argv. Skips `--help`/`--json`
+ * and any dash-prefixed flags so multi-segment command ids (`config get`) stay intact. Shared by
+ * help-preflight and json-meta — both run after `normalizeArgv` has already folded `help X` →
+ * `X --help` and `-h` → `--help`.
+ */
+export declare function positionalArgvTokens(argv: readonly string[], valueTakingFlags: ReadonlySet<string>): string[];

package/dist/lib/argv.js

@@ -1,52 +1,92 @@
-import { buildEnvelope } from './envelope.js';
+import { EXIT_USAGE } from './cli-error-policy.js';
+import { buildCliErrorEnvelope } from './envelope.js';
+/** Shared MISSING_COMMAND copy for flag-only argv preflight. */
+function missingCommandDetails(bin, swallowed) {
+    if (swallowed) {
+        return {
+            code: 'MISSING_COMMAND',
+            message: [
+                `Missing URL or command. ${swallowed.flag} consumed ${swallowed.url} as its value, so there was no URL left to fetch.`,
+                `Run ${bin} --help for usage.`,
+            ].join('\n'),
+            suggestions: [
+                `Pass the URL as the command (flags after): ${bin} ${swallowed.url}`,
+                `Or a named command: ${bin} list`,
+            ],
+        };
+    }
+    return {
+        code: 'MISSING_COMMAND',
+        message: `Missing URL or command. Run ${bin} --help for usage.`,
+        suggestions: [`Pass a URL: ${bin} https://example.com`, `Or a command: ${bin} list`],
+    };
+}
+/**
+ * Boolean flags registered on every command via BaseCommand.baseFlags. oclif only merges those after
+ * it picks a command, so `bonsai --read-only list` would otherwise treat `--read-only` as the
+ * command id. Strip and re-append them after the command/URL, same pattern as `--json`.
+ */
+const GLOBAL_BOOLEAN_FLAGS = new Set(['--read-only', '--plan']);
 /**
- * Normalizes process.argv (excluding Node executable and script path) so the
- * oclif pipeline sees one consistent command structure.
+ * When a value-taking flag is the only "command" and its value looks like a URL, the user almost
+ * certainly put the URL where the flag value belongs (e.g. `bonsai --tags https://example.com`).
  */
-function missingUsageJsonExit() {
+function findSwallowedUrlFlag(argv, valueTakingFlags) {
+    if (!argv?.length)
+        return null;
+    for (let i = 0; i < argv.length - 1; i++) {
+        const flag = argv[i];
+        if (!valueTakingFlags.has(flag))
+            continue;
+        const value = argv[i + 1];
+        if (value.startsWith('-'))
+            continue;
+        if (looksLikeUrl(value))
+            return { flag, url: value };
+    }
+    return null;
+}
+function missingUsageExit(json, argv, valueTakingFlags) {
+    const details = missingCommandDetails('bonsai', findSwallowedUrlFlag(argv, valueTakingFlags));
     return {
-        exitCode: 2,
-        envelope: buildEnvelope({
+        exitCode: EXIT_USAGE,
+        json,
+        envelope: buildCliErrorEnvelope({
             command: 'bonsai',
-            ok: false,
-            exitCode: 2,
-            stderr: 'Missing URL or command. Run bonsai --help for usage.',
-            data: null,
+            message: details.message,
+            code: details.code,
+            suggestions: details.suggestions,
         }),
     };
 }
-const FLAGS_WITH_VALUES = new Set([
-    '--topic',
-    '-t',
-    '--tags',
-    '-g',
-    '--format',
-    '--tier',
-    '--ttl',
-    '--max-age',
-    '--storage',
-    '--file',
-    '-f',
-    '--input-format',
-    '--source-url',
-    '--freshness',
-    '--artifact-type',
-    '--capture-method',
-    '--older-than',
-    '--inactive',
-    '--domain',
-    '--remote',
-    '--limit',
-]);
-export function normalizeArgv(rawArgv) {
-    const onlyJsonFlags = rawArgv.length > 0 && rawArgv.every((arg) => arg === '--json');
-    if (onlyJsonFlags) {
-        return {
-            // bin/cli.mjs exits before applying argv when exitWithJson is set.
-            argv: ['--json'],
-            exitWithJson: missingUsageJsonExit(),
-        };
+/**
+ * Index of the first positional command/URL token, skipping flags (and value-flag operands)
+ * plus root meta tokens that never name a command (`--help`, `--json`, globals).
+ */
+function firstPositionalIndex(argv, valueTakingFlags) {
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--help' || token === '--json' || GLOBAL_BOOLEAN_FLAGS.has(token))
+            continue;
+        if (token.startsWith('-')) {
+            if (valueTakingFlags.has(token))
+                i++;
+            continue;
+        }
+        return i;
     }
+    return -1;
+}
+/** True when argv selects a command, URL, or root `--version` action (not flag-only usage). */
+function hasCommandToken(argv, valueTakingFlags) {
+    return argv.includes('--version') || firstPositionalIndex(argv, valueTakingFlags) !== -1;
+}
+/**
+ * Normalize raw process argv for oclif. `valueTakingFlags` must come from the composition root
+ * (`cli-flag-manifest`) — this module stays free of command registry imports.
+ */
+export function normalizeArgv(rawArgv, options) {
+    const { valueTakingFlags } = options;
     // oclif's JSON flag is command-scoped, so `bonsai list --json` works but
     // `bonsai --json list` is otherwise parsed as an unknown command named
     // "--json". Collect every --json, append one copy after the command/URL, and
@@ -60,22 +100,20 @@ export function normalizeArgv(rawArgv) {
     }
     const helpRequested = tokens.includes('--help');
     let core = tokens.filter((arg) => arg !== '--help');
+    // Relocate base boolean flags so they survive command resolution (see GLOBAL_BOOLEAN_FLAGS).
+    const relocatedGlobals = [];
+    core = core.filter((arg) => {
+        if (!GLOBAL_BOOLEAN_FLAGS.has(arg))
+            return true;
+        if (!relocatedGlobals.includes(arg))
+            relocatedGlobals.push(arg);
+        return false;
+    });
     // Treat URL-shaped tokens as the `fetch` shorthand. Match both `https://...` and scheme-only
     // forms like `javascript:` or `data:` so fetch can reject unsupported protocols instead of oclif
     // reporting a misleading "command not found". If the invocation begins with a flag, allow common
     // flag-before-argument usage such as `bonsai --format detailed https://example.com`.
-    let firstNonFlagArgIndex = -1;
-    for (let i = 0; i < core.length; i++) {
-        const token = core[i];
-        if (token.startsWith('-')) {
-            if (FLAGS_WITH_VALUES.has(token)) {
-                i++; // skip the value
-            }
-            continue;
-        }
-        firstNonFlagArgIndex = i;
-        break;
-    }
+    const firstNonFlagArgIndex = firstPositionalIndex(core, valueTakingFlags);
     const rootFetchShape = firstNonFlagArgIndex !== -1 && looksLikeUrl(core[firstNonFlagArgIndex]);
     if (rootFetchShape) {
         const url = core[firstNonFlagArgIndex];
@@ -88,10 +126,43 @@ export function normalizeArgv(rawArgv) {
     }
     if (helpRequested)
         core.push('--help');
+    core.push(...relocatedGlobals);
     if (jsonMode)
         core.push('--json');
+    // Flag-only argv (`--json`, `--read-only`, `--tags https://…`) never resolves a command.
+    // Exit here so command_not_found does not special-case dash-prefixed ids.
+    // Empty argv and `--help`/`--version` stay with oclif.
+    if (!helpRequested && core.length > 0 && !hasCommandToken(core, valueTakingFlags)) {
+        return {
+            argv: jsonMode ? ['--json'] : [],
+            earlyExit: missingUsageExit(jsonMode, rawArgv, valueTakingFlags),
+        };
+    }
     return { argv: core };
 }
+/**
+ * Non-flag positional tokens from a (typically already-normalized) argv. Skips `--help`/`--json`
+ * and any dash-prefixed flags so multi-segment command ids (`config get`) stay intact. Shared by
+ * help-preflight and json-meta — both run after `normalizeArgv` has already folded `help X` →
+ * `X --help` and `-h` → `--help`.
+ */
+export function positionalArgvTokens(argv, valueTakingFlags) {
+    const tokens = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--')
+            break;
+        if (arg === '--help' || arg === '--json')
+            continue;
+        if (arg.startsWith('-')) {
+            if (!arg.includes('=') && valueTakingFlags.has(arg))
+                i++;
+            continue;
+        }
+        tokens.push(arg);
+    }
+    return tokens;
+}
 function looksLikeUrl(arg) {
     return arg.includes('://') || /^[a-z][a-z0-9+.-]*:/i.test(arg);
 }

package/dist/lib/batch.d.ts

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