@taurgis/bonsai 1.0.4 → 1.0.6

package/bin/cli.mjs

@@ -3,20 +3,47 @@
 import { execute } from '@oclif/core';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import updateNotifier from 'update-notifier';
+import { createRequire } from 'node:module';
+
+import { normalizeArgv } from '../dist/lib/argv.js';
+import { tryJsonMetaOutput } from '../dist/lib/json-meta.js';
+
+const req = createRequire(import.meta.url);
+const pkg = req('../package.json');
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+// Normalize argv so the whole oclif pipeline sees one consistent command. oclif's
+// error handler re-reads process.argv (not the args passed to execute) when it renders
+// help on a parse error, so rewriting only the execute() args leaves the help renderer
+// trying to resolve the bare URL as a command — which crashes with a stack trace. Rewrite
+// process.argv itself so both the run path and the help/error path agree.
 const rawArgv = process.argv.slice(2);
-const [firstArg, ...restArgv] = rawArgv;
-const args =
-  firstArg === 'help'
-    ? [...restArgv, '--help']
-    : firstArg?.startsWith('http://') || firstArg?.startsWith('https://')
-      ? ['fetch', ...rawArgv]
-      : rawArgv;
+const result = normalizeArgv(rawArgv);
+
+if (result.exitWithJson) {
+  process.exitCode = result.exitWithJson.exitCode;
+  console.log(JSON.stringify(result.exitWithJson.envelope, null, 2));
+  process.exit();
+}
+
+const jsonMeta = await tryJsonMetaOutput(result.argv, __dirname + '/../');
+if (jsonMeta) {
+  process.exitCode = jsonMeta.exitCode;
+  console.log(JSON.stringify(jsonMeta.envelope, null, 2));
+  process.exit();
+}
+
+// Only notify after the exitWithJson fast-path so the notifier never fires before
+// a JSON envelope exits. Also skip under --json so agent callers never see stderr noise.
+if (!process.argv.includes('--json')) {
+  updateNotifier({ pkg }).notify();
+}
+
+process.argv = [process.argv[0], process.argv[1], ...result.argv];
 
 await execute({
-  args,
   development: false,
   dir: __dirname + '/../',
 });

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`
@@ -17,8 +18,30 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      * JSON envelope, so machine output stays clean.
      */
     warn(input: string | Error): string | Error;
+    /**
+     * The exit code an error maps to. oclif `CLIError`s carry it in `err.oclif.exit`; other errors may
+     * expose `err.exitCode`. Defined once so the process exit code (`catch`) and the JSON envelope
+     * (`toErrorJson`) can never disagree — a mismatch between these two was itself the bug this fixes.
+     */
+    private static exitCodeOf;
+    /**
+     * Align the process exit code with the code reported in the JSON envelope. oclif's default
+     * `catch` sets `process.exitCode = err.exitCode ?? 1`, but oclif `CLIError`s carry their code in
+     * `err.oclif.exit` (never `err.exitCode`), so a usage error (`this.error(msg, { exit: 2 })`) would
+     * exit the process with 1 under `--json` while `toErrorJson` correctly reports `exitCode: 2`. That
+     * contradiction breaks the deterministic-exit-code contract agents rely on. Pre-seed the code from
+     * the shared resolver so the framework's `??` keeps it, then defer to the default behavior.
+     */
+    catch(err: Error & {
+        oclif?: {
+            exit?: number;
+        };
+        exitCode?: number;
+    }): 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 with INVALID_URL on normalization failure. */
+    protected resolveResearchTargetOrFail(url: string, extra?: Pick<ResolveResearchTargetOptions, 'flagOverride' | 'lookup'>): ResolvedResearchTarget;
     /** 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,4 +1,7 @@
-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';
 /**
  * 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`
@@ -19,6 +22,11 @@ export class BaseCommand extends Command {
         });
         this.flags = flags;
         this.args = args;
+        // Surface a set-but-invalid BONSAI_* override once per run. Resolution silently drops such a
+        // value, so without this a typo'd env var would take no effect with no signal. Warnings go to
+        // stderr (even under --json), so machine output stays clean.
+        for (const warning of invalidEnvOverrideWarnings(process.env))
+            this.warn(warning);
     }
     /**
      * Always surface warnings on stderr, even under `--json`. oclif silences `warn()` in JSON mode,
@@ -30,21 +38,58 @@ export class BaseCommand extends Command {
         Errors.warn(input);
         return input;
     }
+    /**
+     * The exit code an error maps to. oclif `CLIError`s carry it in `err.oclif.exit`; other errors may
+     * expose `err.exitCode`. Defined once so the process exit code (`catch`) and the JSON envelope
+     * (`toErrorJson`) can never disagree — a mismatch between these two was itself the bug this fixes.
+     */
+    static exitCodeOf(err) {
+        return err?.oclif?.exit ?? err?.exitCode ?? 1;
+    }
+    /**
+     * Align the process exit code with the code reported in the JSON envelope. oclif's default
+     * `catch` sets `process.exitCode = err.exitCode ?? 1`, but oclif `CLIError`s carry their code in
+     * `err.oclif.exit` (never `err.exitCode`), so a usage error (`this.error(msg, { exit: 2 })`) would
+     * exit the process with 1 under `--json` while `toErrorJson` correctly reports `exitCode: 2`. That
+     * contradiction breaks the deterministic-exit-code contract agents rely on. Pre-seed the code from
+     * 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;
+        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 with INVALID_URL on normalization failure. */
+    resolveResearchTargetOrFail(url, extra) {
+        try {
+            return resolveResearchTarget({
+                configDir: this.config.configDir,
+                cwd: process.cwd(),
+                dataDir: this.config.dataDir,
+                url,
+                ...extra,
+            });
+        }
+        catch (err) {
+            this.error(`Invalid URL: ${err.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) {
@@ -58,7 +103,21 @@ export class BaseCommand extends Command {
     /** Mirror the success envelope for failures so JSON consumers get one consistent shape. */
     toErrorJson(err) {
         const e = err;
-        const exitCode = e?.oclif?.exit ?? e?.exitCode ?? 1;
-        return this.envelope({ ok: false, exitCode, stderr: e?.message ?? String(err), data: null });
+        const exitCode = BaseCommand.exitCodeOf(e);
+        const code = stableErrorCodeFrom(e);
+        const message = typeof e?.message === 'string' ? normalizeCliErrorMessage(e.message) : undefined;
+        const stderr = message || code || e?.suggestions?.length || e?.ref
+            ? formatErrorForJson({ ...e, message, code })
+            : String(err);
+        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

@@ -1,22 +1,22 @@
 import { Args } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { KEY_META, BUILT_IN_DEFAULTS, readScopedConfig } from '../../lib/config/index.js';
+import { KEY_META, BUILT_IN_DEFAULTS, readScopedConfig, validKeysHint, } from '../../lib/config/index.js';
 export default class ConfigGet extends ConfigCommand {
     static id = 'config get';
     static summary = 'Get the effective value of a research configuration key.';
-    static description = 'Print a config value. Without --global/--local, shows the merged effective value (flag > env > project > user > default).\n\nValid keys: storage.';
+    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

@@ -1,16 +1,16 @@
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { ALL_KEYS, KEY_META, BUILT_IN_DEFAULTS, readScopedConfig } from '../../lib/config/index.js';
+import { ALL_KEYS, KEY_META, BUILT_IN_DEFAULTS, readScopedConfig, validKeysHint, } from '../../lib/config/index.js';
 export default class ConfigList extends ConfigCommand {
     static id = 'config list';
     static summary = 'List all research configuration keys and their effective values.';
-    static description = 'Show every configuration key with its current value. Use --global/--local to show a single scope.\n\nValid keys: storage.';
+    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

@@ -1,24 +1,24 @@
 import { Args, Flags } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { KEY_META, writeUserConfig, writeProjectConfig } from '../../lib/config/index.js';
+import { KEY_META, writeUserConfig, writeProjectConfig, validKeysHint, } from '../../lib/config/index.js';
 export default class ConfigSet extends ConfigCommand {
     static id = 'config set';
     static summary = 'Set a research configuration key.';
     static description = 'Persist a configuration value. Writes user-level config by default; pass --local to write the project-level config (.bonsai.json in cwd).\n\n' +
-        'Valid keys: storage. The inline form `<key>=<value>` is also accepted.';
+        `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

@@ -1,22 +1,22 @@
 import { Args, Flags } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { writeUserConfig, writeProjectConfig } from '../../lib/config/index.js';
+import { writeUserConfig, writeProjectConfig, validKeysHint } from '../../lib/config/index.js';
 export default class ConfigUnset extends ConfigCommand {
     static id = 'config unset';
     static summary = 'Remove a research configuration key.';
-    static description = 'Delete a key from user-level config (default) or project-level config (--local), restoring the built-in default.\n\nValid keys: storage.';
+    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

@@ -30,8 +30,13 @@ export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
     private executeCacheMiss;
     private buildResultData;
     private validateDurationFlags;
+    private emitFetchError;
     private resolveArtifact;
     private persistFreshArtifact;
     private persistSectionsIfFresh;
     run(): Promise<unknown>;
 }
+export declare function fetchFailureGuidance(message: string, url: string): {
+    suggestions: string[];
+    ref?: string;
+} | undefined;