@taurgis/bonsai 3.2.0 → 4.0.0

package/dist/lib/cli-presentation.js

@@ -0,0 +1,53 @@
+import { colors } from './color.js';
+import { MAX_TAG_LENGTH, MAX_TOPIC_LENGTH } from './research/metadata-flags.js';
+const HUMAN_LABEL_WIDTH = 25;
+// Repeated verbatim across several flag descriptions; single-use wording lives inline below.
+const DURATION_EXAMPLES = 'e.g. "2h", "7d", "6m"';
+const SECRET_STORAGE_NOTE = 'secrets always stored globally';
+/** Shared flag/help copy so identical flags read identically across commands. */
+export const CLI_FLAG_DESCRIPTIONS = {
+    freshnessTierPolicy: 'freshness tier policy',
+    statusFreshnessTierPolicy: "freshness tier policy to evaluate; when omitted, uses the cached entry's own tier",
+    fetchTtl: `TTL duration for freshness (${DURATION_EXAMPLES})`,
+    importTtl: `TTL duration for imported note freshness (${DURATION_EXAMPLES})`,
+    statusTtl: `TTL duration to evaluate freshness (${DURATION_EXAMPLES})`,
+    maxAge: `maximum cache age to accept (${DURATION_EXAMPLES})`,
+    fetchStorage: `override where this result is cached (${SECRET_STORAGE_NOTE})`,
+    importStorage: `override where this note is cached (${SECRET_STORAGE_NOTE})`,
+    fetchTopic: `main research topic for metadata (max ${MAX_TOPIC_LENGTH} chars)`,
+    importTopic: `main topic for this research note (max ${MAX_TOPIC_LENGTH} chars)`,
+    filterTopic: 'exact topic (case-insensitive)',
+    fetchTags: `taxonomic tags for this research (can be repeated, max ${MAX_TAG_LENGTH} chars each)`,
+    importTags: `taxonomic tags (can be repeated, max ${MAX_TAG_LENGTH} chars each)`,
+    filterTags: 'tags to require (must match all)',
+    format: 'output format',
+    readOnly: '(alias: --plan) block filesystem writes/deletes; network fetches still run; also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE',
+    toon: 'emit the same envelope as --json, encoded as TOON (fewer tokens); cannot be combined with --json',
+    sourceUrlGlob: 'source URL glob (case-insensitive, supports * wildcard)',
+    listArtifactType: 'artifact type; section children are omitted from list - use inspect to see them',
+    pruneArtifactType: 'artifact type to prune, including section children',
+    listFull: 'include every metadata field (cache key, path, artifact type, tags, capture method, quality notes, timestamps); default output is a minimal row (source URLs, topic, freshness, token estimate)',
+};
+function formatHumanLabel(label) {
+    const text = `${label}:`;
+    return colors.cyan(text.padEnd(Math.max(HUMAN_LABEL_WIDTH, text.length)));
+}
+/**
+ * Format one cyan-padded label/value line for human CLI output.
+ *
+ * @param label - Field label (without trailing colon).
+ * @param value - Field value.
+ * @returns A single formatted line.
+ */
+export function formatHumanField(label, value) {
+    return `${formatHumanLabel(label)} ${value}`;
+}
+/**
+ * Format many label/value lines for human CLI output.
+ *
+ * @param fields - Label/value pairs.
+ * @returns Formatted lines in the same order.
+ */
+export function formatHumanFields(fields) {
+    return fields.map(([label, value]) => formatHumanField(label, value));
+}

package/dist/lib/cli-result-types.d.ts

@@ -0,0 +1,112 @@
+/** Shared machine-facing write/result shapes for CLI JSON envelopes. */
+import type { ArtifactType, CaptureMethod, ResearchArtifactMetadata, TokenEstimate } from './research/schema.js';
+/** Result of `config set` / `config unset` for the JSON envelope. */
+export interface ConfigWriteResult {
+    key: string;
+    scope: 'user' | 'project';
+    dryRun: boolean;
+    status: 'set' | 'would_set' | 'unset' | 'would_unset';
+    value?: unknown;
+}
+/** One prune candidate row before delete/preview. */
+export interface PruneCandidate {
+    cacheKey: string;
+    path: string;
+    topic: string | null;
+    url: string;
+}
+/** Result of `prune` for the JSON envelope. */
+export interface PruneWriteResult {
+    dryRun: boolean;
+    status: 'pruned' | 'would_prune';
+    wouldPruneCount: number;
+    prunedCount: number;
+    candidateCount: number;
+    files: Array<{
+        cacheKey: string;
+        path: string;
+    }>;
+}
+/** Cache lookup outcome reported on fetch results. */
+export type CacheHitStatus = 'hit' | 'miss' | 'stale' | 'refreshed' | 'revalidated';
+/** Freshness tier for a cached entry; `none` means no entry exists. */
+export type FreshnessState = 'fresh' | 'stale_grace' | 'stale_expired' | 'none';
+/** Freshness values that appear on list rows (an entry always exists). */
+export type ListFreshness = Exclude<FreshnessState, 'none'>;
+/** One row in `list --json` output when `--full` is passed. */
+export interface ListRow {
+    cacheKey: string;
+    path: string;
+    artifactType: ArtifactType;
+    sourceUrls: string[];
+    topic: string | null;
+    tags: string[];
+    freshness: ListFreshness;
+    captureMethod: CaptureMethod | null;
+    tokenEstimate: TokenEstimate;
+    qualityNotes: string[];
+    fetchedAt: string | null;
+    validatedAt: string | null;
+}
+/**
+ * Default `list --json`/`--toon` row: the fields an agent needs to judge relevance and act next
+ * (fetch/inspect the source, gauge freshness, budget tokens) without the full metadata dump.
+ * Pass `--full` for every field on {@link ListRow}.
+ */
+export interface ListRowMinimal {
+    sourceUrls: string[];
+    topic: string | null;
+    freshness: ListFreshness;
+    tokenEstimate: TokenEstimate;
+}
+/** Aggregate counts attached to `list`'s envelope so agents skip extra round trips. */
+export interface ListSummary {
+    /** Entries matching the given filters, before `--limit` truncation. */
+    total: number;
+    /** Entries actually returned in `data` (after `--limit`). */
+    shown: number;
+    limit: number;
+    /** True when `total > shown`, i.e. more entries matched than `--limit` allowed through. */
+    truncated: boolean;
+    /** Explicit signal for `total === 0`, so an empty `data: []` is never ambiguous. */
+    empty: boolean;
+    byFreshness: Record<ListFreshness, number>;
+}
+/** Section child summary nested under an inspect hit. */
+export interface InspectSectionRow {
+    cacheKey: string;
+    anchor: string | null;
+    headingPath: string | null;
+    tokenEstimate: TokenEstimate;
+}
+/**
+ * An already-cached artifact (typically a multi-source `research_note`) that lists the requested
+ * URL among its own `source_urls`, surfaced on an `inspect` miss so the requested URL isn't
+ * mistaken for wholly uncached content when it is really a secondary source of an existing note.
+ */
+export interface InspectExistingNoteRow {
+    cacheKey: string;
+    artifactType: string;
+    topic: string | null;
+    sourceUrls: string[];
+}
+/** One row in `inspect --json` output. */
+export interface InspectRow {
+    cacheKey: string;
+    cachePath: string;
+    normalizedUrl: string;
+    status: 'hit' | 'miss';
+    metadata: ResearchArtifactMetadata | null;
+    sections: InspectSectionRow[];
+    /** Set on a miss when the URL is already a source of a different cached artifact (see above). */
+    partOfExistingNote?: InspectExistingNoteRow | null;
+}
+/** One row in `status --json` output. */
+export interface StatusRow {
+    cacheKey: string;
+    cachePath: string;
+    normalizedUrl: string;
+    status: 'hit' | 'miss' | 'stale';
+    freshness: FreshnessState;
+    action: 'would_fetch' | 'would_revalidate' | 'would_return_cached';
+}

package/dist/lib/cli-result-types.js

@@ -0,0 +1,2 @@
+/** Shared machine-facing write/result shapes for CLI JSON envelopes. */
+export {};

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

@@ -1,7 +1,7 @@
-export { type ConfigValues, type ResolvedConfig, type ConfigKey, type StorageMode, type SummaryLevel, type KeyMeta, SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
-export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
+export { type ConfigValues, type ResolvedConfig, type ConfigKey, type StorageMode, type SummaryLevel, type KeyMeta, SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, keyValuesHint, } from './schema.js';
+export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, invalidConfigFileWarnings, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
 export { resolveStorageMode, resolveSummaryLevel, resolveReadOnly, parseEnvStorage, parseEnvSummary, parseEnvBoolean, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, READ_ONLY_ENV_VAR, PLAN_MODE_ENV_VAR, type ResolveStorageInput, type ResolveSummaryInput, type ResolveReadOnlyInput, } from './resolve.js';
-import type { ConfigValues, ResolvedConfig, StorageMode, SummaryLevel } from './schema.js';
+import { type ConfigKey, type ConfigValues, type ResolvedConfig, type StorageMode, type SummaryLevel } from './schema.js';
 /**
  * Read both config files once and resolve the effective storage mode.
  * `flag` (a per-invocation `--storage` override) wins over everything else.
@@ -17,7 +17,25 @@ export declare function effectiveConfig(configDir: string | undefined, cwd: stri
 export type ConfigScope = 'global' | 'local' | 'effective';
 /**
  * The config values for a requested scope: the user file (`global`), the project file (`local`),
- * or the fully merged result (`effective`). Shared by `config get` and `config list` so the
- * scope-selection lives in one place.
+ * or the fully merged result (`effective`). Shared by write paths and callers that only need the
+ * raw scoped blob (not configured metadata).
  */
 export declare function readScopedConfig(scope: ConfigScope, configDir: string | undefined, cwd: string): Partial<ConfigValues>;
+/** One config key resolved against a scope: effective value + whether that scope set it. */
+export interface ConfigEntry {
+    key: ConfigKey;
+    value: ResolvedConfig[ConfigKey];
+    configured: boolean;
+}
+/** Resolve a single key; same semantics as {@link resolveConfigEntries}. */
+export declare function resolveConfigEntry(key: ConfigKey, scope: ConfigScope, configDir: string | undefined, cwd: string, env?: Record<string, string | undefined>): ConfigEntry;
+/**
+ * Resolve every config key for a scope. Unset keys fall back to the built-in default while
+ * `configured: false` tells agents the value is not pinned beyond that default.
+ */
+export declare function resolveConfigEntries(scope: ConfigScope, configDir: string | undefined, cwd: string, env?: Record<string, string | undefined>): ConfigEntry[];
+/**
+ * Human display for a resolved entry. Effective scope always has a usable value, so the
+ * "(not configured)" suffix is reserved for `--global`/`--local` reads where absence matters.
+ */
+export declare function formatConfigEntry(entry: ConfigEntry, scope?: ConfigScope): string;

package/dist/lib/config/index.js

@@ -1,8 +1,9 @@
-export { SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, } from './schema.js';
-export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
+export { SCHEMA_VERSION, STORAGE_MODES, SUMMARY_LEVELS, ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, isKnownKey, suggestKey, validKeysHint, keyValuesHint, } from './schema.js';
+export { readUserConfig, readProjectConfig, writeUserConfig, writeProjectConfig, invalidConfigFileWarnings, USER_CONFIG_FILENAME, PROJECT_CONFIG_FILENAME, } from './io.js';
 export { resolveStorageMode, resolveSummaryLevel, resolveReadOnly, parseEnvStorage, parseEnvSummary, parseEnvBoolean, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, READ_ONLY_ENV_VAR, PLAN_MODE_ENV_VAR, } from './resolve.js';
 import { readUserConfig, readProjectConfig } from './io.js';
-import { resolveStorageMode, resolveSummaryLevel } from './resolve.js';
+import { parseEnvStorage, parseEnvSummary, resolveStorageMode, resolveSummaryLevel, } from './resolve.js';
+import { ALL_KEYS, BUILT_IN_DEFAULTS, KEY_META, } from './schema.js';
 /**
  * Read both config files once and resolve the effective storage mode.
  * `flag` (a per-invocation `--storage` override) wins over everything else.
@@ -36,8 +37,8 @@ export function effectiveConfig(configDir, cwd) {
 }
 /**
  * The config values for a requested scope: the user file (`global`), the project file (`local`),
- * or the fully merged result (`effective`). Shared by `config get` and `config list` so the
- * scope-selection lives in one place.
+ * or the fully merged result (`effective`). Shared by write paths and callers that only need the
+ * raw scoped blob (not configured metadata).
  */
 export function readScopedConfig(scope, configDir, cwd) {
     if (scope === 'global')
@@ -46,3 +47,57 @@ export function readScopedConfig(scope, configDir, cwd) {
         return readProjectConfig(cwd);
     return effectiveConfig(configDir, cwd);
 }
+/**
+ * Whether any non-default layer pins `key`. For `--global`/`--local`, that is the file itself.
+ * For effective, project file, user file, or a valid BONSAI_* env override counts — so a bare
+ * default never reports `configured: true` just because `effectiveConfig` always fills values.
+ */
+function isKeyConfigured(key, scope, project, user, env) {
+    if (scope === 'global')
+        return key in user;
+    if (scope === 'local')
+        return key in project;
+    if (key in project || key in user)
+        return true;
+    if (key === 'storage')
+        return parseEnvStorage(env) !== undefined;
+    if (key === 'summary')
+        return parseEnvSummary(env) !== undefined;
+    return false;
+}
+function buildEntry(key, scope, project, user, env) {
+    const configured = isKeyConfigured(key, scope, project, user, env);
+    if (key === 'storage') {
+        const value = scope === 'effective'
+            ? resolveStorageMode({ env, projectConfig: project, userConfig: user })
+            : ((scope === 'global' ? user : project).storage ?? BUILT_IN_DEFAULTS.storage);
+        return { key, value, configured };
+    }
+    const value = scope === 'effective'
+        ? resolveSummaryLevel({ env, projectConfig: project, userConfig: user })
+        : ((scope === 'global' ? user : project).summary ?? BUILT_IN_DEFAULTS.summary);
+    return { key, value, configured };
+}
+/** Resolve a single key; same semantics as {@link resolveConfigEntries}. */
+export function resolveConfigEntry(key, scope, configDir, cwd, env = process.env) {
+    return buildEntry(key, scope, readProjectConfig(cwd), readUserConfig(configDir), env);
+}
+/**
+ * Resolve every config key for a scope. Unset keys fall back to the built-in default while
+ * `configured: false` tells agents the value is not pinned beyond that default.
+ */
+export function resolveConfigEntries(scope, configDir, cwd, env = process.env) {
+    const project = readProjectConfig(cwd);
+    const user = readUserConfig(configDir);
+    return ALL_KEYS.map((key) => buildEntry(key, scope, project, user, env));
+}
+/**
+ * Human display for a resolved entry. Effective scope always has a usable value, so the
+ * "(not configured)" suffix is reserved for `--global`/`--local` reads where absence matters.
+ */
+export function formatConfigEntry(entry, scope = 'local') {
+    const formatted = KEY_META[entry.key].format(entry.value);
+    if (scope === 'effective' || entry.configured)
+        return formatted;
+    return `${formatted} (not configured)`;
+}

package/dist/lib/config/io.d.ts

@@ -4,5 +4,14 @@ export declare const USER_CONFIG_FILENAME = "config.json";
 export declare const PROJECT_CONFIG_FILENAME = ".bonsai.json";
 export declare function readUserConfig(configDir: string | undefined): Partial<ConfigValues>;
 export declare function readProjectConfig(cwd: string): Partial<ConfigValues>;
+/**
+ * Warnings for the user and project config files, so a corrupted or hand-edited file that would
+ * otherwise silently degrade to `{}` (or drop just the offending key) is never a silent surprise —
+ * mirrors {@link invalidEnvOverrideWarnings} for env vars. Empty when both files are missing,
+ * unreadable, or valid.
+ *
+ * @param bin - CLI binary name (`this.config.bin`) for the "fix it" suggestion in a warning.
+ */
+export declare function invalidConfigFileWarnings(configDir: string | undefined, cwd: string, bin: string): string[];
 export declare function writeUserConfig(configDir: string, patch: Partial<ConfigValues>): void;
 export declare function writeProjectConfig(cwd: string, patch: Partial<ConfigValues>): void;

package/dist/lib/config/io.js

@@ -5,43 +5,93 @@ import { KEY_META, ALL_KEYS } from './schema.js';
 /** Global, user-level config lives in the OCLIF config dir; project config sits at the repo root. */
 export const USER_CONFIG_FILENAME = 'config.json';
 export const PROJECT_CONFIG_FILENAME = '.bonsai.json';
-/** Parse a config file, keeping only known keys with valid values. Invalid input degrades to {}. */
-function parseConfigFile(raw) {
+/**
+ * Parse a config file, keeping only known keys with valid values. Unparseable JSON, a non-object
+ * top level, or an invalid value for a known key degrades that part to "absent" rather than
+ * throwing — callers that only need values (`readUserConfig`/`readProjectConfig`) ignore
+ * `warnings`; {@link invalidConfigFileWarnings} surfaces them so the degradation is never silent.
+ */
+function parseConfigFile(filePath, raw, scopeFlag, bin) {
+    let parsed;
     try {
-        const parsed = JSON.parse(raw);
-        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
-            return {};
-        const obj = parsed;
-        const result = {};
-        for (const key of ALL_KEYS) {
-            const val = obj[key];
-            if (val !== undefined && KEY_META[key].isValid(val)) {
-                Object.assign(result, { [key]: val });
-            }
-        }
-        return result;
+        parsed = JSON.parse(raw);
     }
     catch {
-        return {};
+        return {
+            values: {},
+            warnings: [
+                `Ignoring ${filePath}: not valid JSON. Using the configured value or default instead. ` +
+                    `Fix the file by hand, or overwrite it with ${bin} config set <key> <value> ${scopeFlag}.`,
+            ],
+        };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return {
+            values: {},
+            warnings: [
+                `Ignoring ${filePath}: expected a JSON object at the top level. Using the configured value or default instead.`,
+            ],
+        };
+    }
+    const obj = parsed;
+    const values = {};
+    const warnings = [];
+    for (const key of ALL_KEYS) {
+        const val = obj[key];
+        if (val === undefined)
+            continue;
+        if (KEY_META[key].isValid(val)) {
+            Object.assign(values, { [key]: val });
+        }
+        else {
+            const validValues = KEY_META[key].values;
+            const validValuesHint = validValues ? ` Valid values: ${validValues.join(', ')}.` : '';
+            warnings.push(`Ignoring "${key}" in ${filePath}: invalid value ${JSON.stringify(val)}.${validValuesHint} ` +
+                `Using the configured value or default instead.`);
+        }
     }
+    return { values, warnings };
 }
-function readConfigFile(filePath) {
+// Only the "fix it" suggestion in a warning message names the binary; every value-only caller
+// below (readUserConfig/readProjectConfig, and transitively write*Config) discards warnings
+// entirely, so this default never reaches a user — it's a placeholder for an unused code path,
+// not a claim about the real bin name. invalidConfigFileWarnings passes the real `this.config.bin`.
+const DEFAULT_BIN = 'bonsai';
+function readConfigFile(filePath, scopeFlag, bin = DEFAULT_BIN) {
     if (!existsSync(filePath))
-        return {};
+        return { values: {}, warnings: [] };
+    let raw;
     try {
-        return parseConfigFile(readFileSync(filePath, 'utf-8'));
+        raw = readFileSync(filePath, 'utf-8');
     }
     catch {
-        return {};
+        return { values: {}, warnings: [] };
     }
+    return parseConfigFile(filePath, raw, scopeFlag, bin);
 }
 export function readUserConfig(configDir) {
     if (!configDir)
         return {};
-    return readConfigFile(join(configDir, USER_CONFIG_FILENAME));
+    return readConfigFile(join(configDir, USER_CONFIG_FILENAME), '--global').values;
 }
 export function readProjectConfig(cwd) {
-    return readConfigFile(join(cwd, PROJECT_CONFIG_FILENAME));
+    return readConfigFile(join(cwd, PROJECT_CONFIG_FILENAME), '--local').values;
+}
+/**
+ * Warnings for the user and project config files, so a corrupted or hand-edited file that would
+ * otherwise silently degrade to `{}` (or drop just the offending key) is never a silent surprise —
+ * mirrors {@link invalidEnvOverrideWarnings} for env vars. Empty when both files are missing,
+ * unreadable, or valid.
+ *
+ * @param bin - CLI binary name (`this.config.bin`) for the "fix it" suggestion in a warning.
+ */
+export function invalidConfigFileWarnings(configDir, cwd, bin) {
+    const warnings = [];
+    if (configDir) {
+        warnings.push(...readConfigFile(join(configDir, USER_CONFIG_FILENAME), '--global', bin).warnings);
+    }
+    warnings.push(...readConfigFile(join(cwd, PROJECT_CONFIG_FILENAME), '--local', bin).warnings);
+    return warnings;
 }
 function writeAtomically(filePath, data) {
     atomicWriteFile(filePath, JSON.stringify(data, null, 2) + '\n');

package/dist/lib/config/schema.d.ts

@@ -29,3 +29,5 @@ export declare function isKnownKey(key: string): key is ConfigKey;
 export declare function suggestKey(input: string): ConfigKey | undefined;
 /** Comma-joined valid key list for error messages, kept in one place. */
 export declare function validKeysHint(): string;
+/** Valid keys with their accepted values, e.g. "storage (global|project), summary (…)", for `--help` descriptions. */
+export declare function keyValuesHint(): string;

package/dist/lib/config/schema.js

@@ -40,3 +40,10 @@ export function suggestKey(input) {
 export function validKeysHint() {
     return ALL_KEYS.join(', ');
 }
+/** Valid keys with their accepted values, e.g. "storage (global|project), summary (…)", for `--help` descriptions. */
+export function keyValuesHint() {
+    return ALL_KEYS.map((key) => {
+        const { values } = KEY_META[key];
+        return values ? `${key} (${values.join('|')})` : key;
+    }).join(', ');
+}

package/dist/lib/config-persist.d.ts

@@ -0,0 +1,28 @@
+import { type ConfigKey, type ConfigValues } from './config/index.js';
+/** Scope for config writes (`user` = XDG config dir; `project` = cwd `.bonsai`). */
+export type ConfigWriteScope = 'user' | 'project';
+/** Successful config persist outcome. */
+export interface ConfigPersistResult {
+    ok: true;
+}
+/** Failed config persist outcome with stable code and recovery tips. */
+export interface ConfigPersistFailure {
+    ok: false;
+    code: 'CONFIG_DIR_UNAVAILABLE';
+    message: string;
+    suggestions: string[];
+}
+/**
+ * Persist a config patch to user or project scope. Pure of oclif — callers map failures to
+ * this.error(...). Shared by config set and unset so the write branch cannot drift.
+ */
+export declare function persistConfigPatch(opts: {
+    scope: ConfigWriteScope;
+    cwd: string;
+    configDir: string | undefined;
+    patch: Partial<ConfigValues>;
+    /** Used in failure suggestions (set vs unset). */
+    action: 'set' | 'unset';
+    bin: string;
+    key: ConfigKey;
+}): ConfigPersistResult | ConfigPersistFailure;

package/dist/lib/config-persist.js

@@ -0,0 +1,29 @@
+import { writeUserConfig, writeProjectConfig, } from './config/index.js';
+/**
+ * Persist a config patch to user or project scope. Pure of oclif — callers map failures to
+ * this.error(...). Shared by config set and unset so the write branch cannot drift.
+ */
+export function persistConfigPatch(opts) {
+    if (opts.scope === 'project') {
+        writeProjectConfig(opts.cwd, opts.patch);
+        return { ok: true };
+    }
+    if (!opts.configDir) {
+        const verb = opts.action === 'set' ? 'write' : 'remove';
+        const example = opts.action === 'set'
+            ? `${opts.bin} config set ${opts.key} <value> --local`
+            : `${opts.bin} config unset ${opts.key} --local`;
+        return {
+            ok: false,
+            code: 'CONFIG_DIR_UNAVAILABLE',
+            message: `Could not determine user config directory. Use --local to ${verb} project config.`,
+            suggestions: [
+                opts.action === 'set'
+                    ? `Write project config instead: ${example}`
+                    : `Remove project config instead: ${example}`,
+            ],
+        };
+    }
+    writeUserConfig(opts.configDir, opts.patch);
+    return { ok: true };
+}

package/dist/lib/envelope.d.ts

@@ -7,8 +7,12 @@ export interface CliErrorShape {
 }
 /** 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. */
+/**
+ * Strip oclif's generic help suffix and the `Parsing --flag` wrapper so agents and humans see the
+ * actionable message we threw (e.g. `Limit must be between 1 and 100.`) instead of the wrapper.
+ */
 export declare function normalizeCliErrorMessage(message: string): string;
+/** Machine-readable envelope fields for `--json` success and error paths. */
 export interface EnvelopeParts {
     command: string;
     ok: boolean;
@@ -25,12 +29,46 @@ export interface EnvelopeParts {
  * without ANSI or the leading "Error:" prefix (the message is already the primary line).
  */
 export declare function formatErrorForJson(err: CliErrorShape): string;
+/** Stable CLIError fields for batch failure rows (status/inspect/fetch). */
+export declare function cliErrorFields(err: {
+    code?: string;
+    message?: string;
+    suggestions?: string[];
+    ref?: string;
+}, fallbackCode?: string): {
+    code: string;
+    message: string;
+    suggestions?: string[];
+    ref?: string;
+};
+/**
+ * CACHE_MISS overlay. Message wording is fixed so status/inspect cannot drift.
+ */
+export declare function enrichCacheMissEnvelope(envelope: Record<string, unknown>, data: unknown, bin: string): Record<string, unknown>;
+/**
+ * Per-row `.error` overlay for multi-URL batches (fetch, status, inspect).
+ * Keeps prior successes in `data` and surfaces the first row's code/message.
+ */
+export declare function enrichRowErrorEnvelope(envelope: Record<string, unknown>, data: unknown): Record<string, unknown>;
+/**
+ * Partial prune unlink failure: candidates remain in `data`, envelope reports the stable code.
+ */
+export declare function enrichPrunePartialEnvelope(envelope: Record<string, unknown>, data: unknown): Record<string, unknown>;
 /**
  * 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.
+ * Usage/not-found style error envelope: message + Code (+ Try this) in `stderr`, stable `code`,
+ * and top-level `suggestions` when present. Shared by argv preflight, help-preflight, and the
+ * command_not_found hook so those paths cannot drift.
  */
-export declare function formatEnvelope(parts: EnvelopeParts): string;
+export declare function buildCliErrorEnvelope(opts: {
+    command: string;
+    message: string;
+    code: string;
+    suggestions?: string[];
+    exitCode?: number;
+    ref?: string;
+}): Record<string, unknown>;