@taurgis/bonsai 1.0.5 → 3.0.0

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

@@ -1,20 +1,24 @@
 import { toConfiguredId } from '@oclif/core';
-import { closestMatch } from '../../lib/text.js';
-// Nearest command must be within this edit distance to be offered as a correction. Bonsai's command
-// ids are short, so 3 catches realistic typos ("statuss", "improt") without suggesting an unrelated
-// command for input that resembles nothing.
-const MAX_SUGGESTION_DISTANCE = 3;
+import { closestMatch, maxFuzzyDistance } from '../../lib/text.js';
+import { buildEnvelope, formatErrorForJson } from '../../lib/envelope.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
  * the command. With `topicSeparator: ' '`, oclif folds every leading token of an unknown command
- * into one colon-delimited id, so `bonsai serch hello` arrives as `serch:hello`. Matching that whole
+ * into one colon-delimited id, so `bonsai lisst extra` arrives as `lisst:extra`. Matching that whole
  * string never finds a short command, so walk prefixes longest→shortest and suggest off the closest:
- * `serch:hello` resolves to nothing, but its prefix `serch` resolves to `search`. The matched prefix
+ * `lisst:extra` resolves to nothing, but its prefix `lisst` resolves to `list`. The matched prefix
  * length doubles as the command-segment count, so a folded-in positional arg is dropped from display.
  */
 function findSuggestion(segments, visibleIds) {
     for (let n = segments.length; n >= 1; n--) {
-        const suggestion = closestMatch(segments.slice(0, n).join(':'), visibleIds, MAX_SUGGESTION_DISTANCE);
+        const attempted = segments.slice(0, n).join(':');
+        const suggestion = closestMatch(attempted, visibleIds, maxFuzzyDistance(attempted));
+        if (suggestion === attempted &&
+            n < segments.length &&
+            visibleIds.some((id) => id.startsWith(`${attempted}:`))) {
+            continue;
+        }
         if (suggestion)
             return { suggestion, commandSegments: n };
     }
@@ -31,63 +35,113 @@ function topicChainLength(segments, config) {
         i++;
     return i + 1;
 }
-// Dot-separated, non-empty labels: a real domain (`docs.nestjs.com`) or IPv4 (`192.168.1.1`). The
-// URL parser also accepts a leading-dot filename (`.env`) or a relative path (`./x`) as a "host",
-// whose suggestion would be a nonsense `https://.env`; requiring well-formed labels rejects those.
-// Anchored with no overlapping quantifiers, so it is ReDoS-safe on the (already length-bounded) host.
-const DOMAIN_OR_IPV4 = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i;
+function exactZeroArgCommandPrefix(segments, visibleIds, config) {
+    for (let n = segments.length - 1; n >= 1; n--) {
+        const candidate = segments.slice(0, n).join(':');
+        if (!visibleIds.includes(candidate))
+            continue;
+        if (visibleIds.some((id) => id.startsWith(`${candidate}:`)))
+            continue;
+        const command = config.commands.find((entry) => entry.id === candidate);
+        const args = Object.keys(command?.args ?? {});
+        if (args.length > 0)
+            continue;
+        const extra = segments[n];
+        if (extra === undefined)
+            continue;
+        return { commandId: candidate, extra };
+    }
+    return null;
+}
 /**
  * The input as-typed when it looks like a URL missing its scheme (`example.com`,
  * `docs.nestjs.com/guide`), else null. `bonsai <url>` is the headline command, but bin/cli.mjs only
  * routes args carrying a `://` scheme to the fetch shorthand — so a scheme-less URL falls through to
  * `command_not_found`. A domain-shaped host separates a forgotten-scheme URL from an ordinary command
  * typo: `statuss` has no dot and never matches, while `config:frobnicate` fails to parse (the second
- * segment becomes a non-numeric port), so neither is misread as a URL.
+ * segment becomes a non-numeric port), so neither is misread as a URL. The same domain-shape test
+ * powers normalizeUrl's "missing scheme" hint, so the two entry paths stay in lockstep.
  */
 function bareUrlInput(id) {
-    if (id.includes('://'))
-        return null;
-    let hostname;
-    try {
-        hostname = new URL(`https://${id}`).hostname;
-    }
-    catch {
-        return null;
-    }
-    return DOMAIN_OR_IPV4.test(hostname) ? id : null;
+    return looksLikeSchemelessUrl(id) ? id : null;
 }
-/**
- * Typo-aware "command not found" handler. oclif fires this before printing its own terse error;
- * throwing here (via `this.error`) replaces that default with a more helpful message. A correction
- * is offered only when the nearest command is a close match, and it is never auto-run — the user
- * re-runs the corrected command themselves, so they learn the right syntax (clig.dev guidance).
- */
-const hook = async function (opts) {
-    const hiddenIds = new Set(opts.config.commands.filter((c) => c.hidden).map((c) => c.id));
-    const visibleIds = opts.config.commandIDs.filter((id) => !hiddenIds.has(id));
+function isJsonMode(argv) {
+    return argv?.includes('--json') ?? false;
+}
+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;
+}
+export function buildCommandNotFoundDetails(id, argv, config) {
+    const hiddenIds = new Set(config.commands.filter((c) => c.hidden).map((c) => c.id));
+    const visibleIds = config.commandIDs.filter((commandId) => !hiddenIds.has(commandId));
     // A scheme-less URL is the most common "not a command" mistake for this CLI, so steer the user to
     // the `bonsai <url>` shorthand with a scheme before falling back to nearest-command matching (which
     // never finds a command for a hostname). The correction is shown, never auto-run (clig.dev).
-    const bareUrl = bareUrlInput(opts.id);
+    const bareUrl = bareUrlInput(id);
     if (bareUrl) {
-        this.error([
-            `${bareUrl} is not a ${opts.config.bin} command.`,
-            `Run ${opts.config.bin} help for a list of available commands.`,
-            `Did you mean ${opts.config.bin} https://${bareUrl}? URLs need an http:// or https:// scheme.`,
-        ].join('\n'), { exit: 2 });
+        return {
+            code: 'MISSING_URL_SCHEME',
+            command: bareUrl,
+            jsonMode: isJsonMode(argv),
+            message: [
+                `${bareUrl} is not a ${config.bin} command.`,
+                `Run ${config.bin} help for a list of available commands.`,
+                `Did you mean ${config.bin} https://${bareUrl}? URLs need an http:// or https:// scheme.`,
+            ].join('\n'),
+        };
+    }
+    const segments = id.split(':');
+    const unexpected = exactZeroArgCommandPrefix(segments, visibleIds, config);
+    if (unexpected) {
+        const command = toConfiguredId(unexpected.commandId, config);
+        return {
+            code: 'UNEXPECTED_ARGUMENT',
+            command,
+            jsonMode: isJsonMode(argv),
+            message: [
+                `Unexpected argument: ${unexpected.extra}`,
+                `Run ${config.bin} ${command} --help for usage.`,
+            ].join('\n'),
+        };
     }
-    const segments = opts.id.split(':');
     const { suggestion, commandSegments } = findSuggestion(segments, visibleIds);
     // Show only the segments that name the command, never the positional args oclif folded into the id
     // (which would otherwise glue the arg on and turn `://` into ` //`).
-    const displaySegments = commandSegments || topicChainLength(segments, opts.config);
-    const attempted = toConfiguredId(segments.slice(0, displaySegments).join(':'), opts.config);
+    const displaySegments = commandSegments || topicChainLength(segments, config);
+    const attempted = toConfiguredId(segments.slice(0, displaySegments).join(':'), config);
     // Order so the most actionable line lands last, where the eye rests (clig.dev): the help pointer
     // is the floor, and a concrete "Did you mean …?" correction — when we have one — goes below it.
-    const lines = [`${attempted} is not a ${opts.config.bin} command.`];
-    lines.push(`Run ${opts.config.bin} help for a list of available commands.`);
+    const lines = [`${attempted} is not a ${config.bin} command.`];
+    lines.push(`Run ${config.bin} help for a list of available commands.`);
     if (suggestion)
-        lines.push(`Did you mean ${toConfiguredId(suggestion, opts.config)}?`);
-    this.error(lines.join('\n'), { exit: 2 });
+        lines.push(`Did you mean ${toConfiguredId(suggestion, config)}?`);
+    return {
+        code: 'COMMAND_NOT_FOUND',
+        command: attempted,
+        jsonMode: isJsonMode(argv),
+        message: lines.join('\n'),
+    };
+}
+/**
+ * Typo-aware "command not found" handler. oclif fires this before printing its own terse error;
+ * throwing here (via `this.error`) replaces that default with a more helpful message. A correction
+ * is offered only when the nearest command is a close match, and it is never auto-run — the user
+ * re-runs the corrected command themselves, so they learn the right syntax (clig.dev guidance).
+ */
+const hook = async function (opts) {
+    const details = buildCommandNotFoundDetails(opts.id, opts.argv, opts.config);
+    if (details.jsonMode)
+        return emitJsonError(details.command, details.message, details.code);
+    this.error(details.message, { exit: 2, code: details.code });
 };
 export default hook;

package/dist/lib/argv.d.ts

@@ -0,0 +1,10 @@
+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?: {
+        exitCode: number;
+        envelope: Record<string, unknown>;
+    };
+}
+export declare function normalizeArgv(rawArgv: string[]): NormalizationResult;

package/dist/lib/argv.js

@@ -0,0 +1,97 @@
+import { buildEnvelope } from './envelope.js';
+/**
+ * Normalizes process.argv (excluding Node executable and script path) so the
+ * oclif pipeline sees one consistent command structure.
+ */
+function missingUsageJsonExit() {
+    return {
+        exitCode: 2,
+        envelope: buildEnvelope({
+            command: 'bonsai',
+            ok: false,
+            exitCode: 2,
+            stderr: 'Missing URL or command. Run bonsai --help for usage.',
+            data: null,
+        }),
+    };
+}
+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(),
+        };
+    }
+    // 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
+    // dedupe repeats like `bonsai --json --json list`.
+    const jsonMode = rawArgv.includes('--json');
+    let tokens = rawArgv.filter((arg) => arg !== '--json');
+    // clig.dev: -h and --help must always work at any level.
+    tokens = tokens.map((arg) => (arg === '-h' ? '--help' : arg));
+    if (tokens[0] === 'help') {
+        tokens = [...tokens.slice(1), '--help'];
+    }
+    const helpRequested = tokens.includes('--help');
+    let core = tokens.filter((arg) => arg !== '--help');
+    // Treat URL-shaped tokens as the `fetch` shorthand. Match both `https://...` and scheme-only
+    // forms like `javascript:` or `data:` so fetch can reject unsupported protocols instead of oclif
+    // reporting a misleading "command not found". If the invocation begins with a flag, allow common
+    // flag-before-argument usage such as `bonsai --format detailed https://example.com`.
+    let firstNonFlagArgIndex = -1;
+    for (let i = 0; i < core.length; i++) {
+        const token = core[i];
+        if (token.startsWith('-')) {
+            if (FLAGS_WITH_VALUES.has(token)) {
+                i++; // skip the value
+            }
+            continue;
+        }
+        firstNonFlagArgIndex = i;
+        break;
+    }
+    const rootFetchShape = firstNonFlagArgIndex !== -1 && looksLikeUrl(core[firstNonFlagArgIndex]);
+    if (rootFetchShape) {
+        const url = core[firstNonFlagArgIndex];
+        core = [
+            'fetch',
+            url,
+            ...core.slice(0, firstNonFlagArgIndex),
+            ...core.slice(firstNonFlagArgIndex + 1),
+        ];
+    }
+    if (helpRequested)
+        core.push('--help');
+    if (jsonMode)
+        core.push('--json');
+    return { argv: core };
+}
+function looksLikeUrl(arg) {
+    return arg.includes('://') || /^[a-z][a-z0-9+.-]*:/i.test(arg);
+}

package/dist/lib/color.d.ts

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

package/dist/lib/color.js

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

package/dist/lib/envelope.d.ts

@@ -0,0 +1,36 @@
+/** Fields oclif attaches to CLIError that human pretty-print surfaces but JSON mode must mirror. */
+export interface CliErrorShape {
+    message?: string;
+    code?: string;
+    suggestions?: string[];
+    ref?: string;
+}
+/** 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. */
+export declare function normalizeCliErrorMessage(message: string): string;
+export interface EnvelopeParts {
+    command: string;
+    ok: boolean;
+    exitCode: number;
+    stderr: string;
+    data: unknown;
+    /** Stable machine-readable error code when the failure is a CLIError with `code`. */
+    code?: string;
+    suggestions?: string[];
+    ref?: string;
+}
+/**
+ * Formats a CLI error for the JSON envelope `stderr` field — same lines as human pretty-print,
+ * without ANSI or the leading "Error:" prefix (the message is already the primary line).
+ */
+export declare function formatErrorForJson(err: CliErrorShape): string;
+/**
+ * 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.
+ */
+export declare function formatEnvelope(parts: EnvelopeParts): string;

package/dist/lib/envelope.js

@@ -0,0 +1,82 @@
+/** Map oclif parse-time errors to stable Bonsai codes when the throw site did not set one. */
+export function stableErrorCodeFrom(err) {
+    const e = err;
+    if (typeof e?.code === 'string' && e.code)
+        return e.code;
+    switch (e?.constructor?.name) {
+        case 'RequiredArgsError':
+            return 'MISSING_ARGUMENT';
+        case 'FlagInvalidOptionError':
+        case 'ArgInvalidOptionError':
+            return 'INVALID_FLAG_VALUE';
+        case 'NonExistentFlagsError':
+            return 'UNKNOWN_FLAG';
+        case 'UnexpectedArgsError':
+            return 'UNEXPECTED_ARGUMENT';
+    }
+    // A flag supplied without its value throws a plain CLIError with no dedicated class to switch on,
+    // so it would otherwise reach agents with no stable code. oclif phrases it two ways: "expects a
+    // value" for a free-form flag, "expects one of these values: …" for an options-constrained flag.
+    if (typeof e?.message === 'string' &&
+        /^Flag --\S+ expects (a value$|one of these values:)/.test(e.message)) {
+        return 'MISSING_FLAG_VALUE';
+    }
+    return undefined;
+}
+/** Strip oclif's generic help suffix from JSON stderr — agents already have structured codes. */
+export function normalizeCliErrorMessage(message) {
+    const suffix = '\nSee more help with --help';
+    return message.endsWith(suffix) ? message.slice(0, -suffix.length) : message;
+}
+/**
+ * Formats a CLI error for the JSON envelope `stderr` field — same lines as human pretty-print,
+ * without ANSI or the leading "Error:" prefix (the message is already the primary line).
+ */
+export function formatErrorForJson(err) {
+    const lines = [];
+    if (err.message)
+        lines.push(err.message);
+    if (err.code)
+        lines.push(`Code: ${err.code}`);
+    if (err.suggestions?.length) {
+        if (err.suggestions.length === 1) {
+            lines.push(`Try this: ${err.suggestions[0]}`);
+        }
+        else {
+            lines.push('Try this:');
+            for (const suggestion of err.suggestions)
+                lines.push(`* ${suggestion}`);
+        }
+    }
+    if (err.ref)
+        lines.push(`Reference: ${err.ref}`);
+    return lines.join('\n');
+}
+/**
+ * Builds the standard Bonsai CLI JSON envelope structure.
+ * This is the single source of truth for the output envelope schema.
+ */
+export function buildEnvelope(parts) {
+    const envelope = {
+        schemaVersion: 1,
+        command: parts.command,
+        ok: parts.ok,
+        exitCode: parts.exitCode,
+        stdout: '',
+        stderr: parts.stderr,
+        data: parts.data,
+    };
+    if (parts.code)
+        envelope.code = parts.code;
+    if (parts.suggestions?.length)
+        envelope.suggestions = parts.suggestions;
+    if (parts.ref)
+        envelope.ref = parts.ref;
+    return envelope;
+}
+/**
+ * Formats a JSON envelope to a string with indentation.
+ */
+export function formatEnvelope(parts) {
+    return JSON.stringify(buildEnvelope(parts), null, 2);
+}

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

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

package/dist/lib/help-preflight.js

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

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

@@ -0,0 +1,10 @@
+/** 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.
+ */
+export declare function tryJsonMetaOutput(argv: readonly string[], root: string): Promise<{
+    exitCode: number;
+    envelope: Record<string, unknown>;
+} | null>;