@taurgis/bonsai 1.0.5 → 3.0.0

package/dist/base-command.d.ts

@@ -1,4 +1,5 @@
 import { Command, Interfaces } from '@oclif/core';
+import { type ResolveResearchTargetOptions, type ResolvedResearchTarget } from './lib/research/resolve-target.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`
@@ -9,10 +10,11 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
     static enableJsonFlag: boolean;
     flags: Interfaces.InferredFlags<T['flags']>;
     args: Interfaces.InferredArgs<T['args']>;
+    parsedArgv: string[];
     init(): Promise<void>;
     /**
      * Always surface warnings on stderr, even under `--json`. oclif silences `warn()` in JSON mode,
-     * but our warnings (secret-redirect, stale-serve, remote-search fallback, prune failures) are
+     * but our warnings (secret-redirect, stale-serve, prune failures) are
      * security- and freshness-relevant side effects users must see. stderr never pollutes the stdout
      * JSON envelope, so machine output stays clean.
      */
@@ -36,9 +38,23 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
             exit?: number;
         };
         exitCode?: number;
+        code?: string;
     }): Promise<any>;
     /** Command id for the JSON envelope; falls back to the binary name when a command has no id. */
     protected envelopeCommandId(): string;
+    /**
+     * Resolve a URL against the research cache, exiting on a normalization failure. A scheme-less but
+     * domain-shaped input reports MISSING_URL_SCHEME — the same code the root `bonsai <url>` shorthand
+     * uses — so an agent sees one stable code for "forgot https://" everywhere; truly unparseable input
+     * 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.
+     */
+    protected failInvalidUrl(url: string, message: string): never;
     /** Single source of truth for the `--json` envelope shape, shared by success and error output. */
     private envelope;
     /** Wrap a command's return value in the machine-readable envelope emitted under `--json`. */

package/dist/base-command.js

@@ -1,5 +1,8 @@
-import { Command, Errors } from '@oclif/core';
+import { Command, Errors, toConfiguredId } from '@oclif/core';
 import { invalidEnvOverrideWarnings } from './lib/config/index.js';
+import { buildEnvelope, formatErrorForJson, normalizeCliErrorMessage, stableErrorCodeFrom, } from './lib/envelope.js';
+import { resolveResearchTarget, } from './lib/research/resolve-target.js';
+import { looksLikeSchemelessUrl } from './lib/research/url.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`
@@ -10,9 +13,10 @@ export class BaseCommand extends Command {
     static enableJsonFlag = true;
     flags;
     args;
+    parsedArgv;
     async init() {
         await super.init();
-        const { args, flags } = await this.parse({
+        const { args, flags, argv } = await this.parse({
             flags: this.ctor.flags,
             enableJsonFlag: this.ctor.enableJsonFlag,
             args: this.ctor.args,
@@ -20,6 +24,7 @@ export class BaseCommand extends Command {
         });
         this.flags = flags;
         this.args = args;
+        this.parsedArgv = argv;
         // 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.
@@ -28,7 +33,7 @@ export class BaseCommand extends Command {
     }
     /**
      * Always surface warnings on stderr, even under `--json`. oclif silences `warn()` in JSON mode,
-     * but our warnings (secret-redirect, stale-serve, remote-search fallback, prune failures) are
+     * but our warnings (secret-redirect, stale-serve, prune failures) are
      * security- and freshness-relevant side effects users must see. stderr never pollutes the stdout
      * JSON envelope, so machine output stays clean.
      */
@@ -53,24 +58,66 @@ export class BaseCommand extends Command {
      * the shared resolver so the framework's `??` keeps it, then defer to the default behavior.
      */
     async catch(err) {
+        // Parse failures throw before `this.parse()` sets `parsed`, which makes oclif emit a spurious
+        // [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);
         return super.catch(err);
     }
     /** Command id for the JSON envelope; falls back to the binary name when a command has no id. */
     envelopeCommandId() {
-        return this.ctor.id || this.config.bin;
+        return this.ctor.id ? toConfiguredId(this.ctor.id, this.config) : this.config.bin;
+    }
+    /**
+     * Resolve a URL against the research cache, exiting on a normalization failure. A scheme-less but
+     * domain-shaped input reports MISSING_URL_SCHEME — the same code the root `bonsai <url>` shorthand
+     * uses — so an agent sees one stable code for "forgot https://" everywhere; truly unparseable input
+     * stays INVALID_URL.
+     */
+    resolveResearchTargetOrFail(url, extra) {
+        try {
+            return resolveResearchTarget({
+                configDir: this.config.configDir,
+                cwd: process.cwd(),
+                dataDir: this.config.dataDir,
+                url,
+                ...extra,
+            });
+        }
+        catch (err) {
+            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.
+     */
+    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' });
     }
     /** Single source of truth for the `--json` envelope shape, shared by success and error output. */
     envelope(parts) {
-        return {
-            schemaVersion: 1,
+        return buildEnvelope({
             command: this.envelopeCommandId(),
             ok: parts.ok,
             exitCode: parts.exitCode,
-            stdout: '',
             stderr: parts.stderr,
             data: parts.data,
-        };
+        });
     }
     /** Wrap a command's return value in the machine-readable envelope emitted under `--json`. */
     toSuccessJson(data) {
@@ -85,6 +132,20 @@ export class BaseCommand extends Command {
     toErrorJson(err) {
         const e = err;
         const exitCode = BaseCommand.exitCodeOf(e);
-        return this.envelope({ ok: false, exitCode, stderr: e?.message ?? String(err), data: null });
+        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);
+        return buildEnvelope({
+            command: this.envelopeCommandId(),
+            ok: false,
+            exitCode,
+            stderr,
+            data: null,
+            code,
+            suggestions: e.suggestions?.length ? e.suggestions : undefined,
+            ref: e.ref,
+        });
     }
 }

package/dist/commands/config/base.d.ts

@@ -12,6 +12,8 @@ export declare abstract class ConfigCommand<T extends typeof Command> extends Ba
     /** Read scope for get/list: an explicit `--global`/`--local`, else the merged effective view. */
     protected readScope(global?: boolean, local?: boolean): ConfigScope;
     protected assertKnownKey(keyArg: string): asserts keyArg is ConfigKey;
+    protected requireConfigKey(key: string | undefined): asserts key is ConfigKey;
+    protected validateConfigKeyAndScope(key: string | undefined, global?: boolean, local?: boolean): asserts key is ConfigKey;
 }
 /** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
 export declare function configScopeFlags(descriptions: {

package/dist/commands/config/base.js

@@ -8,7 +8,10 @@ import { isKnownKey, suggestKey, validKeysHint } from '../../lib/config/index.js
 export class ConfigCommand extends BaseCommand {
     assertScopeFlagsExclusive(global, local) {
         if (global && local) {
-            this.error('--global and --local are mutually exclusive.', { exit: 2 });
+            this.error('--global and --local are mutually exclusive.', {
+                exit: 2,
+                code: 'CONFLICTING_FLAGS',
+            });
         }
     }
     /** `--local` writes/reads the project file; otherwise the user-level file. */
@@ -29,9 +32,20 @@ export class ConfigCommand extends BaseCommand {
             const hint = suggestion ? ` Did you mean: ${suggestion}?` : '';
             this.error(`Unknown config key: "${keyArg}".${hint} Valid keys: ${validKeysHint()}.`, {
                 exit: 2,
+                code: 'UNKNOWN_KEY',
             });
         }
     }
+    requireConfigKey(key) {
+        if (!key) {
+            this.error('Missing required argument: key', { exit: 2, code: 'MISSING_ARGUMENT' });
+        }
+        this.assertKnownKey(key);
+    }
+    validateConfigKeyAndScope(key, global, local) {
+        this.requireConfigKey(key);
+        this.assertScopeFlagsExclusive(global, local);
+    }
 }
 /** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
 export function configScopeFlags(descriptions) {

package/dist/commands/config/get.d.ts

@@ -8,7 +8,7 @@ export default class ConfigGet extends ConfigCommand<typeof ConfigGet> {
         command: string;
     }[];
     static args: {
-        key: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        key: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static flags: {
         global: import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/config/get.js

@@ -7,16 +7,16 @@ export default class ConfigGet extends ConfigCommand {
     static description = `Print a config value. Without --global/--local, shows the merged effective value (flag > env > project > user > default).\n\nValid keys: ${validKeysHint()}.`;
     static examples = [
         {
-            description: 'Get the effective storage mode',
+            description: 'get the effective storage mode',
             command: '<%= config.bin %> config get storage',
         },
         {
-            description: 'Read only the project-level value',
+            description: 'read only the project-level value',
             command: '<%= config.bin %> config get storage --local',
         },
     ];
     static args = {
-        key: Args.string({ required: true, description: 'The configuration key to read.' }),
+        key: Args.string({ required: false, description: 'the configuration key to read' }),
     };
     static flags = {
         ...configScopeFlags({
@@ -27,8 +27,7 @@ export default class ConfigGet extends ConfigCommand {
     static stdoutIsPrimaryData = true;
     async run() {
         const key = this.args.key;
-        this.assertKnownKey(key);
-        this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
+        this.validateConfigKeyAndScope(key, this.flags.global, this.flags.local);
         const scope = this.readScope(this.flags.global, this.flags.local);
         const value = readScopedConfig(scope, this.config.configDir, process.cwd())[key];
         const meta = KEY_META[key];

package/dist/commands/config/index.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../base-command.js';
+export default class ConfigIndex extends BaseCommand<typeof ConfigIndex> {
+    static id: string;
+    static summary: string;
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static stdoutIsPrimaryData: boolean;
+    run(): Promise<unknown>;
+}

package/dist/commands/config/index.js

@@ -0,0 +1,34 @@
+import { Help, toConfiguredId } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
+export default class ConfigIndex extends BaseCommand {
+    static id = 'config';
+    static summary = 'Manage research cache storage configuration (global vs project).';
+    static description = 'Show config subcommands for reading and writing Bonsai research cache configuration.';
+    static examples = [
+        {
+            description: 'get a configuration value',
+            command: '<%= config.bin %> <%= command.id %> get storage',
+        },
+        {
+            description: 'set a configuration value for the current project',
+            command: '<%= config.bin %> <%= command.id %> set storage project --local',
+        },
+    ];
+    static stdoutIsPrimaryData = true;
+    async run() {
+        if (!this.jsonEnabled()) {
+            await new Help(this.config, this.config.pjson.oclif.helpOptions ?? {}).showHelp(['config']);
+        }
+        const commands = this.config.commands
+            .filter((c) => c.id.startsWith('config:') && !c.hidden)
+            .map((c) => ({
+            id: toConfiguredId(c.id, this.config),
+            summary: c.summary || c.description || '',
+        }))
+            .sort((a, b) => a.id.localeCompare(b.id));
+        return {
+            topic: 'config',
+            commands,
+        };
+    }
+}

package/dist/commands/config/list.js

@@ -6,11 +6,11 @@ export default class ConfigList extends ConfigCommand {
     static description = `Show every configuration key with its current value. Use --global/--local to show a single scope.\n\nValid keys: ${validKeysHint()}.`;
     static examples = [
         {
-            description: 'Show all effective config values',
+            description: 'show all effective config values',
             command: '<%= config.bin %> config list',
         },
         {
-            description: 'Show only project-level config',
+            description: 'show only project-level config',
             command: '<%= config.bin %> config list --local',
         },
     ];

package/dist/commands/config/set.js

@@ -8,17 +8,17 @@ export default class ConfigSet extends ConfigCommand {
         `Valid keys: ${validKeysHint()}. The inline form \`<key>=<value>\` is also accepted.`;
     static examples = [
         {
-            description: 'Store research cache inside the current project',
+            description: 'store research cache inside the current project',
             command: '<%= config.bin %> config set storage project --local',
         },
         {
-            description: 'Set the user-level default using the inline key=value form',
+            description: 'set the user-level default using the inline key=value form',
             command: '<%= config.bin %> config set storage=global',
         },
     ];
     static args = {
-        key: Args.string({ required: false, description: 'The configuration key to set.' }),
-        value: Args.string({ required: false, description: 'The value to assign.' }),
+        key: Args.string({ required: false, description: 'the configuration key to set' }),
+        value: Args.string({ required: false, description: 'the value to assign' }),
     };
     static flags = {
         ...configScopeFlags({
@@ -26,26 +26,28 @@ export default class ConfigSet extends ConfigCommand {
             local: 'Write to project-level config (.bonsai.json in cwd).',
         }),
         'dry-run': Flags.boolean({
-            description: 'Show what would be written without saving.',
+            description: 'show what would be written without saving',
             default: false,
         }),
     };
     static stdoutIsPrimaryData = true;
     async run() {
         const { keyArg, valueArg } = splitInlineKeyValue(this.args.key, this.args.value);
-        if (!keyArg) {
-            this.error('Missing required argument: key', { exit: 2 });
-        }
-        this.assertKnownKey(keyArg);
-        this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
+        this.validateConfigKeyAndScope(keyArg, this.flags.global, this.flags.local);
         const meta = KEY_META[keyArg];
         if (valueArg === undefined) {
-            this.error(`Missing required argument: value for key "${keyArg}"`, { exit: 2 });
+            this.error(`Missing required argument: value for key "${keyArg}"`, {
+                exit: 2,
+                code: 'MISSING_ARGUMENT',
+            });
         }
         const parsed = meta.parseValue(valueArg);
         if (!meta.isValid(parsed)) {
             const guidance = meta.values ? `Valid values: ${meta.values.join(', ')}.` : meta.description;
-            this.error(`Invalid value "${valueArg}" for "${keyArg}". ${guidance}`, { exit: 2 });
+            this.error(`Invalid value "${valueArg}" for "${keyArg}". ${guidance}`, {
+                exit: 2,
+                code: 'INVALID_VALUE',
+            });
         }
         const scope = this.writeScope(this.flags.local);
         const formatted = meta.format(parsed);
@@ -63,6 +65,10 @@ export default class ConfigSet extends ConfigCommand {
             if (!configDir) {
                 this.error('Could not determine user config directory. Use --local to write project config.', {
                     exit: 1,
+                    code: 'CONFIG_DIR_UNAVAILABLE',
+                    suggestions: [
+                        `Write project config instead: ${this.config.bin} config set <key> <value> --local`,
+                    ],
                 });
             }
             writeUserConfig(configDir, patch);

package/dist/commands/config/unset.d.ts

@@ -8,7 +8,7 @@ export default class ConfigUnset extends ConfigCommand<typeof ConfigUnset> {
         command: string;
     }[];
     static args: {
-        key: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        key: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static flags: {
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/config/unset.js

@@ -7,16 +7,16 @@ export default class ConfigUnset extends ConfigCommand {
     static description = `Delete a key from user-level config (default) or project-level config (--local), restoring the built-in default.\n\nValid keys: ${validKeysHint()}.`;
     static examples = [
         {
-            description: 'Remove the user-level storage setting',
+            description: 'remove the user-level storage setting',
             command: '<%= config.bin %> config unset storage',
         },
         {
-            description: 'Remove the project-level storage setting',
+            description: 'remove the project-level storage setting',
             command: '<%= config.bin %> config unset storage --local',
         },
     ];
     static args = {
-        key: Args.string({ required: true, description: 'The configuration key to remove.' }),
+        key: Args.string({ required: false, description: 'the configuration key to remove' }),
     };
     static flags = {
         ...configScopeFlags({
@@ -24,15 +24,14 @@ export default class ConfigUnset extends ConfigCommand {
             local: 'Remove from project-level config (.bonsai.json in cwd).',
         }),
         'dry-run': Flags.boolean({
-            description: 'Show what would be removed without saving.',
+            description: 'show what would be removed without saving',
             default: false,
         }),
     };
     static stdoutIsPrimaryData = true;
     async run() {
         const key = this.args.key;
-        this.assertKnownKey(key);
-        this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
+        this.validateConfigKeyAndScope(key, this.flags.global, this.flags.local);
         const scope = this.writeScope(this.flags.local);
         if (this.flags['dry-run']) {
             if (!this.jsonEnabled())
@@ -48,6 +47,10 @@ export default class ConfigUnset extends ConfigCommand {
             if (!configDir) {
                 this.error('Could not determine user config directory. Use --local to remove project config.', {
                     exit: 1,
+                    code: 'CONFIG_DIR_UNAVAILABLE',
+                    suggestions: [
+                        `Remove project config instead: ${this.config.bin} config unset ${key} --local`,
+                    ],
                 });
             }
             writeUserConfig(configDir, patch);

package/dist/commands/fetch.d.ts

@@ -8,6 +8,7 @@ export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
         description: string;
         command: string;
     }[];
+    static strict: boolean;
     static args: {
         url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
@@ -35,6 +36,7 @@ export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
     private persistFreshArtifact;
     private persistSectionsIfFresh;
     run(): Promise<unknown>;
+    private fetchSingleTarget;
 }
 export declare function fetchFailureGuidance(message: string, url: string): {
     suggestions: string[];