@taurgis/bonsai 3.1.0 → 3.2.0

package/README.md

@@ -112,6 +112,7 @@ Common flags:
 * `--dry-run`: Scrape and validate without writing to cache.
 * `--allow-stale`: Serve stale cache if the remote site is offline.
 * `--rendered`: Use browser-rendered extraction for SPA pages.
+* `--read-only` (alias `--plan`): Block all filesystem writes/deletes across every command; network fetches still run. See [Read-only / plan mode](#read-only--plan-mode) below.
 * `--json`: Return structured machine-readable output.
 
 ### `import [url]`
@@ -148,7 +149,7 @@ npx @taurgis/bonsai list [flags]
 
 ### `prune`
 
-Delete old or inactive cache entries. Requires a filter (`--older-than`, `--inactive`, `--artifact-type`, or `--url`) and exactly one of `--dry-run` or `--yes` (passing both is a usage error).
+Delete old or inactive cache entries. Requires a filter (`--older-than`, `--inactive`, `--artifact-type`, or `--url`) and exactly one of `--dry-run` or `--yes` (passing both is a usage error). In [read-only mode](#read-only--plan-mode), `--yes` is rejected and the safety check is implicitly satisfied by a preview.
 
 ```bash
 npx @taurgis/bonsai prune --older-than 90d --dry-run
@@ -170,6 +171,18 @@ npx @taurgis/bonsai config set summary balanced
 
 Both keys can also be overridden per-invocation via the `BONSAI_STORAGE` and `BONSAI_SUMMARY` environment variables. Project config is stored in `.bonsai.json`; project cache files are stored under `.bonsai/research/`.
 
+### Read-only / plan mode
+
+Every command accepts a global `--read-only` flag (alias `--plan`) that blocks all filesystem writes and deletes — cache persistence, config file writes, `prune` deletions — while still allowing network fetches to run. This is for agent harnesses (Claude Code and others) that enter a read-only "plan mode": set it once and every `bonsai` invocation for the rest of that session automatically skips writes, without needing the flag on every call.
+
+```bash
+BONSAI_READ_ONLY=1 npx @taurgis/bonsai https://example.com/docs
+npx @taurgis/bonsai import https://example.com/docs --file notes.md --read-only
+npx @taurgis/bonsai prune --older-than 90d --plan
+```
+
+It can also be set via the `BONSAI_READ_ONLY` or `BONSAI_PLAN_MODE` environment variables (both are equivalent). Composition is OR, not override: read-only mode is active if *either* env var or the flag is set, and there is no way to force writes back on once one of them is — this is a safety gate, not a preference. Commands that already expose `--dry-run` (`fetch`, `prune`, `config set`/`unset`) treat it the same as an explicit `--dry-run`; `import` (which has no `--dry-run` of its own) previews the write and reports `dryRun: true` instead of persisting.
+
 ---
 
 ## Shell Autocomplete
@@ -273,6 +286,7 @@ When run with `--json`, commands return a stable envelope:
 | --- | --- |
 | `BONSAI_STORAGE` | Override the default storage location per-invocation (`global` or `project`). |
 | `BONSAI_SUMMARY` | Override the summary compression level per-invocation (`conservative`, `balanced`, or `aggressive`). |
+| `BONSAI_READ_ONLY` / `BONSAI_PLAN_MODE` | Set to `1`/`true`/`yes` to enable [read-only/plan mode](#read-only--plan-mode) for every command in the session, equivalent to passing `--read-only` (`--plan`) each time. Either variable is sufficient; there is no way to override it back off from a single invocation. |
 | `NO_COLOR` | Set to any non-empty value to disable all ANSI color output. An empty `NO_COLOR` is treated as unset. |
 | `FORCE_COLOR` | Set to any value other than an empty string, `0`, or `false` to force ANSI color on, even in non-TTY environments. |
 | `TERM=dumb` | Disables ANSI color output when the terminal cannot render escape sequences. |

package/dist/base-command.d.ts

@@ -8,6 +8,15 @@ import { type ResolveResearchTargetOptions, type ResolvedResearchTarget } from '
  */
 export declare abstract class BaseCommand<T extends typeof Command> extends Command {
     static enableJsonFlag: boolean;
+    /**
+     * Flags shared by every command. Passed as `baseFlags` to `this.parse()` in `init()` below, which
+     * is oclif's own mechanism for merging them into `this.ctor.flags` at both parse time and
+     * `--help`/manifest generation — no per-command `static flags` changes are needed to expose these.
+     * `--plan` mirrors agent-harness "plan mode" terminology; `--read-only` is the canonical name.
+     */
+    static baseFlags: {
+        'read-only': Interfaces.BooleanFlag<boolean>;
+    };
     flags: Interfaces.InferredFlags<T['flags']>;
     args: Interfaces.InferredArgs<T['args']>;
     parsedArgv: string[];
@@ -19,6 +28,14 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
      * JSON envelope, so machine output stays clean.
      */
     warn(input: string | Error): string | Error;
+    /** Whether read-only/plan mode is active for this invocation (flag OR either env var). */
+    protected get readOnly(): boolean;
+    /**
+     * Combines a command's own explicit dry-run intent with global read-only mode. Warns once (on
+     * stderr, so it never pollutes `--json`) when read-only mode is what's actually suppressing the
+     * write, so a skipped write is never a silent surprise to the caller.
+     */
+    protected effectiveDryRun(explicitDryRun: boolean): boolean;
     /**
      * 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

package/dist/base-command.js

@@ -1,5 +1,5 @@
-import { Command, Errors, toConfiguredId } from '@oclif/core';
-import { invalidEnvOverrideWarnings } from './lib/config/index.js';
+import { Command, Errors, Flags, toConfiguredId } from '@oclif/core';
+import { invalidEnvOverrideWarnings, resolveReadOnly } from './lib/config/index.js';
 import { buildEnvelope, formatErrorForJson, normalizeCliErrorMessage, stableErrorCodeFrom, } from './lib/envelope.js';
 import { resolveResearchTarget, } from './lib/research/resolve-target.js';
 import { looksLikeSchemelessUrl } from './lib/research/url.js';
@@ -11,6 +11,20 @@ import { looksLikeSchemelessUrl } from './lib/research/url.js';
  */
 export class BaseCommand extends Command {
     static enableJsonFlag = true;
+    /**
+     * Flags shared by every command. Passed as `baseFlags` to `this.parse()` in `init()` below, which
+     * is oclif's own mechanism for merging them into `this.ctor.flags` at both parse time and
+     * `--help`/manifest generation — no per-command `static flags` changes are needed to expose these.
+     * `--plan` mirrors agent-harness "plan mode" terminology; `--read-only` is the canonical name.
+     */
+    static baseFlags = {
+        'read-only': Flags.boolean({
+            aliases: ['plan'],
+            default: false,
+            description: 'Block all filesystem writes/deletes (cache and config); network fetches still run. ' +
+                'Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.',
+        }),
+    };
     flags;
     args;
     parsedArgv;
@@ -18,6 +32,7 @@ export class BaseCommand extends Command {
         await super.init();
         const { args, flags, argv } = await this.parse({
             flags: this.ctor.flags,
+            baseFlags: this.ctor.baseFlags,
             enableJsonFlag: this.ctor.enableJsonFlag,
             args: this.ctor.args,
             strict: this.ctor.strict,
@@ -41,6 +56,21 @@ export class BaseCommand extends Command {
         Errors.warn(input);
         return input;
     }
+    /** Whether read-only/plan mode is active for this invocation (flag OR either env var). */
+    get readOnly() {
+        return resolveReadOnly({ flag: Boolean(this.flags?.['read-only']), env: process.env });
+    }
+    /**
+     * Combines a command's own explicit dry-run intent with global read-only mode. Warns once (on
+     * stderr, so it never pollutes `--json`) when read-only mode is what's actually suppressing the
+     * write, so a skipped write is never a silent surprise to the caller.
+     */
+    effectiveDryRun(explicitDryRun) {
+        if (this.readOnly && !explicitDryRun) {
+            this.warn('Read-only mode active (--read-only/--plan or BONSAI_READ_ONLY/BONSAI_PLAN_MODE): skipping filesystem writes.');
+        }
+        return explicitDryRun || this.readOnly;
+    }
     /**
      * 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

package/dist/commands/config/set.js

@@ -51,7 +51,7 @@ export default class ConfigSet extends ConfigCommand {
         }
         const scope = this.writeScope(this.flags.local);
         const formatted = meta.format(parsed);
-        if (this.flags['dry-run']) {
+        if (this.effectiveDryRun(this.flags['dry-run'])) {
             if (!this.jsonEnabled())
                 this.log(`[dry-run] Would set ${keyArg} = ${formatted} (${scope})`);
             return { key: keyArg, value: parsed, scope, dryRun: true };

package/dist/commands/config/unset.js

@@ -33,7 +33,7 @@ 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.flags['dry-run']) {
+        if (this.effectiveDryRun(this.flags['dry-run'])) {
             if (!this.jsonEnabled())
                 this.log(`[dry-run] Would unset ${key} (${scope})`);
             return { key, scope, dryRun: true };

package/dist/commands/fetch.js

@@ -270,8 +270,9 @@ export default class FetchCommand extends BaseCommand {
     }
     async run() {
         const urls = this.parsedArgv;
-        const { format, ttl, 'max-age': maxAge, 'dry-run': dryRun } = this.flags;
+        const { format, ttl, 'max-age': maxAge } = this.flags;
         this.validateDurationFlags(ttl, maxAge);
+        const dryRun = this.effectiveDryRun(this.flags['dry-run']);
         const summaryLevel = loadSummaryLevel(this.config.configDir, process.cwd());
         const tmpDir = dryRun ? mkdtempSync(join(tmpdir(), 'fnr-dry-run-')) : null;
         const currentTime = new Date();

package/dist/commands/import.js

@@ -343,13 +343,16 @@ export default class ResearchImport extends BaseCommand {
             dataDir: this.config.dataDir,
             flagOverride: this.flags.storage,
         });
-        const writeResult = writeArtifactSecurely(roots, cacheKey, artifact);
+        const dryRun = this.effectiveDryRun(false);
+        const writeResult = writeArtifactSecurely(roots, cacheKey, artifact, { dryRun });
         const storagePath = getArtifactPath(writeResult.dataDir, cacheKey);
         if (writeResult.redirected) {
             this.warn(`Detected ${writeResult.secretLabel} in the imported content; stored in the global cache instead of the project to avoid committing secrets.`);
         }
         if (!this.jsonEnabled()) {
-            this.log(`Successfully imported research artifact.`);
+            this.log(dryRun
+                ? `[dry-run] Would import research artifact.`
+                : `Successfully imported research artifact.`);
             this.log(`${'Cache Key:'.padEnd(25)} ${cacheKey}`);
             this.log(`${'Storage Path:'.padEnd(25)} ${storagePath}`);
         }
@@ -357,9 +360,10 @@ export default class ResearchImport extends BaseCommand {
         return {
             schemaVersion: 1,
             command: 'import',
+            dryRun,
             cache: {
                 key: cacheKey,
-                status: 'imported',
+                status: dryRun ? 'would_import' : 'imported',
                 freshness: 'fresh',
                 path: storagePath,
                 storage: roots.mode,

package/dist/commands/prune.js

@@ -68,10 +68,21 @@ export default class ResearchPrune extends BaseCommand {
                 ],
             });
         }
+        // Checked before the generic --dry-run/--yes conflict below so a combination like
+        // `--dry-run --yes --read-only` reports the more specific READ_ONLY_MODE code, not
+        // CONFLICTING_FLAGS — read-only mode is the more fundamental constraint being violated.
+        if (this.readOnly && this.flags.yes) {
+            this.error('--yes cannot be used while read-only mode is active (--read-only/--plan or BONSAI_READ_ONLY/BONSAI_PLAN_MODE): mutations are disabled.', {
+                exit: 2,
+                code: 'READ_ONLY_MODE',
+                suggestions: [`Preview instead: ${this.config.bin} prune --dry-run`],
+            });
+        }
         if (this.flags['dry-run'] && this.flags.yes) {
             this.error('--dry-run and --yes are mutually exclusive: --dry-run previews without deleting, --yes confirms deletion. Choose one.', { exit: 2, code: 'CONFLICTING_FLAGS' });
         }
-        if (!this.flags['dry-run'] && !this.flags.yes) {
+        // Read-only mode implicitly previews, so the usual "pick one" safety check is redundant here.
+        if (!this.readOnly && !this.flags['dry-run'] && !this.flags.yes) {
             const olderThanPart = this.flags['older-than']
                 ? ` --older-than ${this.flags['older-than']}`
                 : '';
@@ -155,7 +166,7 @@ export default class ResearchPrune extends BaseCommand {
         });
         const currentTime = new Date();
         const filesToPrune = this.findPruneCandidates(roots.readRoots, currentTime);
-        const dryRun = this.flags['dry-run'];
+        const dryRun = this.effectiveDryRun(this.flags['dry-run']);
         const count = filesToPrune.length;
         // Track deletions actually performed so the JSON envelope and human output agree even when an
         // unlink fails (e.g. a permission error). Reporting candidate count as `prunedCount` would

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

@@ -1,6 +1,6 @@
 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';
+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';
 /**
  * Read both config files once and resolve the effective storage mode.

package/dist/lib/config/index.js

@@ -1,6 +1,6 @@
 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';
 /**

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;

package/dist/lib/config/resolve.js

@@ -2,6 +2,26 @@ import { BUILT_IN_DEFAULTS, STORAGE_MODES, SUMMARY_LEVELS } from './schema.js';
 /** Scoped env override, following oclif's `<BIN>_*` env-var convention for this CLI. */
 export const STORAGE_ENV_VAR = 'BONSAI_STORAGE';
 export const SUMMARY_ENV_VAR = 'BONSAI_SUMMARY';
+/** Two names for the same safety switch: `PLAN_MODE` mirrors agent-harness "plan mode" terminology. */
+export const READ_ONLY_ENV_VAR = 'BONSAI_READ_ONLY';
+export const PLAN_MODE_ENV_VAR = 'BONSAI_PLAN_MODE';
+const BOOLEAN_TRUE_VALUES = ['1', 'true', 'yes'];
+const BOOLEAN_FALSE_VALUES = ['0', 'false', 'no'];
+/**
+ * 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 function parseEnvBoolean(raw) {
+    const v = raw?.trim().toLowerCase();
+    if (!v)
+        return undefined;
+    if (BOOLEAN_TRUE_VALUES.includes(v))
+        return true;
+    if (BOOLEAN_FALSE_VALUES.includes(v))
+        return false;
+    return 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
@@ -9,18 +29,36 @@ export const SUMMARY_ENV_VAR = 'BONSAI_SUMMARY';
  * is visible without breaking the run. Returns one message per offending variable, or empty.
  */
 export function invalidEnvOverrideWarnings(env) {
+    // Each check names the var, how to tell a value is invalid, and the hint to show when it is.
     const checks = [
-        [STORAGE_ENV_VAR, STORAGE_MODES],
-        [SUMMARY_ENV_VAR, SUMMARY_LEVELS],
+        [
+            STORAGE_ENV_VAR,
+            (raw) => STORAGE_MODES.includes(raw),
+            `not one of ${STORAGE_MODES.join(', ')}. Using the configured value or default instead.`,
+        ],
+        [
+            SUMMARY_ENV_VAR,
+            (raw) => SUMMARY_LEVELS.includes(raw),
+            `not one of ${SUMMARY_LEVELS.join(', ')}. Using the configured value or default instead.`,
+        ],
+        [
+            READ_ONLY_ENV_VAR,
+            (raw) => parseEnvBoolean(raw) !== undefined,
+            'expected 1/true/yes or 0/false/no. Read-only mode was not toggled by this value.',
+        ],
+        [
+            PLAN_MODE_ENV_VAR,
+            (raw) => parseEnvBoolean(raw) !== undefined,
+            'expected 1/true/yes or 0/false/no. Read-only mode was not toggled by this value.',
+        ],
     ];
     const warnings = [];
-    for (const [name, valid] of checks) {
+    for (const [name, isValid, hint] of checks) {
         // After trim, an empty/whitespace-only value is falsy and treated as "unset" (no warning),
         // matching parseEnv*; matching is case-sensitive, so a wrong-case value is invalid and warns.
         const raw = env[name]?.trim();
-        if (raw && !valid.includes(raw)) {
-            warnings.push(`Ignoring ${name}="${raw}": not one of ${valid.join(', ')}. ` +
-                `Using the configured value or default instead.`);
+        if (raw && !isValid(raw)) {
+            warnings.push(`Ignoring ${name}="${raw}": ${hint}`);
         }
     }
     return warnings;
@@ -59,3 +97,14 @@ export function resolveSummaryLevel(input) {
         input.userConfig.summary ??
         BUILT_IN_DEFAULTS.summary);
 }
+/**
+ * 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 function resolveReadOnly(input) {
+    return Boolean(input.flag ||
+        parseEnvBoolean(input.env[READ_ONLY_ENV_VAR]) ||
+        parseEnvBoolean(input.env[PLAN_MODE_ENV_VAR]));
+}

package/dist/lib/research/secure-write.d.ts

@@ -12,5 +12,11 @@ export interface SecureWriteResult {
  * Write an artifact to the configured write root, except when it contains a secret and the
  * target is a (potentially committed) project cache — those are redirected to the global cache.
  * Returns where it landed so the caller can warn the user and report the real path.
+ *
+ * `dryRun` still runs the secret scan and reports the real would-be destination, but skips the
+ * actual `writeArtifact` persist — so a read-only preview never gives a falsely reassuring answer
+ * about where secret-bearing content would land.
  */
-export declare function writeArtifactSecurely(roots: StoreRoots, key: string, artifact: ResearchArtifact): SecureWriteResult;
+export declare function writeArtifactSecurely(roots: StoreRoots, key: string, artifact: ResearchArtifact, options?: {
+    dryRun?: boolean;
+}): SecureWriteResult;

package/dist/lib/research/secure-write.js

@@ -4,14 +4,16 @@ import { scanArtifactForSecret } from './secret-scan.js';
  * Write an artifact to the configured write root, except when it contains a secret and the
  * target is a (potentially committed) project cache — those are redirected to the global cache.
  * Returns where it landed so the caller can warn the user and report the real path.
+ *
+ * `dryRun` still runs the secret scan and reports the real would-be destination, but skips the
+ * actual `writeArtifact` persist — so a read-only preview never gives a falsely reassuring answer
+ * about where secret-bearing content would land.
  */
-export function writeArtifactSecurely(roots, key, artifact) {
+export function writeArtifactSecurely(roots, key, artifact, options = {}) {
     const isProjectWrite = roots.writeRoot !== roots.globalRoot;
     const secretLabel = isProjectWrite ? scanArtifactForSecret(artifact) : null;
-    if (secretLabel) {
-        writeArtifact(roots.globalRoot, key, artifact);
-        return { dataDir: roots.globalRoot, redirected: true, secretLabel };
-    }
-    writeArtifact(roots.writeRoot, key, artifact);
-    return { dataDir: roots.writeRoot, redirected: false, secretLabel: null };
+    const dataDir = secretLabel ? roots.globalRoot : roots.writeRoot;
+    if (!options.dryRun)
+        writeArtifact(dataDir, key, artifact);
+    return { dataDir, redirected: Boolean(secretLabel), secretLabel };
 }

package/oclif.manifest.json

@@ -28,6 +28,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "topic": {
           "char": "t",
           "description": "the main category/topic of the research for metadata tagging",
@@ -169,6 +178,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "stdin": {
           "description": "read Markdown from stdin",
           "name": "stdin",
@@ -288,6 +306,15 @@
           "name": "json",
           "allowNo": false,
           "type": "boolean"
+        },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -331,6 +358,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "topic": {
           "char": "t",
           "description": "filter by exact topic (case-insensitive)",
@@ -438,6 +474,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "older-than": {
           "description": "prune entries older than duration (e.g. \"30d\", \"90d\")",
           "name": "older-than",
@@ -525,6 +570,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "tier": {
           "description": "freshness tier policy to evaluate against",
           "name": "tier",
@@ -586,6 +640,15 @@
           "name": "json",
           "allowNo": false,
           "type": "boolean"
+        },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -627,6 +690,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "global": {
           "char": "g",
           "description": "Read from user-level config only.",
@@ -679,6 +751,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "global": {
           "char": "g",
           "description": "Show user-level config only.",
@@ -742,6 +823,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "global": {
           "char": "g",
           "description": "Write to user-level config (default).",
@@ -806,6 +896,15 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "read-only": {
+          "aliases": [
+            "plan"
+          ],
+          "description": "Block all filesystem writes/deletes (cache and config); network fetches still run. Also honored via BONSAI_READ_ONLY/BONSAI_PLAN_MODE — enable for agent read-only/plan modes.",
+          "name": "read-only",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "global": {
           "char": "g",
           "description": "Remove from user-level config (default).",
@@ -843,5 +942,5 @@
       "stdoutIsPrimaryData": true
     }
   },
-  "version": "3.1.0"
+  "version": "3.2.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taurgis/bonsai",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Bonsai is a standalone local research cache CLI for AI agents",
   "repository": {
     "type": "git",