@taurgis/bonsai 3.1.0 → 3.2.2

package/dist/lib/batch.js

@@ -0,0 +1,39 @@
+import { cliErrorFields } from './envelope.js';
+import { EXIT_RUNTIME_FAILURE } from './cli-error-policy.js';
+/**
+ * Collapse a multi-URL command's per-URL rows into the CLI's single-vs-array return
+ * contract, and mark {@link EXIT_RUNTIME_FAILURE} when any row is a failure outcome.
+ *
+ * @param results - Per-URL result rows.
+ * @param isFailure - Predicate marking a row as a failure outcome.
+ * @returns The sole row when there is one URL; otherwise the full array.
+ */
+export function finalizeBatch(results, isFailure) {
+    if (results.some(isFailure))
+        process.exitCode = EXIT_RUNTIME_FAILURE;
+    return results.length === 1 ? results[0] : results;
+}
+/**
+ * status/inspect batch rows: a miss or a validation error row is a failure outcome.
+ *
+ * @param row - Batch row with a `status` field.
+ * @returns `true` when the row should fail the batch exit code.
+ */
+export function isBatchReadFailure(row) {
+    return row.status === 'miss' || row.status === 'error';
+}
+/**
+ * Sparse validation-failure row for multi-URL status/inspect. Only the fields agents need —
+ * no fake cacheKey/freshness/metadata padding.
+ *
+ * @param url - Input URL that failed validation.
+ * @param err - Error-like object with optional code/message/suggestions/ref.
+ * @returns Sparse error row for the batch result array.
+ */
+export function urlValidationErrorRow(url, err) {
+    return {
+        status: 'error',
+        normalizedUrl: url,
+        error: cliErrorFields(err),
+    };
+}

package/dist/lib/cache-view.d.ts

@@ -0,0 +1,21 @@
+import { type HumanField } from './cli-presentation.js';
+/**
+ * Shared URL / cache-key / path header used by status and inspect human output, plus any
+ * command-specific extra rows, formatted as label/value lines.
+ *
+ * @param target - Normalized URL, cache key, and store roots.
+ * @param extra - Optional additional label/value rows.
+ * @param artifactPath - Optional explicit path; defaults to the write-root artifact path.
+ * @returns Formatted human-output lines.
+ */
+export declare function formatCacheTargetHeader(target: {
+    normalizedUrl: string;
+    cacheKey: string;
+    roots: {
+        writeRoot: string;
+    };
+}, extra?: HumanField[], artifactPath?: string): string[];
+/** Stderr tip pointing at the fetch shorthand when a URL has no cache entry. */
+export declare function cacheMissHint(cliBin: string, normalizedUrl: string): string;
+/** Visual row separator between per-URL blocks in multi-URL human output; null for single URLs. */
+export declare function batchSeparator(multi: boolean): string | null;

package/dist/lib/cache-view.js

@@ -0,0 +1,30 @@
+import { colors } from './color.js';
+import { formatHumanFields } from './cli-presentation.js';
+import { getArtifactPath } from './research/storage.js';
+/**
+ * Shared URL / cache-key / path header used by status and inspect human output, plus any
+ * command-specific extra rows, formatted as label/value lines.
+ *
+ * @param target - Normalized URL, cache key, and store roots.
+ * @param extra - Optional additional label/value rows.
+ * @param artifactPath - Optional explicit path; defaults to the write-root artifact path.
+ * @returns Formatted human-output lines.
+ */
+export function formatCacheTargetHeader(target, extra = [], artifactPath) {
+    const path = artifactPath ?? getArtifactPath(target.roots.writeRoot, target.cacheKey);
+    return formatHumanFields([
+        ['URL', colors.bold(target.normalizedUrl)],
+        ['Cache Key', colors.bold(target.cacheKey)],
+        ['Cache Path', colors.gray(path)],
+        ...extra,
+    ]);
+}
+/** Stderr tip pointing at the fetch shorthand when a URL has no cache entry. */
+export function cacheMissHint(cliBin, normalizedUrl) {
+    return `Cache miss — run: ${cliBin} ${normalizedUrl}`;
+}
+const BATCH_SEPARATOR_WIDTH = 40;
+/** Visual row separator between per-URL blocks in multi-URL human output; null for single URLs. */
+export function batchSeparator(multi) {
+    return multi ? '='.repeat(BATCH_SEPARATOR_WIDTH) : null;
+}

package/dist/lib/cli-emit.d.ts

@@ -0,0 +1,28 @@
+/** Preflight early-exit payload used before oclif command dispatch. */
+export interface PreflightExit {
+    exitCode: number;
+    json: boolean;
+    envelope: Record<string, unknown>;
+}
+/**
+ * Print a preflight usage/error result (JSON envelope on stdout, or oclif-style human error) and exit.
+ *
+ * @param result - Exit code, JSON mode, and envelope to print.
+ * @returns Never — calls `process.exit()`.
+ */
+export declare function exitWithPreflight(result: PreflightExit): never;
+/**
+ * Command-not-found hook: print JSON error, set {@link EXIT_USAGE}, return envelope (no process.exit).
+ *
+ * @param options.command - Command id for the envelope.
+ * @param options.message - Human-readable error message.
+ * @param options.code - Stable error code.
+ * @param options.suggestions - Optional recovery tips.
+ * @returns The printed error envelope.
+ */
+export declare function writeCommandNotFoundJson(options: {
+    command: string;
+    message: string;
+    code: string;
+    suggestions?: string[];
+}): Record<string, unknown>;

package/dist/lib/cli-emit.js

@@ -0,0 +1,44 @@
+import { buildCliErrorEnvelope } from './envelope.js';
+import { EXIT_USAGE } from './cli-error-policy.js';
+const JSON_STDOUT_INDENT = 2;
+/** Print the envelope as pretty JSON on stdout (the machine-readable channel). */
+function printJsonEnvelope(envelope) {
+    console.log(JSON.stringify(envelope, null, JSON_STDOUT_INDENT));
+}
+/**
+ * Print a preflight usage/error result (JSON envelope on stdout, or oclif-style human error) and exit.
+ *
+ * @param result - Exit code, JSON mode, and envelope to print.
+ * @returns Never — calls `process.exit()`.
+ */
+export function exitWithPreflight(result) {
+    process.exitCode = result.exitCode;
+    const message = String(result.envelope.stderr ?? '');
+    if (result.json) {
+        printJsonEnvelope(result.envelope);
+    }
+    else if (message) {
+        console.error(` ›   Error: ${message.replaceAll('\n', '\n ›   ')}`);
+    }
+    process.exit();
+}
+/**
+ * Command-not-found hook: print JSON error, set {@link EXIT_USAGE}, return envelope (no process.exit).
+ *
+ * @param options.command - Command id for the envelope.
+ * @param options.message - Human-readable error message.
+ * @param options.code - Stable error code.
+ * @param options.suggestions - Optional recovery tips.
+ * @returns The printed error envelope.
+ */
+export function writeCommandNotFoundJson(options) {
+    const envelope = buildCliErrorEnvelope({
+        command: options.command,
+        message: options.message,
+        code: options.code,
+        suggestions: options.suggestions,
+    });
+    process.exitCode = EXIT_USAGE;
+    printJsonEnvelope(envelope);
+    return envelope;
+}

package/dist/lib/cli-error-policy.d.ts

@@ -0,0 +1,57 @@
+/** Process succeeded. */
+export declare const EXIT_OK = 0;
+/** Runtime / batch failure (agents treat as failed). */
+export declare const EXIT_RUNTIME_FAILURE = 1;
+/** Usage / validation failure (flags, URLs, missing args). */
+export declare const EXIT_USAGE = 2;
+/** Stale content served after failed revalidation; success envelope may still be `ok: true`. */
+export declare const EXIT_STALE_SERVED = 5;
+/**
+ * Resolves the process/envelope exit code from an oclif CLIError or plain Error.
+ *
+ * @param err - Error-like object with optional `oclif.exit` or `exitCode`.
+ * @returns Exit code; defaults to {@link EXIT_RUNTIME_FAILURE}.
+ */
+export declare function resolveExitCode(err: {
+    oclif?: {
+        exit?: number;
+    };
+    exitCode?: number;
+}): number;
+/** Normalized error fields shared by human pretty-print and the `--json` envelope. */
+export interface PreparedCliError {
+    exitCode: number;
+    code: string | undefined;
+    message: string | undefined;
+    suggestions: string[] | undefined;
+    ref: string | undefined;
+    stderr: string;
+}
+/**
+ * Normalize a thrown value into the fields humans and `--json` both need: stable code,
+ * suggestions (including fallbacks), and stderr lines that mirror human pretty-print.
+ *
+ * @param err - Thrown value (Error, CLIError, or unknown).
+ * @param options.bin - CLI binary name for help suggestions.
+ * @param options.command - Command id for help suggestions.
+ * @returns Prepared fields for exit handling and envelope construction.
+ */
+export declare function prepareCliError(err: unknown, options: {
+    bin: string;
+    command: string;
+}): PreparedCliError;
+/**
+ * Attach stable code + fallback suggestions onto a mutable error (human pretty-print path).
+ *
+ * @param err - Mutable error object receiving `code` / `suggestions`.
+ * @param options.bin - CLI binary name for help suggestions.
+ * @param options.command - Command id for help suggestions.
+ */
+export declare function enrichErrorForDisplay(err: {
+    code?: string;
+    suggestions?: string[];
+    message?: string;
+}, options: {
+    bin: string;
+    command: string;
+}): void;

package/dist/lib/cli-error-policy.js

@@ -0,0 +1,74 @@
+import { formatErrorForJson, normalizeCliErrorMessage, stableErrorCodeFrom, } from './envelope.js';
+/** Process succeeded. */
+export const EXIT_OK = 0;
+/** Runtime / batch failure (agents treat as failed). */
+export const EXIT_RUNTIME_FAILURE = 1;
+/** Usage / validation failure (flags, URLs, missing args). */
+export const EXIT_USAGE = 2;
+/** Stale content served after failed revalidation; success envelope may still be `ok: true`. */
+export const EXIT_STALE_SERVED = 5;
+/**
+ * Resolves the process/envelope exit code from an oclif CLIError or plain Error.
+ *
+ * @param err - Error-like object with optional `oclif.exit` or `exitCode`.
+ * @returns Exit code; defaults to {@link EXIT_RUNTIME_FAILURE}.
+ */
+export function resolveExitCode(err) {
+    return err?.oclif?.exit ?? err?.exitCode ?? EXIT_RUNTIME_FAILURE;
+}
+/** Default recovery tips when a throw site set a stable code but no suggestions. */
+function fallbackSuggestionsForCode(code, bin, command) {
+    const help = command === bin ? `${bin} --help` : `${bin} ${command} --help`;
+    switch (code) {
+        case 'UNKNOWN_FLAG':
+        case 'INVALID_FLAG_VALUE':
+        case 'MISSING_FLAG_VALUE':
+        case 'DUPLICATE_FLAG':
+        case 'MISSING_ARGUMENT':
+        case 'UNEXPECTED_ARGUMENT':
+            return [`Check usage: ${help}`];
+        case 'INVALID_DURATION':
+            return ['Use a whole number plus a unit, e.g. 2h, 7d, or 6m.'];
+        default:
+            return undefined;
+    }
+}
+/**
+ * Normalize a thrown value into the fields humans and `--json` both need: stable code,
+ * suggestions (including fallbacks), and stderr lines that mirror human pretty-print.
+ *
+ * @param err - Thrown value (Error, CLIError, or unknown).
+ * @param options.bin - CLI binary name for help suggestions.
+ * @param options.command - Command id for help suggestions.
+ * @returns Prepared fields for exit handling and envelope construction.
+ */
+export function prepareCliError(err, options) {
+    const e = err;
+    const exitCode = resolveExitCode(e);
+    const code = stableErrorCodeFrom(e);
+    const message = typeof e?.message === 'string' ? normalizeCliErrorMessage(e.message) : undefined;
+    const suggestions = e.suggestions?.length
+        ? e.suggestions
+        : fallbackSuggestionsForCode(code, options.bin, options.command);
+    const stderr = message || code || suggestions?.length || e?.ref
+        ? formatErrorForJson({ ...e, message, code, suggestions })
+        : String(err);
+    return { exitCode, code, message, suggestions, ref: e.ref, stderr };
+}
+/**
+ * Attach stable code + fallback suggestions onto a mutable error (human pretty-print path).
+ *
+ * @param err - Mutable error object receiving `code` / `suggestions`.
+ * @param options.bin - CLI binary name for help suggestions.
+ * @param options.command - Command id for help suggestions.
+ */
+export function enrichErrorForDisplay(err, options) {
+    if (!err.code) {
+        const code = stableErrorCodeFrom(err);
+        if (code)
+            err.code = code;
+    }
+    if (err.code && !err.suggestions?.length) {
+        err.suggestions = fallbackSuggestionsForCode(err.code, options.bin, options.command);
+    }
+}

package/dist/lib/cli-flag-manifest.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Composition-root flag manifest: every CLI token that consumes a following argv value.
+ * Built from command class metadata so argv normalization stays free of command imports.
+ */
+export declare const VALUE_TAKING_FLAG_TOKENS: ReadonlySet<string>;

package/dist/lib/cli-flag-manifest.js

@@ -0,0 +1,8 @@
+import { BaseCommand } from '../base-command.js';
+import { commands } from '../commands.js';
+import { valueTakingFlagTokensFromCommands } from './value-flags.js';
+/**
+ * Composition-root flag manifest: every CLI token that consumes a following argv value.
+ * Built from command class metadata so argv normalization stays free of command imports.
+ */
+export const VALUE_TAKING_FLAG_TOKENS = valueTakingFlagTokensFromCommands(commands, BaseCommand.baseFlags);

package/dist/lib/cli-presentation.d.ts

@@ -0,0 +1,39 @@
+/** Shared flag/help copy so identical flags read identically across commands. */
+export declare const CLI_FLAG_DESCRIPTIONS: {
+    readonly freshnessTierPolicy: "freshness tier policy";
+    readonly statusFreshnessTierPolicy: "freshness tier policy to evaluate; when omitted, uses the cached entry's own tier";
+    readonly fetchTtl: "TTL duration for freshness (e.g. \"2h\", \"7d\", \"6m\")";
+    readonly importTtl: "TTL duration for imported note freshness (e.g. \"2h\", \"7d\", \"6m\")";
+    readonly statusTtl: "TTL duration to evaluate freshness (e.g. \"2h\", \"7d\", \"6m\")";
+    readonly maxAge: "maximum cache age to accept (e.g. \"2h\", \"7d\", \"6m\")";
+    readonly fetchStorage: "override where this result is cached (secrets always stored globally)";
+    readonly importStorage: "override where this note is cached (secrets always stored globally)";
+    readonly fetchTopic: "main research topic for metadata";
+    readonly importTopic: "main topic for this research note";
+    readonly filterTopic: "exact topic (case-insensitive)";
+    readonly fetchTags: "taxonomic tags for this research (can be repeated)";
+    readonly importTags: "taxonomic tags (can be repeated)";
+    readonly filterTags: "tags to require (must match all)";
+    readonly format: "output format";
+    readonly readOnly: "(alias: --plan) block filesystem writes/deletes; network fetches still run; also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE";
+    readonly sourceUrlGlob: "source URL glob (case-insensitive, supports * wildcard)";
+    readonly listArtifactType: "artifact type; section children are omitted from list - use inspect to see them";
+    readonly pruneArtifactType: "artifact type to prune, including section children";
+};
+/** One human-readable label/value pair for CLI stdout. */
+export type HumanField = readonly [label: string, value: string];
+/**
+ * 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 declare function formatHumanField(label: string, value: string): string;
+/**
+ * Format many label/value lines for human CLI output.
+ *
+ * @param fields - Label/value pairs.
+ * @returns Formatted lines in the same order.
+ */
+export declare function formatHumanFields(fields: readonly HumanField[]): string[];

package/dist/lib/cli-presentation.js

@@ -0,0 +1,50 @@
+import { colors } from './color.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',
+    importTopic: 'main topic for this research note',
+    filterTopic: 'exact topic (case-insensitive)',
+    fetchTags: 'taxonomic tags for this research (can be repeated)',
+    importTags: 'taxonomic tags (can be repeated)',
+    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',
+    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',
+};
+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,88 @@
+/** 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. */
+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;
+}
+/** 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 { resolveStorageMode, resolveSummaryLevel, parseEnvStorage, parseEnvSummary, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, type ResolveStorageInput, type ResolveSummaryInput, } from './resolve.js';
-import type { ConfigValues, ResolvedConfig, StorageMode, SummaryLevel } from './schema.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 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 { resolveStorageMode, resolveSummaryLevel, parseEnvStorage, parseEnvSummary, invalidEnvOverrideWarnings, STORAGE_ENV_VAR, SUMMARY_ENV_VAR, } from './resolve.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/resolve.d.ts

@@ -2,6 +2,15 @@ import type { ConfigValues, StorageMode, SummaryLevel } from './schema.js';
 /** Scoped env override, following oclif's `<BIN>_*` env-var convention for this CLI. */
 export declare const STORAGE_ENV_VAR = "BONSAI_STORAGE";
 export declare const SUMMARY_ENV_VAR = "BONSAI_SUMMARY";
+/** Two names for the same safety switch: `PLAN_MODE` mirrors agent-harness "plan mode" terminology. */
+export declare const READ_ONLY_ENV_VAR = "BONSAI_READ_ONLY";
+export declare const PLAN_MODE_ENV_VAR = "BONSAI_PLAN_MODE";
+/**
+ * Parses a boolean-ish env value. Empty/unset is `undefined` (not present); an unrecognized
+ * non-empty value is also `undefined` (invalid — see {@link invalidEnvOverrideWarnings}), so a
+ * typo never silently reads as `true`.
+ */
+export declare function parseEnvBoolean(raw: string | undefined): boolean | undefined;
 /**
  * Warnings for Bonsai env overrides that are set but hold an unrecognized value. Such a value is
  * dropped during resolution (falling back to config/default), which would otherwise silently mask
@@ -33,3 +42,15 @@ export interface ResolveSummaryInput {
  * flag > env > project file > user file > built-in default.
  */
 export declare function resolveSummaryLevel(input: ResolveSummaryInput): SummaryLevel;
+export interface ResolveReadOnlyInput {
+    /** True when `--read-only`/`--plan` was passed on this invocation. */
+    flag: boolean;
+    env: Record<string, string | undefined>;
+}
+/**
+ * Resolve whether read-only (plan) mode is active. Unlike storage/summary, this is a safety gate
+ * rather than a preference: composition is OR, not override-by-precedence — if the flag or either
+ * env var says read-only, the run is read-only. There is no way to force writes back on when an
+ * ambient `BONSAI_READ_ONLY`/`BONSAI_PLAN_MODE` is set, by design.
+ */
+export declare function resolveReadOnly(input: ResolveReadOnlyInput): boolean;