@taurgis/bonsai 3.2.0 → 3.2.2

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>;

package/dist/lib/envelope.js

@@ -1,3 +1,4 @@
+import { EXIT_RUNTIME_FAILURE } from './cli-error-policy.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 +22,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 +66,119 @@ 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 ?? '';
+            return failures.length > 1
+                ? `Cache miss for ${url} and ${failures.length - 1} other 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) => (first.message ?? '') +
+            (failures.length > 1 ? `\n…and ${failures.length - 1} other URL failure(s)` : ''),
+        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 +202,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,28 @@
+/**
+ * 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;
+    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;