@taurgis/bonsai 3.2.0 → 4.0.0

package/dist/commands/config/get.js

@@ -1,10 +1,10 @@
 import { Args } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { KEY_META, BUILT_IN_DEFAULTS, readScopedConfig, validKeysHint, } from '../../lib/config/index.js';
+import { formatConfigEntry, resolveConfigEntry, keyValuesHint } 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: ${validKeysHint()}.`;
+    static summary = 'Get a research configuration value';
+    static description = `Print a config value. Without --global/--local, shows the merged effective value, in precedence order: a per-command override flag (e.g. \`fetch --storage\`) > env var > project file > user file > built-in default.\n\nValid keys: ${keyValuesHint()}.`;
     static examples = [
         {
             description: 'get the effective storage mode',
@@ -20,8 +20,8 @@ export default class ConfigGet extends ConfigCommand {
     };
     static flags = {
         ...configScopeFlags({
-            global: 'Read from user-level config only.',
-            local: 'Read from project-level config only.',
+            global: 'read user-level config only',
+            local: 'read project-level config only',
         }),
     };
     static stdoutIsPrimaryData = true;
@@ -29,13 +29,9 @@ export default class ConfigGet extends ConfigCommand {
         const key = this.args.key;
         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];
-        const displayValue = value !== undefined ? value : BUILT_IN_DEFAULTS[key];
-        const formatted = meta.format(displayValue);
-        const suffix = value === undefined ? ' (not configured)' : '';
+        const entry = resolveConfigEntry(key, scope, this.config.configDir, process.cwd());
         if (!this.jsonEnabled())
-            this.log(formatted + suffix);
-        return { key, value: displayValue };
+            this.log(formatConfigEntry(entry, scope));
+        return entry;
     }
 }

package/dist/commands/config/index.js

@@ -2,7 +2,7 @@ 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 summary = 'Manage research cache configuration';
     static description = 'Show config subcommands for reading and writing Bonsai research cache configuration.';
     static examples = [
         {
@@ -10,7 +10,7 @@ export default class ConfigIndex extends BaseCommand {
             command: '<%= config.bin %> <%= command.id %> get storage',
         },
         {
-            description: 'set a configuration value for the current project',
+            description: 'set project storage mode',
             command: '<%= config.bin %> <%= command.id %> set storage project --local',
         },
     ];

package/dist/commands/config/list.js

@@ -1,9 +1,9 @@
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { ALL_KEYS, KEY_META, BUILT_IN_DEFAULTS, readScopedConfig, validKeysHint, } from '../../lib/config/index.js';
+import { formatConfigEntry, resolveConfigEntries, keyValuesHint } 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: ${validKeysHint()}.`;
+    static summary = 'List research configuration values';
+    static description = `Show every configuration key with its current value. Use --global/--local to show a single scope.\n\nValid keys: ${keyValuesHint()}.`;
     static examples = [
         {
             description: 'show all effective config values',
@@ -16,28 +16,22 @@ export default class ConfigList extends ConfigCommand {
     ];
     static flags = {
         ...configScopeFlags({
-            global: 'Show user-level config only.',
-            local: 'Show project-level config only.',
+            global: 'show user-level config only',
+            local: 'show project-level config only',
         }),
     };
     static stdoutIsPrimaryData = true;
     async run() {
         this.assertScopeFlagsExclusive(this.flags.global, this.flags.local);
         const scope = this.readScope(this.flags.global, this.flags.local);
-        const scoped = readScopedConfig(scope, this.config.configDir, process.cwd());
+        const entries = resolveConfigEntries(scope, this.config.configDir, process.cwd());
         if (!this.jsonEnabled()) {
-            const width = Math.max(...ALL_KEYS.map((k) => k.length)) + 2;
-            for (const key of ALL_KEYS) {
-                const raw = scoped[key];
-                const formatted = raw !== undefined ? KEY_META[key].format(raw) : '(not configured)';
-                this.log(`${key.padEnd(width)}${formatted}`);
+            const width = Math.max(...entries.map((e) => e.key.length)) + 2;
+            for (const entry of entries) {
+                this.log(`${entry.key.padEnd(width)}${formatConfigEntry(entry, scope)}`);
             }
         }
-        const values = {};
-        for (const key of ALL_KEYS) {
-            const raw = scoped[key];
-            values[key] = raw !== undefined ? raw : BUILT_IN_DEFAULTS[key];
-        }
-        return values;
+        // Bare array — same shape as `list`'s data payload; no `{ entries }` wrapper.
+        return entries;
     }
 }

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

@@ -1,4 +1,5 @@
 import { ConfigCommand } from './base.js';
+import type { ConfigWriteResult } from '../../lib/cli-result-types.js';
 export default class ConfigSet extends ConfigCommand<typeof ConfigSet> {
     static id: string;
     static summary: string;
@@ -17,5 +18,5 @@ export default class ConfigSet extends ConfigCommand<typeof ConfigSet> {
         local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
-    run(): Promise<unknown>;
+    run(): Promise<ConfigWriteResult>;
 }

package/dist/commands/config/set.js

@@ -1,18 +1,19 @@
 import { Args, Flags } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { KEY_META, writeUserConfig, writeProjectConfig, validKeysHint, } from '../../lib/config/index.js';
+import { KEY_META, keyValuesHint } from '../../lib/config/index.js';
+import { persistConfigPatch } from '../../lib/config-persist.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: ${validKeysHint()}. The inline form \`<key>=<value>\` is also accepted.`;
+    static summary = 'Set a research configuration key';
+    static description = 'Persist a configuration value. Writes user-level config by default; pass --local for project-level config (.bonsai.json in cwd).\n\n' +
+        `Valid keys: ${keyValuesHint()}. The inline form \`<key>=<value>\` is also accepted.`;
     static examples = [
         {
-            description: 'store research cache inside the current project',
+            description: 'store research cache in 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 with key=value',
             command: '<%= config.bin %> config set storage=global',
         },
     ];
@@ -22,11 +23,11 @@ export default class ConfigSet extends ConfigCommand {
     };
     static flags = {
         ...configScopeFlags({
-            global: 'Write to user-level config (default).',
-            local: 'Write to project-level config (.bonsai.json in cwd).',
+            global: 'write user-level config (default)',
+            local: 'write project-level config (.bonsai.json in cwd)',
         }),
         'dry-run': Flags.boolean({
-            description: 'show what would be written without saving',
+            description: 'preview write without saving',
             default: false,
         }),
     };
@@ -39,6 +40,11 @@ export default class ConfigSet extends ConfigCommand {
             this.error(`Missing required argument: value for key "${keyArg}"`, {
                 exit: 2,
                 code: 'MISSING_ARGUMENT',
+                suggestions: [
+                    meta.values
+                        ? `Use one of: ${meta.values.join(', ')}`
+                        : `Provide a value for ${keyArg}: ${meta.description}`,
+                ],
             });
         }
         const parsed = meta.parseValue(valueArg);
@@ -47,35 +53,36 @@ export default class ConfigSet extends ConfigCommand {
             this.error(`Invalid value "${valueArg}" for "${keyArg}". ${guidance}`, {
                 exit: 2,
                 code: 'INVALID_VALUE',
+                suggestions: meta.values?.map((value) => `Set ${keyArg} to "${value}": ${this.config.bin} config set ${keyArg} ${value}`),
             });
         }
         const scope = this.writeScope(this.flags.local);
         const formatted = meta.format(parsed);
-        if (this.effectiveDryRun(this.flags['dry-run'])) {
+        const dryRun = this.effectiveDryRun(this.flags['dry-run']);
+        if (dryRun) {
             if (!this.jsonEnabled())
                 this.log(`[dry-run] Would set ${keyArg} = ${formatted} (${scope})`);
-            return { key: keyArg, value: parsed, scope, dryRun: true };
+            return { key: keyArg, value: parsed, scope, dryRun: true, status: 'would_set' };
         }
-        const patch = { [keyArg]: parsed };
-        if (scope === 'project') {
-            writeProjectConfig(process.cwd(), patch);
-        }
-        else {
-            const configDir = this.config.configDir;
-            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);
+        const persisted = persistConfigPatch({
+            scope,
+            cwd: process.cwd(),
+            configDir: this.config.configDir,
+            patch: { [keyArg]: parsed },
+            action: 'set',
+            bin: this.config.bin,
+            key: keyArg,
+        });
+        if (!persisted.ok) {
+            this.error(persisted.message, {
+                exit: 1,
+                code: persisted.code,
+                suggestions: persisted.suggestions,
+            });
         }
         if (!this.jsonEnabled())
             this.log(`Set ${keyArg} = ${formatted} (${scope})`);
-        return { key: keyArg, value: parsed, scope, dryRun: false };
+        return { key: keyArg, value: parsed, scope, dryRun: false, status: 'set' };
     }
 }
 /**

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

@@ -1,4 +1,5 @@
 import { ConfigCommand } from './base.js';
+import type { ConfigWriteResult } from '../../lib/cli-result-types.js';
 export default class ConfigUnset extends ConfigCommand<typeof ConfigUnset> {
     static id: string;
     static summary: string;
@@ -16,5 +17,5 @@ export default class ConfigUnset extends ConfigCommand<typeof ConfigUnset> {
         local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static stdoutIsPrimaryData: boolean;
-    run(): Promise<unknown>;
+    run(): Promise<ConfigWriteResult>;
 }

package/dist/commands/config/unset.js

@@ -1,10 +1,11 @@
 import { Args, Flags } from '@oclif/core';
 import { ConfigCommand, configScopeFlags } from './base.js';
-import { writeUserConfig, writeProjectConfig, validKeysHint } from '../../lib/config/index.js';
+import { keyValuesHint } from '../../lib/config/index.js';
+import { persistConfigPatch } from '../../lib/config-persist.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: ${validKeysHint()}.`;
+    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: ${keyValuesHint()}.`;
     static examples = [
         {
             description: 'remove the user-level storage setting',
@@ -20,11 +21,11 @@ export default class ConfigUnset extends ConfigCommand {
     };
     static flags = {
         ...configScopeFlags({
-            global: 'Remove from user-level config (default).',
-            local: 'Remove from project-level config (.bonsai.json in cwd).',
+            global: 'remove from user-level config (default)',
+            local: 'remove from project-level config (.bonsai.json in cwd)',
         }),
         'dry-run': Flags.boolean({
-            description: 'show what would be removed without saving',
+            description: 'preview removal without saving',
             default: false,
         }),
     };
@@ -33,30 +34,30 @@ export default class ConfigUnset extends ConfigCommand {
         const key = this.args.key;
         this.validateConfigKeyAndScope(key, this.flags.global, this.flags.local);
         const scope = this.writeScope(this.flags.local);
-        if (this.effectiveDryRun(this.flags['dry-run'])) {
+        const dryRun = this.effectiveDryRun(this.flags['dry-run']);
+        if (dryRun) {
             if (!this.jsonEnabled())
                 this.log(`[dry-run] Would unset ${key} (${scope})`);
-            return { key, scope, dryRun: true };
+            return { key, scope, dryRun: true, status: 'would_unset' };
         }
-        const patch = { [key]: undefined };
-        if (scope === 'project') {
-            writeProjectConfig(process.cwd(), patch);
-        }
-        else {
-            const configDir = this.config.configDir;
-            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);
+        const persisted = persistConfigPatch({
+            scope,
+            cwd: process.cwd(),
+            configDir: this.config.configDir,
+            patch: { [key]: undefined },
+            action: 'unset',
+            bin: this.config.bin,
+            key,
+        });
+        if (!persisted.ok) {
+            this.error(persisted.message, {
+                exit: 1,
+                code: persisted.code,
+                suggestions: persisted.suggestions,
+            });
         }
         if (!this.jsonEnabled())
             this.log(`Unset ${key} (${scope})`);
-        return { key, scope, dryRun: false };
+        return { key, scope, dryRun: false, status: 'unset' };
     }
 }

package/dist/commands/fetch.d.ts

@@ -1,4 +1,5 @@
 import { BaseCommand } from '../base-command.js';
+/** Hidden named `fetch` command; usually invoked as `bonsai <url>`. */
 export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
     static id: string;
     static hidden: boolean;
@@ -26,20 +27,11 @@ export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
         storage: import("@oclif/core/interfaces").OptionFlag<"global" | "project" | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static stdoutIsPrimaryData: boolean;
-    protected envelopeCommandId(): string;
-    private executeCacheHit;
-    private executeCacheMiss;
-    private buildResultData;
-    private validateDurationFlags;
-    private emitFetchError;
-    private resolveArtifact;
-    private persistFreshArtifact;
-    private persistSectionsIfFresh;
+    /**
+     * When a multi-URL batch has any per-URL failure, keep the result array (including hits) and
+     * surface FETCH_FAILED on the envelope — same batch contract as status/inspect CACHE_MISS.
+     */
+    protected toSuccessJson(data: unknown): Record<string, unknown>;
+    private serviceFlags;
     run(): Promise<unknown>;
-    private fetchSingleTarget;
 }
-export declare function describeError(err: unknown): string;
-export declare function fetchFailureGuidance(message: string, url: string): {
-    suggestions: string[];
-    ref?: string;
-} | undefined;