@taurgis/bonsai 3.2.0 → 4.0.0

package/dist/lib/envelope.js

@@ -1,3 +1,5 @@
+import { EXIT_RUNTIME_FAILURE } from './cli-error-policy.js';
+import { pluralize } from './text.js';
 /** Map oclif parse-time errors to stable Bonsai codes when the throw site did not set one. */
 export function stableErrorCodeFrom(err) {
     const e = err;
@@ -21,10 +23,23 @@ export function stableErrorCodeFrom(err) {
         /^Flag --\S+ expects (a value$|one of these values:)/.test(e.message)) {
         return 'MISSING_FLAG_VALUE';
     }
+    // Repeating a single-value flag (e.g. `--topic a --topic b`) is also a plain CLIError with no
+    // dedicated class — oclif's parser rejects it before any flag-specific validation runs.
+    if (typeof e?.message === 'string' && /^Flag --\S+ can only be specified once$/.test(e.message)) {
+        return 'DUPLICATE_FLAG';
+    }
     return undefined;
 }
-/** Strip oclif's generic help suffix from JSON stderr — agents already have structured codes. */
+/** oclif wraps custom flag parse failures as `Parsing --name \n\t…\nSee more help with --help`. */
+const PARSING_WRAPPER = /^Parsing --\S+ \n\t([\s\S]*?)(?:\nSee more help with --help)?$/;
+/**
+ * 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 function normalizeCliErrorMessage(message) {
+    const wrapped = message.match(PARSING_WRAPPER);
+    if (wrapped?.[1])
+        return wrapped[1];
     const suffix = '\nSee more help with --help';
     return message.endsWith(suffix) ? message.slice(0, -suffix.length) : message;
 }
@@ -52,6 +67,125 @@ export function formatErrorForJson(err) {
         lines.push(`Reference: ${err.ref}`);
     return lines.join('\n');
 }
+/** Stable CLIError fields for batch failure rows (status/inspect/fetch). */
+export function cliErrorFields(err, fallbackCode = 'INVALID_URL') {
+    return {
+        code: typeof err.code === 'string' && err.code ? err.code : fallbackCode,
+        message: typeof err.message === 'string' ? err.message : String(err),
+        suggestions: err.suggestions,
+        ref: err.ref,
+    };
+}
+/**
+ * Overlay a batch failure onto a success envelope while keeping per-row `data`.
+ * Shared by multi-URL status/inspect (CACHE_MISS) and fetch/row errors.
+ */
+function enrichBatchFailureEnvelope(envelope, data, opts) {
+    const list = Array.isArray(data) ? data : [data];
+    const failures = list.map(opts.pick).filter(Boolean);
+    if (failures.length === 0)
+        return envelope;
+    const first = failures[0];
+    const code = typeof opts.code === 'function' ? opts.code(first, failures) : opts.code;
+    const suggestions = opts.suggestions?.(failures);
+    const ref = opts.ref?.(first);
+    const stderr = formatErrorForJson({
+        message: opts.message(first, failures),
+        code,
+        suggestions,
+        ref,
+    });
+    return {
+        ...envelope,
+        ok: false,
+        exitCode: opts.exitCode ?? 1,
+        stderr,
+        code,
+        suggestions,
+        ref,
+    };
+}
+/**
+ * CACHE_MISS overlay. Message wording is fixed so status/inspect cannot drift.
+ */
+export function enrichCacheMissEnvelope(envelope, data, bin) {
+    return enrichBatchFailureEnvelope(envelope, data, {
+        pick: (row) => {
+            const r = row;
+            return r?.status === 'miss' ? r : null;
+        },
+        code: 'CACHE_MISS',
+        exitCode: EXIT_RUNTIME_FAILURE,
+        message: (first, failures) => {
+            const url = first.normalizedUrl ?? '';
+            const otherCount = failures.length - 1;
+            return otherCount > 0
+                ? `Cache miss for ${url} and ${otherCount} other ${pluralize(otherCount, 'URL', 'URLs')}`
+                : `Cache miss for ${url}`;
+        },
+        // A URL that is already a secondary source of a different cached artifact must not be pointed
+        // at a plain fetch — that would create an unrelated duplicate entry instead of finding the
+        // note that already covers it.
+        suggestions: (failures) => failures.map((m) => m.partOfExistingNote
+            ? `Find it with: ${bin} list --url "${m.normalizedUrl}"`
+            : `Fetch and cache it first: ${bin} ${m.normalizedUrl}`),
+    });
+}
+/**
+ * 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 function enrichRowErrorEnvelope(envelope, data) {
+    return enrichBatchFailureEnvelope(envelope, data, {
+        pick: (row) => {
+            if (!row || typeof row !== 'object')
+                return null;
+            return row.error ?? null;
+        },
+        code: (first) => first.code ?? 'FETCH_FAILED',
+        message: (first, failures) => {
+            const otherCount = failures.length - 1;
+            const suffix = otherCount > 0
+                ? `\n…and ${otherCount} other URL ${pluralize(otherCount, 'failure', 'failures')}`
+                : '';
+            return (first.message ?? '') + suffix;
+        },
+        suggestions: (failures) => failures[0]?.suggestions,
+        ref: (first) => first.ref,
+        exitCode: EXIT_RUNTIME_FAILURE,
+    });
+}
+/**
+ * Partial prune unlink failure: candidates remain in `data`, envelope reports the stable code.
+ */
+export function enrichPrunePartialEnvelope(envelope, data) {
+    if (!isPruneCounts(data))
+        return envelope;
+    // A dry run never deletes anything, so prunedCount is always 0 by design — that is a preview,
+    // not a partial failure, and must never be reported as one.
+    if (data.dryRun)
+        return envelope;
+    if (data.candidateCount <= 0 || data.prunedCount >= data.candidateCount)
+        return envelope;
+    const failed = data.candidateCount - data.prunedCount;
+    const code = 'PRUNE_PARTIAL_FAILURE';
+    const message = `Failed to delete ${failed} of ${data.candidateCount} cache ${failed === 1 ? 'entry' : 'entries'}.`;
+    return {
+        ...envelope,
+        ok: false,
+        exitCode: EXIT_RUNTIME_FAILURE,
+        code,
+        stderr: formatErrorForJson({ message, code }),
+    };
+}
+function isPruneCounts(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const d = data;
+    return (typeof d.prunedCount === 'number' &&
+        typeof d.candidateCount === 'number' &&
+        typeof d.dryRun === 'boolean');
+}
 /**
  * Builds the standard Bonsai CLI JSON envelope structure.
  * This is the single source of truth for the output envelope schema.
@@ -75,8 +209,24 @@ export function buildEnvelope(parts) {
     return envelope;
 }
 /**
- * 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 function formatEnvelope(parts) {
-    return JSON.stringify(buildEnvelope(parts), null, 2);
+export function buildCliErrorEnvelope(opts) {
+    return buildEnvelope({
+        command: opts.command,
+        ok: false,
+        exitCode: opts.exitCode ?? 2,
+        stderr: formatErrorForJson({
+            message: opts.message,
+            code: opts.code,
+            suggestions: opts.suggestions,
+            ref: opts.ref,
+        }),
+        data: null,
+        code: opts.code,
+        suggestions: opts.suggestions?.length ? opts.suggestions : undefined,
+        ref: opts.ref,
+    });
 }

package/dist/lib/help-preflight.d.ts

@@ -1,15 +1,12 @@
-type UnknownHelpResult = {
-    exitCode: 2;
-    kind: 'human';
-    message: string;
-} | {
+import { EXIT_USAGE } from './cli-error-policy.js';
+/** Always an envelope — human and JSON share one formatted stderr (Code + Try this). */
+export type UnknownHelpResult = {
+    exitCode: typeof EXIT_USAGE;
     envelope: Record<string, unknown>;
-    exitCode: 2;
-    kind: 'json';
+    json: boolean;
 };
 /**
  * oclif resolves help before its command_not_found hook, so `bonsai config gett --help` otherwise
  * falls back to a terse framework error. Catch that narrow case and reuse the normal typo guidance.
  */
 export declare function tryUnknownHelpOutput(argv: readonly string[], root: string): Promise<UnknownHelpResult | null>;
-export {};

package/dist/lib/help-preflight.js

@@ -1,22 +1,12 @@
 import { Config } from '@oclif/core';
-import { buildEnvelope } from './envelope.js';
+import { positionalArgvTokens } from './argv.js';
+import { EXIT_USAGE } from './cli-error-policy.js';
+import { VALUE_TAKING_FLAG_TOKENS } from './cli-flag-manifest.js';
+import { buildCliErrorEnvelope } from './envelope.js';
 import { buildCommandNotFoundDetails } from '../hooks/command-not-found/suggest.js';
 function commandId(parts) {
     return parts.join(':');
 }
-function positionalTokens(argv) {
-    const tokens = [];
-    for (const arg of argv) {
-        if (arg === '--')
-            break;
-        if (arg === '--help' || arg === '--json')
-            continue;
-        if (arg.startsWith('-'))
-            continue;
-        tokens.push(arg);
-    }
-    return tokens;
-}
 function commandPrefixLength(tokens, config) {
     let longest = 0;
     for (let n = 1; n <= tokens.length; n++) {
@@ -51,7 +41,7 @@ function hasValidHelpTarget(tokens, config) {
 export async function tryUnknownHelpOutput(argv, root) {
     if (!argv.includes('--help'))
         return null;
-    const tokens = positionalTokens(argv);
+    const tokens = positionalArgvTokens(argv, VALUE_TAKING_FLAG_TOKENS);
     if (tokens.length === 0)
         return null;
     const config = await Config.load({ root });
@@ -59,23 +49,14 @@ export async function tryUnknownHelpOutput(argv, root) {
         return null;
     const attemptedId = commandId(tokens);
     const details = buildCommandNotFoundDetails(attemptedId, [...argv], config);
-    if (argv.includes('--json')) {
-        return {
-            kind: 'json',
-            exitCode: 2,
-            envelope: buildEnvelope({
-                command: details.command,
-                ok: false,
-                exitCode: 2,
-                stderr: `${details.message}\nCode: ${details.code}`,
-                data: null,
-                code: details.code,
-            }),
-        };
-    }
     return {
-        kind: 'human',
-        exitCode: 2,
-        message: `${details.message}\nCode: ${details.code}`,
+        exitCode: EXIT_USAGE,
+        json: argv.includes('--json'),
+        envelope: buildCliErrorEnvelope({
+            command: details.command,
+            message: details.message,
+            code: details.code,
+            suggestions: details.suggestions,
+        }),
     };
 }

package/dist/lib/json-meta.d.ts

@@ -1,5 +1,3 @@
-/** True when argv asks for help or version together with --json. */
-export declare function isJsonMetaRequest(argv: readonly string[]): boolean;
 /**
  * When `--json` is combined with `--help` or `--version`, oclif would print human text to stdout.
  * Render the same content inside the standard Bonsai JSON envelope instead.

package/dist/lib/json-meta.js

@@ -1,12 +1,14 @@
 import { Config, Help, toConfiguredId } from '@oclif/core';
+import { positionalArgvTokens } from './argv.js';
+import { EXIT_OK, EXIT_RUNTIME_FAILURE } from './cli-error-policy.js';
+import { VALUE_TAKING_FLAG_TOKENS } from './cli-flag-manifest.js';
 import { buildEnvelope } from './envelope.js';
 /** Strip ANSI color codes so JSON help text stays machine-stable. */
 function stripAnsi(text) {
-    // eslint-disable-next-line no-control-regex
     return text.replace(/\x1b\[[0-9;]*m/g, '');
 }
 /** True when argv asks for help or version together with --json. */
-export function isJsonMetaRequest(argv) {
+function isJsonMetaRequest(argv) {
     if (!argv.includes('--json'))
         return false;
     return argv.includes('--help') || argv.includes('--version');
@@ -21,27 +23,21 @@ class CaptureHelp extends Help {
         }
     }
 }
-function helpSubject(argv) {
-    for (const arg of argv) {
-        if (arg === '--' || arg === '--help' || arg === 'help')
-            continue;
-        if (arg.startsWith('-'))
-            return;
-        return arg;
-    }
-    return undefined;
-}
 function envelopeCommandId(config, argv) {
-    const subject = helpSubject(argv);
-    if (!subject)
+    const tokens = positionalArgvTokens(argv, VALUE_TAKING_FLAG_TOKENS);
+    if (tokens.length === 0)
         return config.bin;
-    const command = config.findCommand(subject);
-    if (command?.id)
-        return toConfiguredId(command.id, config);
-    const topic = config.findTopic(subject);
+    // Longest matching command id wins (`config:get` over topic `config`).
+    for (let n = tokens.length; n >= 1; n--) {
+        const id = tokens.slice(0, n).join(':');
+        const command = config.findCommand(id);
+        if (command?.id)
+            return toConfiguredId(command.id, config);
+    }
+    const topic = config.findTopic(tokens[0]);
     if (topic)
         return topic.name;
-    return subject;
+    return tokens[0];
 }
 /**
  * When `--json` is combined with `--help` or `--version`, oclif would print human text to stdout.
@@ -54,11 +50,11 @@ export async function tryJsonMetaOutput(argv, root) {
         const config = await Config.load({ root });
         if (argv.includes('--version')) {
             return {
-                exitCode: 0,
+                exitCode: EXIT_OK,
                 envelope: buildEnvelope({
                     command: config.bin,
                     ok: true,
-                    exitCode: 0,
+                    exitCode: EXIT_OK,
                     stderr: '',
                     data: {
                         version: config.version,
@@ -71,11 +67,11 @@ export async function tryJsonMetaOutput(argv, root) {
         await help.showHelp([...argv]);
         const helpText = stripAnsi(help.lines.join('\n').trimEnd());
         return {
-            exitCode: 0,
+            exitCode: EXIT_OK,
             envelope: buildEnvelope({
                 command: envelopeCommandId(config, argv),
                 ok: true,
-                exitCode: 0,
+                exitCode: EXIT_OK,
                 stderr: '',
                 data: { help: helpText },
             }),
@@ -84,11 +80,11 @@ export async function tryJsonMetaOutput(argv, root) {
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return {
-            exitCode: 1,
+            exitCode: EXIT_RUNTIME_FAILURE,
             envelope: buildEnvelope({
                 command: 'bonsai',
                 ok: false,
-                exitCode: 1,
+                exitCode: EXIT_RUNTIME_FAILURE,
                 stderr: message,
                 data: null,
                 code: 'META_RENDER_FAILED',

package/dist/lib/limit-flag.d.ts

@@ -1 +1,11 @@
-export declare function limitFlag(max: number, defaultValue: number, description: string): import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+/**
+ * Build an oclif integer `--limit` flag capped at `maxLimit`.
+ *
+ * @param maxLimit - Inclusive upper bound for accepted values.
+ * @param defaultValue - Default when the flag is omitted.
+ * @param description - Help text for the flag.
+ * @returns An oclif custom flag definition.
+ * @throws {Errors.CLIError} With code `INVALID_LIMIT` and exit {@link EXIT_USAGE} on bad input
+ *   (thrown by oclif during parse, not by this factory itself).
+ */
+export declare function limitFlag(maxLimit: number, defaultValue: number, description: string): import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;

package/dist/lib/limit-flag.js

@@ -1,18 +1,31 @@
 import { Errors, Flags } from '@oclif/core';
-export function limitFlag(max, defaultValue, description) {
+import { EXIT_USAGE } from './cli-error-policy.js';
+/**
+ * Build an oclif integer `--limit` flag capped at `maxLimit`.
+ *
+ * @param maxLimit - Inclusive upper bound for accepted values.
+ * @param defaultValue - Default when the flag is omitted.
+ * @param description - Help text for the flag.
+ * @returns An oclif custom flag definition.
+ * @throws {Errors.CLIError} With code `INVALID_LIMIT` and exit {@link EXIT_USAGE} on bad input
+ *   (thrown by oclif during parse, not by this factory itself).
+ */
+export function limitFlag(maxLimit, defaultValue, description) {
     return Flags.custom({
         parse: async (input) => {
             if (!/^\d+$/.test(input)) {
-                throw new Errors.CLIError(`Limit must be an integer between 1 and ${max}.`, {
-                    exit: 2,
+                throw new Errors.CLIError(`Limit must be an integer between 1 and ${maxLimit}.`, {
+                    exit: EXIT_USAGE,
                     code: 'INVALID_LIMIT',
+                    suggestions: [`Use an integer from 1 to ${maxLimit}.`],
                 });
             }
             const value = Number(input);
-            if (value < 1 || value > max) {
-                throw new Errors.CLIError(`Limit must be between 1 and ${max}.`, {
-                    exit: 2,
+            if (value < 1 || value > maxLimit) {
+                throw new Errors.CLIError(`Limit must be between 1 and ${maxLimit}.`, {
+                    exit: EXIT_USAGE,
                     code: 'INVALID_LIMIT',
+                    suggestions: [`Use a value from 1 to ${maxLimit}.`],
                 });
             }
             return value;

package/dist/lib/parse-error-ux.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Improve oclif parse-time errors in place: unwrap wrapper text, then suggest flag/option typos.
+ * Accepts `unknown` because `catch` can receive non-Error throws (bare strings, etc.).
+ */
+export declare function enrichParseError(err: unknown): void;

package/dist/lib/parse-error-ux.js

@@ -0,0 +1,73 @@
+import { normalizeCliErrorMessage } from './envelope.js';
+import { closestMatch, closestOptionValues, maxFuzzyDistance } from './text.js';
+/** FlagInvalidOptionError body after {@link normalizeCliErrorMessage}. */
+const EXPECTED_OPTION = /^Expected --([^=]+)=(\S+) to be one of: (.+)$/;
+function asEnrichable(err) {
+    if (!err || typeof err !== 'object')
+        return null;
+    if (typeof err.message !== 'string')
+        return null;
+    return err;
+}
+function suggestableFlagNames(err) {
+    const defined = err.parse?.input?.flags;
+    if (!defined)
+        return [];
+    const names = [];
+    for (const [name, flag] of Object.entries(defined)) {
+        names.push(`--${name}`);
+        for (const alias of flag.aliases ?? [])
+            names.push(`--${alias}`);
+        if (flag.char)
+            names.push(`-${flag.char}`);
+    }
+    // enableJsonFlag is framework-level — it may be absent from parse.input.flags.
+    if (!names.includes('--json'))
+        names.push('--json');
+    return names;
+}
+function collectTips(err) {
+    const lines = [];
+    const suggestions = [];
+    if (err.flags?.length) {
+        const candidates = suggestableFlagNames(err);
+        for (const bad of err.flags) {
+            const match = closestMatch(bad, candidates, maxFuzzyDistance(bad.replace(/^-*/, '')));
+            if (!match || match === bad)
+                continue;
+            lines.push(`Did you mean ${match}?`);
+            suggestions.push(match);
+        }
+    }
+    const option = err.message.match(EXPECTED_OPTION);
+    if (option) {
+        const [, flagName, input, optionsCsv] = option;
+        if (flagName && input && optionsCsv) {
+            const options = optionsCsv
+                .split(', ')
+                .map((part) => part.trim())
+                .filter(Boolean);
+            const values = closestOptionValues(input, options);
+            if (values.length > 0) {
+                lines.push(`Did you mean ${values.join(' or ')}?`);
+                suggestions.push(...values.map((value) => `--${flagName} ${value}`));
+            }
+        }
+    }
+    return { lines, suggestions };
+}
+/**
+ * Improve oclif parse-time errors in place: unwrap wrapper text, then suggest flag/option typos.
+ * Accepts `unknown` because `catch` can receive non-Error throws (bare strings, etc.).
+ */
+export function enrichParseError(err) {
+    const enrichable = asEnrichable(err);
+    if (!enrichable)
+        return;
+    enrichable.message = normalizeCliErrorMessage(enrichable.message);
+    const { lines, suggestions } = collectTips(enrichable);
+    if (lines.length === 0)
+        return;
+    enrichable.message = [enrichable.message, ...lines].join('\n');
+    enrichable.suggestions = [...(enrichable.suggestions ?? []), ...suggestions];
+}

package/dist/lib/prune-flags.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure prune-flag policy. Returns a usage/safety error descriptor, or null when flags are valid.
+ * Kept outside the command class so the branching stays testable without oclif and so
+ * `validatePruneFlags` stays a thin apply-error loop.
+ */
+export interface PruneFlagError {
+    message: string;
+    code: 'INVALID_FLAG_VALUE' | 'MISSING_FILTER' | 'READ_ONLY_MODE' | 'CONFLICTING_FLAGS' | 'SAFETY_CHECK_REQUIRED' | 'INVALID_DURATION';
+    suggestions?: string[];
+}
+/** Flag bag passed into {@link pruneFlagError}. */
+export interface PruneFlagInput {
+    olderThan?: string;
+    inactive?: string;
+    artifactType?: string;
+    url?: string;
+    topic?: string;
+    tags?: string[];
+    dryRun: boolean;
+    yes: boolean;
+    readOnly: boolean;
+    bin: string;
+}
+/**
+ * Return the first prune usage/safety error, or `null` when flags are valid.
+ *
+ * @param input - Parsed prune flags and binary name.
+ * @returns Error descriptor for `this.error`, or `null`.
+ */
+export declare function pruneFlagError(input: PruneFlagInput): PruneFlagError | null;

package/dist/lib/prune-flags.js

@@ -0,0 +1,86 @@
+import { emptyUrlFilterError } from './research/url.js';
+import { durationFlagError } from './research/freshness.js';
+import { emptyTopicFilterError, emptyTagsFilterError } from './research/metadata-filters.js';
+function missingFilterError(input) {
+    // Treat an explicitly passed empty string as "filter was attempted" so `--older-than ''`
+    // is not misreported as MISSING_FILTER (durationError rejects it as INVALID_DURATION).
+    // `tags` is the one array-valued flag here: oclif never parses a bare `--tags` into `[]` (a
+    // multiple string flag requires a value per occurrence), so a non-empty array is the correct
+    // "was this filter attempted" test, mirroring the `!== undefined` check used for every scalar flag.
+    if (input.olderThan !== undefined ||
+        input.inactive !== undefined ||
+        input.artifactType !== undefined ||
+        input.url !== undefined ||
+        input.topic !== undefined ||
+        (input.tags?.length ?? 0) > 0) {
+        return null;
+    }
+    return {
+        message: 'Must specify at least one pruning filter: --older-than, --inactive, --artifact-type, --url, --topic, or --tags.',
+        code: 'MISSING_FILTER',
+        suggestions: [`Preview age-based pruning: ${input.bin} prune --older-than 30d --dry-run`],
+    };
+}
+/**
+ * Mutation-gate checks. READ_ONLY before --dry-run/--yes conflict so
+ * `--dry-run --yes --read-only` reports the more specific READ_ONLY_MODE code.
+ */
+function mutationSafetyError(input) {
+    if (input.readOnly && input.yes) {
+        return {
+            message: '--yes cannot be used while read-only mode is active (--read-only/--plan or BONSAI_READ_ONLY/BONSAI_PLAN_MODE): mutations are disabled.',
+            code: 'READ_ONLY_MODE',
+            suggestions: [`Preview instead: ${input.bin} prune --dry-run`],
+        };
+    }
+    if (input.dryRun && input.yes) {
+        return {
+            message: '--dry-run and --yes are mutually exclusive: --dry-run previews without deleting, --yes confirms deletion. Choose one.',
+            code: 'CONFLICTING_FLAGS',
+            suggestions: [
+                `Preview without deleting: ${input.bin} prune --dry-run`,
+                `Or confirm deletion: ${input.bin} prune --yes`,
+            ],
+        };
+    }
+    // Read-only mode implicitly previews, so the usual "pick one" safety check is redundant then.
+    if (!input.readOnly && !input.dryRun && !input.yes) {
+        const olderThanPart = input.olderThan ? ` --older-than ${input.olderThan}` : '';
+        const urlPart = input.url ? ` --url "${input.url}"` : '';
+        const topicPart = input.topic ? ` --topic "${input.topic}"` : '';
+        const tagsPart = (input.tags ?? []).map((tag) => ` --tags "${tag}"`).join('');
+        return {
+            message: 'Safety check: use --yes to confirm pruning, or --dry-run to preview files that would be deleted.',
+            code: 'SAFETY_CHECK_REQUIRED',
+            suggestions: [
+                `Preview first: ${input.bin} prune --dry-run${olderThanPart}${urlPart}${topicPart}${tagsPart}`,
+            ],
+        };
+    }
+    return null;
+}
+function durationError(input) {
+    for (const msg of [
+        durationFlagError('--older-than', input.olderThan),
+        durationFlagError('--inactive', input.inactive),
+    ]) {
+        if (msg)
+            return { message: msg, code: 'INVALID_DURATION' };
+    }
+    return null;
+}
+/**
+ * Return the first prune usage/safety error, or `null` when flags are valid.
+ *
+ * @param input - Parsed prune flags and binary name.
+ * @returns Error descriptor for `this.error`, or `null`.
+ */
+export function pruneFlagError(input) {
+    const flagValueErr = emptyUrlFilterError(input.url) ??
+        emptyTopicFilterError(input.topic) ??
+        emptyTagsFilterError(input.tags);
+    if (flagValueErr)
+        return { message: flagValueErr, code: 'INVALID_FLAG_VALUE' };
+    // Duration before missing-filter so `--older-than ''` reports INVALID_DURATION, not MISSING_FILTER.
+    return durationError(input) ?? missingFilterError(input) ?? mutationSafetyError(input);
+}

package/dist/lib/research/artifact-index.d.ts

@@ -3,16 +3,25 @@ export interface IndexedArtifact {
     artifact: ResearchArtifact;
     filePath: string;
 }
+export interface LoadIndexedArtifactsOptions {
+    /**
+     * When false, skip writing `.search-index.json` (read-only/plan mode). Results are still
+     * computed from disk; only the derived sidecar is withheld. Defaults to true.
+     */
+    persist?: boolean;
+}
 /**
  * Returns the indexed view of every active artifact in one research dir, using the sidecar index
  * to skip unchanged files. Re-reads only files whose signature changed, then persists the refreshed
  * index (best-effort; a write failure never breaks callers). Corrupt/unreadable files are skipped —
  * the real read paths in storage.ts handle archiving them.
+ *
+ * Pass `{ persist: false }` under read-only/plan mode so the derived sidecar is never written.
  */
-export declare function loadIndexedArtifactsForDir(researchDir: string): IndexedArtifact[];
+export declare function loadIndexedArtifactsForDir(researchDir: string, options?: LoadIndexedArtifactsOptions): IndexedArtifact[];
 /**
  * Multi-root variant: scans the `research/` dir of each data dir in order and deduplicates by cache
  * key so a project entry shadows the same key in the global cache. Mirrors the dedup semantics of
  * {@link scanCacheDirs} but reads through the per-root sidecar index.
  */
-export declare function loadIndexedArtifacts(dataDirs: string[]): IndexedArtifact[];
+export declare function loadIndexedArtifacts(dataDirs: string[], options?: LoadIndexedArtifactsOptions): IndexedArtifact[];