@visulima/cerebro 3.0.0-alpha.11 → 3.0.0-alpha.13

package/dist/util/general/compile-cache.d.ts

@@ -1,41 +1,41 @@
 /**
- * V8 compile cache helper for faster CLI startup.
- *
- * Enables the V8 compile cache so that subsequent runs of the CLI skip
- * re-parsing and re-compiling JavaScript/TypeScript source files. This
- * can reduce startup time by 30-70% for large CLI tools.
- *
- * ## When to use
- *
- * Call `enableCompileCache()` early in your CLI entry point, after heap
- * tuning but before importing heavy modules:
- *
- * ```typescript
- * // bin.ts
- * import { applyHeapTuning } from "@visulima/cerebro/heap-tuning";
- * import { enableCompileCache } from "@visulima/cerebro/compile-cache";
- *
- * applyHeapTuning();
- * enableCompileCache();
- *
- * import { createCerebro } from "@visulima/cerebro";
- * // ... rest of your CLI setup
- * ```
- *
- * ## How it works
- *
- * 1. Tries `module.enableCompileCache()` (Node.js 22.8+ native API) which
- *    stores compiled bytecode alongside source files for instant reuse.
- * 2. If that's unavailable, falls back to the `v8-compile-cache` npm package
- *    which achieves a similar effect on older Node.js versions.
- * 3. If neither is available, silently does nothing — startup is just slower.
- * @module
- */
+* V8 compile cache helper for faster CLI startup.
+*
+* Enables the V8 compile cache so that subsequent runs of the CLI skip
+* re-parsing and re-compiling JavaScript/TypeScript source files. This
+* can reduce startup time by 30-70% for large CLI tools.
+*
+* ## When to use
+*
+* Call `enableCompileCache()` early in your CLI entry point, after heap
+* tuning but before importing heavy modules:
+*
+* ```typescript
+* // bin.ts
+* import { applyHeapTuning } from "@visulima/cerebro/heap-tuning";
+* import { enableCompileCache } from "@visulima/cerebro/compile-cache";
+*
+* applyHeapTuning();
+* enableCompileCache();
+*
+* import { createCerebro } from "@visulima/cerebro";
+* // ... rest of your CLI setup
+* ```
+*
+* ## How it works
+*
+* 1. Tries `module.enableCompileCache()` (Node.js 22.8+ native API) which
+*    stores compiled bytecode alongside source files for instant reuse.
+* 2. If that's unavailable, falls back to the `v8-compile-cache` npm package
+*    which achieves a similar effect on older Node.js versions.
+* 3. If neither is available, silently does nothing — startup is just slower.
+* @module
+*/
 /**
- * Enable V8 compile cache for faster subsequent CLI startups.
- *
- * Safe to call unconditionally — silently no-ops if the runtime doesn't
- * support compile caching or the fallback package isn't installed.
- */
+* Enable V8 compile cache for faster subsequent CLI startups.
+*
+* Safe to call unconditionally — silently no-ops if the runtime doesn't
+* support compile caching or the fallback package isn't installed.
+*/
 declare const enableCompileCache: () => void;
-export default enableCompileCache;
+export { enableCompileCache as default };

package/dist/util/general/heap-tuning.d.ts

@@ -1,81 +1,18 @@
-/**
- * Dynamic V8 heap memory tuning based on system memory.
- *
- * This helper computes optimal `--max-old-space-size` and `--max-semi-space-size`
- * flags for Node.js/Bun, then re-spawns the process with those flags applied.
- * If the flags are already set (via `NODE_OPTIONS` or direct CLI arguments),
- * the user's values are respected and no re-spawn occurs.
- *
- * ## When to use
- *
- * Import this helper **before** any heavy work — ideally as the very first
- * import in your CLI entry point. Because V8 memory flags can only be set at
- * process startup, this helper works by re-spawning the current process with
- * the computed flags when they are missing. After re-spawn, the module detects
- * that flags are already present and becomes a no-op.
- *
- * ## How to use
- *
- * Call `applyHeapTuning()` as early as possible in your CLI entry point,
- * **before** creating the cerebro instance or importing heavy modules:
- *
- * ```typescript
- * // bin.ts
- * import { applyHeapTuning } from "@visulima/cerebro/heap-tuning";
- *
- * // Apply with defaults (75% of system RAM)
- * applyHeapTuning();
- *
- * // Or customize the allocation percentage
- * applyHeapTuning({ maxOldSpacePercent: 0.5 });
- *
- * import { createCerebro } from "@visulima/cerebro";
- * // ... rest of your CLI setup
- * ```
- *
- * If heap tuning is needed, `applyHeapTuning()` re-spawns the process and
- * **never returns** — subsequent code in the parent is not reached. After
- * re-spawn, the flags are already set so the call becomes a no-op.
- *
- * ## How it works
- *
- * 1. Checks `process.execArgv` for existing `--max-old-space-size` and
- *    `--max-semi-space-size` flags.
- * 2. If both are present, returns immediately (no-op).
- * 3. Otherwise, computes defaults:
- *    - `--max-old-space-size`: percentage of total system memory (default 75%)
- *    - `--max-semi-space-size`: tiered scaling based on old-space size
- * 4. Re-spawns the current process via `execFileSync` with the computed flags
- *    prepended to `execArgv`, then exits the parent with the child's exit code.
- *
- * ## Semi-space sizing tiers
- *
- * | Old-space (MiB) | Semi-space (MiB) |
- * |-----------------|-----------------|
- * | <= 512          | 4               |
- * | <= 1024         | 8               |
- * | <= 2048         | 16              |
- * | <= 4096         | 32              |
- * | <= 8192         | 64              |
- * | > 8192          | log2-scaled     |
- * @module
- */
 interface HeapTuningOptions {
-    /**
-     * Fraction of total system memory to allocate as `--max-old-space-size`.
-     * Must be between 0 and 1. Default: `0.75` (75%).
-     */
-    maxOldSpacePercent?: number;
+  /**
+  * Fraction of total system memory to allocate as `--max-old-space-size`.
+  * Must be between 0 and 1. Default: `0.75` (75%).
+  */
+  maxOldSpacePercent?: number;
 }
 /**
- * Apply heap memory tuning to the current process.
- *
- * When tuning is needed, this function re-spawns the process with computed
- * V8 memory flags and **never returns** — the parent exits with the child's
- * exit code. When no tuning is needed (flags already set), it returns
- * immediately.
- * @param options Optional configuration for heap tuning.
- */
+* Apply heap memory tuning to the current process.
+*
+* When tuning is needed, this function re-spawns the process with computed
+* V8 memory flags and **never returns** — the parent exits with the child's
+* exit code. When no tuning is needed (flags already set), it returns
+* immediately.
+* @param options Optional configuration for heap tuning.
+*/
 declare const applyHeapTuning: (options?: HeapTuningOptions) => void;
-export type { HeapTuningOptions };
-export { applyHeapTuning };
+export { type HeapTuningOptions, applyHeapTuning };

package/package.json

@@ -1,34 +1,34 @@
 {
   "name": "@visulima/cerebro",
-  "version": "3.0.0-alpha.11",
+  "version": "3.0.0-alpha.13",
   "description": "A delightful toolkit for building cross-runtime CLIs for Node.js, Deno, and Bun.",
   "keywords": [
-    "visulima",
-    "command",
-    "line",
-    "class",
-    "terminal",
     "ansi",
-    "cli",
-    "opts",
-    "nopt",
-    "options",
     "args",
+    "argument",
     "argv",
-    "interactive",
-    "commander",
     "clap",
+    "class",
+    "cli",
     "cli-app",
-    "minimist",
+    "command",
     "command line apps",
     "command-line-usage",
-    "option",
-    "parser",
-    "argument",
+    "commander",
     "flag",
     "gluegun",
+    "interactive",
+    "line",
     "meow",
+    "minimist",
+    "nopt",
     "oclif",
+    "option",
+    "options",
+    "opts",
+    "parser",
+    "terminal",
+    "visulima",
     "yargs"
   ],
   "homepage": "https://visulima.com/packages/cerebro",
@@ -116,10 +116,10 @@
     "fastest-levenshtein": "^1.0.16"
   },
   "peerDependencies": {
-    "@bomb.sh/tab": "0.0.14",
+    "@bomb.sh/tab": "0.0.15",
     "@visulima/boxen": "3.0.0-alpha.10",
     "@visulima/find-cache-dir": "3.0.0-alpha.9",
-    "@visulima/pail": "4.0.0-alpha.11",
+    "@visulima/pail": "4.0.0-alpha.12",
     "github-slugger": "2.0.0"
   },
   "peerDependenciesMeta": {

package/dist/cli.d.ts

@@ -1,225 +0,0 @@
-import PluginManager from "./plugin-manager.d.ts";
-import type { Cli as ICli, CliRunOptions, CommandSection as ICommandSection, RunCommandOptions } from "./types/cli.d.ts";
-import type { Command as ICommand, OptionDefinition } from "./types/command.d.ts";
-import type { Plugin } from "./types/plugin.d.ts";
-export type CliOptions<T extends Console = Console> = {
-    argv?: ReadonlyArray<string>;
-    cwd?: string;
-    logger?: T;
-    packageName?: string;
-    packageVersion?: string;
-};
-export declare class Cli<T extends Console = Console> implements ICli<T> {
-    #private;
-    /**
-     * Create a new CLI instance.
-     * @param cliName
-     * @param options The options for the CLI.
-     * @param options.argv The command line arguments.
-     * @param options.cwd The current working directory.
-     * @param options.logger The logger to use.
-     * @param options.packageName
-     * @param options.packageVersion
-     */
-    constructor(cliName: string, options?: CliOptions<T>);
-    /**
-     * Sets the command section configuration for help display.
-     *
-     * This affects how the CLI name and version are displayed in help output.
-     * @param commandSection The command section configuration
-     * @returns The CLI instance for method chaining
-     * @example
-     * ```typescript
-     * cli.setCommandSection({
-     *   header: 'My App v2.0.0',
-     *   footer: 'For more info, visit https://example.com'
-     * });
-     * ```
-     */
-    setCommandSection(commandSection: ICommandSection): this;
-    /**
-     * Gets the current command section configuration.
-     * @returns The command section configuration
-     */
-    getCommandSection(): ICommandSection;
-    /**
-     * Sets the default command to run when no command is specified.
-     *
-     * By default, this is set to 'help'. The command must already be registered
-     * with the CLI instance.
-     * @param commandName The command name to use as the default
-     * @returns The CLI instance for method chaining
-     * @example
-     * ```typescript
-     * cli.setDefaultCommand('start');
-     * ```
-     */
-    setDefaultCommand(commandName: string): this;
-    /**
-     * Gets the current default command.
-     * @returns The name of the default command
-     */
-    get defaultCommand(): string;
-    /**
-     * Adds a command to the CLI.
-     *
-     * Commands define the available operations that users can execute.
-     * Each command can have options, arguments, aliases, and custom execution logic.
-     * @template OD - The option definition type for the command
-     * @param command The command configuration object
-     * @returns The CLI instance for method chaining
-     * @throws {CerebroError} If the command name already exists or validation fails
-     * @example
-     * ```typescript
-     * cli.addCommand({
-     *   name: 'build',
-     *   description: 'Build the project',
-     *   options: [
-     *     {
-     *       name: 'output',
-     *       alias: 'o',
-     *       type: String,
-     *       description: 'Output directory'
-     *     }
-     *   ],
-     *   execute: ({ options }) => {
-     *     console.log(`Building to ${options.output || 'dist'}`);
-     *   }
-     * });
-     * ```
-     */
-    addCommand<OD extends OptionDefinition<unknown> = OptionDefinition<unknown>>(command: ICommand<OD, T>): this;
-    /**
-     * Adds a global option available to all commands.
-     *
-     * Global options are parsed alongside command-specific options and displayed
-     * in the help output under the "Global Options" section.
-     * @param option The option definition
-     * @returns The CLI instance for method chaining
-     * @example
-     * ```typescript
-     * cli.addGlobalOption({
-     *   name: 'cwd',
-     *   type: String,
-     *   description: 'Override working directory',
-     * });
-     * ```
-     */
-    addGlobalOption<V = unknown>(option: OptionDefinition<V>): this;
-    /**
-     * Gets all global options (built-in + custom).
-     * @returns Array of all global option definitions
-     */
-    getGlobalOptions(): OptionDefinition<unknown>[];
-    /**
-     * Adds a plugin to extend the CLI functionality.
-     *
-     * Plugins can hook into various lifecycle events and modify the toolbox
-     * to provide additional functionality to commands.
-     * @param plugin The plugin to register
-     * @returns The CLI instance for method chaining
-     * @example
-     * ```typescript
-     * cli.addPlugin({
-     *   name: 'logger',
-     *   execute: (toolbox) => {
-     *     toolbox.logger = createCustomLogger();
-     *   }
-     * });
-     * ```
-     */
-    addPlugin(plugin: Plugin<T>): this;
-    /**
-     * Gets the plugin manager instance for advanced plugin management.
-     * @returns The plugin manager instance
-     */
-    getPluginManager(): PluginManager<T>;
-    /**
-     * Gets the CLI application name.
-     */
-    getCliName(): string;
-    /**
-     * Gets the package version if configured.
-     * @returns The package version or undefined
-     */
-    getPackageVersion(): string | undefined;
-    /**
-     * Gets the package name if configured.
-     * @returns The package name or undefined
-     */
-    getPackageName(): string | undefined;
-    /**
-     * Gets all registered commands.
-     * @returns A map of command names to command definitions
-     */
-    getCommands(): Map<string, ICommand<OptionDefinition<unknown>, T>>;
-    /**
-     * Gets the current working directory.
-     * @returns The current working directory path
-     */
-    getCwd(): string;
-    /**
-     * Disposes the CLI instance and cleans up resources.
-     *
-     * This method removes event listeners and performs cleanup to prevent memory leaks.
-     * Call this method when the CLI instance is no longer needed, especially in long-running
-     * processes or when creating multiple CLI instances.
-     * @example
-     * ```typescript
-     * const cli = new Cerebro('my-app');
-     * // ... use the cli
-     * cli.dispose(); // Clean up when done
-     * ```
-     */
-    dispose(): void;
-    /**
-     * Runs the CLI application.
-     *
-     * This method parses command line arguments, executes the appropriate command,
-     * and handles the complete CLI lifecycle including plugin initialization,
-     * error handling, process termination, and automatic cleanup.
-     * @param extraOptions Additional options to pass to commands
-     * @param extraOptions.shouldExitProcess Whether to exit the process after execution (default: true)
-     * @param extraOptions.autoDispose Whether to automatically cleanup/dispose resources after execution (default: true)
-     * @returns A promise that resolves when execution completes
-     * @throws {CommandNotFoundError} If the specified command doesn't exist
-     * @throws {Error} If command arguments are invalid or conflicting options are provided
-     * @example
-     * ```typescript
-     * // Run with default behavior (exits process and auto-disposes)
-     * await cli.run();
-     *
-     * // Run without exiting (for testing)
-     * await cli.run({ shouldExitProcess: false });
-     *
-     * // Run without auto-disposing (for reuse)
-     * await cli.run({ autoDispose: false });
-     * ```
-     */
-    run(extraOptions?: CliRunOptions): Promise<void>;
-    /**
-     * Runs a command programmatically from within another command.
-     *
-     * This method allows commands to call other commands during execution,
-     * enabling composition of commands and reusable command logic.
-     * @param commandName The name of the command to execute
-     * @param options Optional options including argv and other command options
-     * @returns A promise that resolves with the command's result
-     * @throws {CommandNotFoundError} If the specified command doesn't exist
-     * @throws {CerebroError} If command validation fails
-     * @example
-     * ```typescript
-     * cli.addCommand({
-     *   name: 'deploy',
-     *   execute: async ({ runtime, logger }) => {
-     *     logger.info('Building...');
-     *     await runtime.runCommand('build', { argv: ['--production'] });
-     *
-     *     logger.info('Testing...');
-     *     await runtime.runCommand('test', { argv: ['--coverage'] });
-     *   }
-     * });
-     * ```
-     */
-    runCommand(commandName: string, options?: RunCommandOptions): Promise<unknown>;
-}

package/dist/constants.d.ts

@@ -1,29 +0,0 @@
-/**
- * Output with this option will be formatted.
- */
-export declare const OUTPUT_NORMAL = 1;
-/**
- * Output with this option will be passed as-is.
- */
-export declare const OUTPUT_RAW = 2;
-/**
- * Output with this option will have any formatting stripped away.
- */
-export declare const OUTPUT_PLAIN = 4;
-/**
- * Output with this verbosity won't write anything at all.
- */
-export declare const VERBOSITY_QUIET = 16;
-/**
- * Output with this verbosity will write default content.
- */
-export declare const VERBOSITY_NORMAL = 32;
-/**
- * Output with this verbosity will be more detailed.
- */
-export declare const VERBOSITY_VERBOSE = 64;
-/**
- * Output with this verbosity will reveal internals.
- */
-export declare const VERBOSITY_DEBUG = 128;
-export declare const POSITIONALS_KEY = "positionals";

package/dist/default-env.d.ts

@@ -1,7 +0,0 @@
-import type { EnvDefinition } from "./types/command.d.ts";
-/**
- * Default environment variables used by Cerebro CLI framework.
- * These are displayed in the help output.
- */
-declare const defaultEnv: (EnvDefinition | EnvDefinition<number> | EnvDefinition<boolean>)[];
-export default defaultEnv;

package/dist/default-options.d.ts

@@ -1,3 +0,0 @@
-import type { OptionDefinition } from "./types/command.d.ts";
-declare const defaultOptions: OptionDefinition<boolean>[];
-export default defaultOptions;

package/dist/empty-toolbox.d.ts

@@ -1,16 +0,0 @@
-import type { Toolbox as IToolbox } from "./types/toolbox.d.ts";
-declare class EmptyToolbox implements Partial<IToolbox> {
-    [x: string]: unknown;
-    result?: unknown;
-    argv?: IToolbox["argv"];
-    options?: IToolbox["options"];
-    argument?: IToolbox["argument"];
-    command: IToolbox["command"];
-    commandName: IToolbox["commandName"];
-    env?: IToolbox["env"];
-    logger?: IToolbox["logger"];
-    runtime?: IToolbox["runtime"];
-    rawUnknown?: IToolbox["rawUnknown"];
-    constructor(commandName: IToolbox["commandName"], command: IToolbox["command"]);
-}
-export default EmptyToolbox;

package/dist/errors/cerebro-error.d.ts

@@ -1,10 +0,0 @@
-import { VisulimaError } from "@visulima/error";
-/**
- * Base error class for Cerebro CLI operations.
- */
-declare class CerebroError extends VisulimaError {
-    readonly code: string;
-    readonly context?: Record<string, unknown>;
-    constructor(message: string, code: string, context?: Record<string, unknown>);
-}
-export default CerebroError;

package/dist/errors/command-not-found-error.d.ts

@@ -1,9 +0,0 @@
-import CerebroError from "./cerebro-error.d.ts";
-/**
- * Error thrown when a command is not found.
- */
-declare class CommandNotFoundError extends CerebroError {
-    readonly commandName: string;
-    constructor(commandName: string, suggestions?: string[]);
-}
-export default CommandNotFoundError;

package/dist/errors/command-validation-error.d.ts

@@ -1,10 +0,0 @@
-import CerebroError from "./cerebro-error.d.ts";
-/**
- * Error thrown when command validation fails.
- */
-declare class CommandValidationError extends CerebroError {
-    readonly commandName: string;
-    readonly missingOptions: string[];
-    constructor(commandName: string, missingOptions: string[]);
-}
-export default CommandValidationError;

package/dist/errors/completion-error.d.ts

@@ -1,9 +0,0 @@
-import CerebroError from "./cerebro-error.d.ts";
-/**
- * Error thrown when completion command operations fail.
- */
-declare class CompletionError extends CerebroError {
-    readonly troubleshooting: string[];
-    constructor(message: string, code: string, troubleshooting?: string[]);
-}
-export default CompletionError;

package/dist/errors/conflicting-options-error.d.ts

@@ -1,10 +0,0 @@
-import CerebroError from "./cerebro-error.d.ts";
-/**
- * Error thrown when there are conflicting options.
- */
-declare class ConflictingOptionsError extends CerebroError {
-    readonly option1: string;
-    readonly option2: string;
-    constructor(option1: string, option2: string);
-}
-export default ConflictingOptionsError;

package/dist/errors/plugin-error.d.ts

@@ -1,9 +0,0 @@
-import CerebroError from "./cerebro-error.d.ts";
-/**
- * Error thrown when plugin operations fail.
- */
-declare class PluginError extends CerebroError {
-    readonly pluginName: string;
-    constructor(pluginName: string, message: string, originalError?: Error);
-}
-export default PluginError;

package/dist/errors/update-notifier-error.d.ts

@@ -1,7 +0,0 @@
-import CerebroError from "./cerebro-error.d.ts";
-/**
- * Error thrown when update notifier operations fail.
- */
-export default class UpdateNotifierError extends CerebroError {
-    constructor(message: string, code?: string, context?: Record<string, unknown>);
-}

package/dist/plugin-manager.d.ts

@@ -1,53 +0,0 @@
-import type { Plugin, PluginContext } from "./types/plugin.d.ts";
-import type { Toolbox } from "./types/toolbox.d.ts";
-type Logger = Console;
-/**
- * Manages plugin lifecycle and execution
- */
-declare class PluginManager<T extends Logger = Logger> {
-    private readonly logger;
-    private readonly plugins;
-    private initialized;
-    private cachedDependencyOrder;
-    constructor(logger: T);
-    /**
-     * Checks if any plugins are registered.
-     * @returns True if at least one plugin is registered
-     */
-    hasPlugins(): boolean;
-    /**
-     * Registers a plugin.
-     * @param plugin The plugin to register
-     * @throws {Error} If plugin name is already registered or dependencies are invalid
-     */
-    register(plugin: Plugin<T>): void;
-    /**
-     * Initializes all registered plugins.
-     * @param context The plugin context for initialization
-     */
-    init(context: PluginContext<T>): Promise<void>;
-    /**
-     * Executes a specific lifecycle hook for all plugins.
-     * @param hook The lifecycle hook name
-     * @param toolbox The command toolbox (for command-specific hooks)
-     * @param result The command result (for afterCommand hook)
-     */
-    executeLifecycle(hook: "beforeCommand" | "afterCommand" | "execute", toolbox: Toolbox<T>, result?: unknown): Promise<void>;
-    /**
-     * Executes error handlers for all plugins.
-     * @param error The error that occurred
-     * @param toolbox The command toolbox
-     */
-    executeErrorHandlers(error: Error, toolbox: Toolbox<T>): Promise<void>;
-    /**
-     * Gets all registered plugins in dependency order.
-     * @returns Array of plugins sorted by dependencies
-     */
-    getDependencyOrder(): Plugin<T>[];
-    /**
-     * Validates that all plugin dependencies exist.
-     * @throws {Error} If any dependencies are missing
-     */
-    private validateDependencies;
-}
-export default PluginManager;

package/dist/plugins/update-notifier/cache.d.ts

@@ -1,11 +0,0 @@
-/**
- * Retrieves the last update check timestamp for the specified package.
- * @param packageName
- * @returns - The timestamp of the last update check, or undefined if the check failed.
- */
-export declare const getLastUpdate: (packageName: string) => number | undefined;
-/**
- * Saves the last update time for a given package.
- * @param packageName
- */
-export declare const saveLastUpdate: (packageName: string) => void;

package/dist/plugins/update-notifier/get-distribution-version.d.ts

@@ -1,2 +0,0 @@
-declare const getDistributionVersion: (packageName: string, distributionTag: string, registryUrl: string) => Promise<string>;
-export default getDistributionVersion;