@taurgis/bonsai 3.2.0 → 4.0.0

package/dist/commands/status.js

@@ -1,77 +1,67 @@
 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',
         },
+        {
+            description: 'check multiple URLs in one batch (space-separated)',
+            command: '<%= config.bin %> <%= command.id %> https://example.com/docs https://example.com/api',
+        },
     ];
     static strict = false;
     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,59 +72,27 @@ 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));
+            }
+            else if (result.action === 'would_revalidate') {
+                this.tip(`${this.config.bin} ${normalizedUrl} to revalidate.`);
+            }
+            else {
+                this.tip(`${this.config.bin} inspect ${normalizedUrl} for full metadata.`);
             }
-        }
-        if (result.status === 'miss' && !this.jsonEnabled()) {
-            this.warn(`Cache miss — run: ${this.config.bin} ${normalizedUrl}`);
         }
         return {
             cacheKey,
@@ -145,4 +103,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

@@ -1,9 +1,10 @@
 import { type Hook, type Interfaces } from '@oclif/core';
-export declare function buildCommandNotFoundDetails(id: string, argv: string[] | undefined, config: Interfaces.Config): {
+export declare function buildCommandNotFoundDetails(rawId: string, argv: string[] | undefined, config: Interfaces.Config): {
     code: 'COMMAND_NOT_FOUND' | 'MISSING_URL_SCHEME' | 'UNEXPECTED_ARGUMENT';
     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 { closestMatch, maxFuzzyDistance, sanitizeForTerminal } from '../../lib/text.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,64 @@ 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));
+export function buildCommandNotFoundDetails(rawId, argv, config) {
+    // The attempted id is raw user input echoed straight back into this error's message and
+    // suggestions — untrusted per the repo's trust-boundary rules, same reasoning as
+    // BaseCommand.error(). Sanitize once, up front, so every derived value below (segments, the
+    // display-only "attempted" string, a bare-URL correction) is already safe; a real command/topic id
+    // never contains control bytes, so this only affects input that could never have matched one
+    // anyway. Gate on jsonMode exactly like BaseCommand.error() does, so `--json` keeps
+    // byte-for-byte fidelity — this hook fires before a Command instance exists, so there's no
+    // `jsonEnabled()` to call, but the same boolean is cheap to compute directly from argv.
+    const jsonMode = isJsonMode(argv);
+    const id = jsonMode ? rawId : sanitizeForTerminal(rawId);
+    // 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 +135,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 +144,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 +154,7 @@ export function buildCommandNotFoundDetails(id, argv, config) {
         command: attempted,
         jsonMode: isJsonMode(argv),
         message: lines.join('\n'),
+        suggestions,
     };
 }
 /**
@@ -140,8 +165,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,36 @@
+/** 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>;
+    /**
+     * Root segment of every registered command id (`config:get` → `config`). From cli-flag-manifest.
+     * A `word:` token whose root is in this set is a command (`config:get`), never a URL scheme.
+     */
+    knownCommandRoots: 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[];