@visulima/cerebro 3.0.2 → 3.0.4

package/dist/index.d.ts

@@ -1,520 +1,490 @@
-import { a as CerebroFs, b as CommandSection, O as OptionDefinition, C as Command, P as Plugin, c as PluginManager, d as CliRunOptions, R as RunCommandOptions, T as Toolbox, e as CommandExecute, f as Cli$1, L as LazyCommandModule } from "./packem_shared/command.d-DbhtfXF4.js";
-export type { A as ArgumentDefinition, g as CerebroProcess, E as EnvDefinition, h as OutputType, i as PluginContext, V as VERBOSITY_LEVEL } from "./packem_shared/command.d-DbhtfXF4.js";
-export { V as VisulimaError } from "./packem_shared/index.d-BL4NtVR3.js";
+import { a as CerebroFs, b as CommandSection, O as OptionDefinition, C as Command, P as Plugin, c as PluginManager, d as CliRunOptions, R as RunCommandOptions, T as Toolbox, e as CommandExecute, f as Cli$1, L as LazyCommandModule } from "./packem_shared/command.d-B_G9vIYJ.js";
+export type { A as ArgumentDefinition, g as CerebroProcess, E as EnvDefinition, h as OutputType, i as PluginContext, V as VERBOSITY_LEVEL } from "./packem_shared/command.d-B_G9vIYJ.js";
+export { V as VisulimaError } from "./packem_shared/index.d-CnnVYgSZ.js";
 import '@visulima/tabular';
 type CliOptions<T extends Console = Console> = {
   argv?: ReadonlyArray<string>;
   cwd?: string;
   /**
-  * Process environment variables exposed to commands via `toolbox.process.env`.
-  * Defaults to the runtime's process environment. Override to provide a
-  * captured snapshot in tests so commands don't read mutating host state.
-  */
+   * Process environment variables exposed to commands via `toolbox.process.env`.
+   * Defaults to the runtime's process environment. Override to provide a
+   * captured snapshot in tests so commands don't read mutating host state.
+   */
   env?: Record<string, string | undefined>;
   /**
-  * Function called when a command invokes `toolbox.process.exit(code)`.
-  * Defaults to the runtime-agnostic exit helper that terminates the process.
-  * Override with a `vi.fn()` in tests to capture exit codes without killing
-  * the test runner.
-  */
+   * Function called when a command invokes `toolbox.process.exit(code)`.
+   * Defaults to the runtime-agnostic exit helper that terminates the process.
+   * Override with a `vi.fn()` in tests to capture exit codes without killing
+   * the test runner.
+   */
   exit?: (code?: number) => void;
   /**
-  * Filesystem adapter exposed via `toolbox.fs`. Defaults to `node:fs/promises`.
-  * Override with an in-memory or sandboxed adapter for tests and embedded
-  * runtimes (MCP, JustBash).
-  */
+   * Filesystem adapter exposed via `toolbox.fs`. Defaults to `node:fs/promises`.
+   * Override with an in-memory or sandboxed adapter for tests and embedded
+   * runtimes (MCP, JustBash).
+   */
   fs?: CerebroFs;
   logger?: T;
   /**
-  * Maximum number of argv tokens accepted before {@link Cli} rejects the
-  * invocation. Defaults to a generous cap (`DEFAULT_MAX_ARGS`) that never
-  * trips real-world glob expansions; set to `Number.POSITIVE_INFINITY` to
-  * disable the guard entirely.
-  */
+   * Maximum number of argv tokens accepted before {@link Cli} rejects the
+   * invocation. Defaults to a generous cap (`DEFAULT_MAX_ARGS`) that never
+   * trips real-world glob expansions; set to `Number.POSITIVE_INFINITY` to
+   * disable the guard entirely.
+   */
   maxArguments?: number;
   packageName?: string;
   packageVersion?: string;
   /**
-  * Buffered stdin content exposed via `toolbox.process.stdin`. Empty string
-  * by default. Useful for tests and sandboxed runtimes where wiring real
-  * stdin is impractical.
-  */
+   * Buffered stdin content exposed via `toolbox.process.stdin`. Empty string
+   * by default. Useful for tests and sandboxed runtimes where wiring real
+   * stdin is impractical.
+   */
   stdin?: string;
   /**
-  * When enabled, unknown long options (`--typo`) that appear before any `--`
-  * passthrough separator cause the run to fail with an `UnknownOptionError`
-  * (with did-you-mean suggestions) instead of being silently routed to
-  * `toolbox.rawUnknown`. Tokens after `--` are always preserved as
-  * passthrough. Off by default to preserve existing behavior.
-  */
+   * When enabled, unknown long options (`--typo`) that appear before any `--`
+   * passthrough separator cause the run to fail with an `UnknownOptionError`
+   * (with did-you-mean suggestions) instead of being silently routed to
+   * `toolbox.rawUnknown`. Tokens after `--` are always preserved as
+   * passthrough. Off by default to preserve existing behavior.
+   */
   strictOptions?: boolean;
 };
 declare class Cli<T extends Console = Console> implements Cli$1<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
-  */
+   * 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'
-  * });
-  * ```
-  */
+   * 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: CommandSection): this;
   /**
-  * Gets the current command section configuration.
-  * @returns The command section configuration
-  */
+   * Gets the current command section configuration.
+   * @returns The command section configuration
+   */
   getCommandSection(): CommandSection;
   /**
-  * 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');
-  * ```
-  */
+   * 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
-  */
+   * 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'}`);
-  *   }
-  * });
-  * ```
-  */
+   * 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: Command<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',
-  * });
-  * ```
-  */
+   * 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
-  */
+   * 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();
-  *   }
-  * });
-  * ```
-  */
+   * 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
-  */
+   * Gets the plugin manager instance for advanced plugin management.
+   * @returns The plugin manager instance
+   */
   getPluginManager(): PluginManager<T>;
   /**
-  * Gets the CLI application name.
-  */
+   * Gets the CLI application name.
+   */
   getCliName(): string;
   /**
-  * Gets the package version if configured.
-  * @returns The package version or undefined
-  */
+   * 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
-  */
+   * 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
-  */
+   * Gets all registered commands.
+   * @returns A map of command names to command definitions
+   */
   getCommands(): Map<string, Command<OptionDefinition<unknown>, T>>;
   /**
-  * Gets the current working directory.
-  * @returns The current working directory path
-  */
+   * 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
-  * ```
-  */
+   * 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 });
-  * ```
-  */
+   * 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'] });
-  *   }
-  * });
-  * ```
-  */
+   * 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>;
   /**
-  * Creates a shallow copy of the CLI with optional `CliOptions` overrides.
-  *
-  * The clone shares the underlying command definitions (the same `Command`
-  * objects are reused), but has its own commands map, global-options list,
-  * default-command setting, command-section configuration, and a freshly
-  * initialized plugin manager. Mutating one CLI's commands after cloning
-  * does not affect the other.
-  *
-  * Primarily useful in tests to run the same CLI definition with different
-  * argv / stdout / exit / fs overrides without rebuilding the command tree.
-  * @param overrides Optional `CliOptions` to merge over the clone's existing options
-  * @returns A new `Cli` instance with the same commands and merged options
-  * @example
-  * ```typescript
-  * const cli = new Cerebro("acme");
-  * cli.addCommand({ name: "build", execute: ({ console }) => console.log("building") });
-  *
-  * // In tests: clone with mocked exit + captured stdout
-  * const exitSpy = vi.fn();
-  * const isolated = cli.clone({ argv: ["build"], exit: exitSpy });
-  * await isolated.run({ shouldExitProcess: false });
-  * ```
-  */
+   * Creates a shallow copy of the CLI with optional `CliOptions` overrides.
+   *
+   * The clone shares the underlying command definitions (the same `Command`
+   * objects are reused), but has its own commands map, global-options list,
+   * default-command setting, command-section configuration, and a freshly
+   * initialized plugin manager. Mutating one CLI's commands after cloning
+   * does not affect the other.
+   *
+   * Primarily useful in tests to run the same CLI definition with different
+   * argv / stdout / exit / fs overrides without rebuilding the command tree.
+   * @param overrides Optional `CliOptions` to merge over the clone's existing options
+   * @returns A new `Cli` instance with the same commands and merged options
+   * @example
+   * ```typescript
+   * const cli = new Cerebro("acme");
+   * cli.addCommand({ name: "build", execute: ({ console }) => console.log("building") });
+   *
+   * // In tests: clone with mocked exit + captured stdout
+   * const exitSpy = vi.fn();
+   * const isolated = cli.clone({ argv: ["build"], exit: exitSpy });
+   * await isolated.run({ shouldExitProcess: false });
+   * ```
+   */
   clone(overrides?: CliOptions<T>): Cli<T>;
   /**
-  * Returns the resolved `execute` function for a registered command.
-  *
-  * For lazy-loaded commands (defined via `loader`), the loader is awaited
-  * and its module's default export is returned. The result is cached on the
-  * command for subsequent calls. Supports space-separated nested command
-  * paths (e.g. `"git remote add"`).
-  *
-  * Primarily useful in tests to invoke a command's handler directly with a
-  * synthesized toolbox, without going through argv parsing or the full
-  * `run()` lifecycle.
-  * @param commandName The command name or space-separated nested path
-  * @returns A promise resolving to the command's handler function
-  * @throws {CommandNotFoundError} If no command matches the given name
-  * @throws {CerebroError} If the command has neither `execute` nor `loader`
-  * @example
-  * ```typescript
-  * const cli = new Cerebro("acme");
-  * cli.addCommand({
-  *   name: "deploy",
-  *   execute: ({ console, options }) => console.log("deploying to", options.env),
-  * });
-  *
-  * // In tests: call the action directly with a mocked toolbox
-  * const action = await cli.getAction("deploy");
-  * await action({ console: fakeConsole, options: { env: "staging" } } as never);
-  * ```
-  */
+   * Returns the resolved `execute` function for a registered command.
+   *
+   * For lazy-loaded commands (defined via `loader`), the loader is awaited
+   * and its module's default export is returned. The result is cached on the
+   * command for subsequent calls. Supports space-separated nested command
+   * paths (e.g. `"git remote add"`).
+   *
+   * Primarily useful in tests to invoke a command's handler directly with a
+   * synthesized toolbox, without going through argv parsing or the full
+   * `run()` lifecycle.
+   * @param commandName The command name or space-separated nested path
+   * @returns A promise resolving to the command's handler function
+   * @throws {CommandNotFoundError} If no command matches the given name
+   * @throws {CerebroError} If the command has neither `execute` nor `loader`
+   * @example
+   * ```typescript
+   * const cli = new Cerebro("acme");
+   * cli.addCommand({
+   *   name: "deploy",
+   *   execute: ({ console, options }) => console.log("deploying to", options.env),
+   * });
+   *
+   * // In tests: call the action directly with a mocked toolbox
+   * const action = await cli.getAction("deploy");
+   * await action({ console: fakeConsole, options: { env: "staging" } } as never);
+   * ```
+   */
   getAction(commandName: string): Promise<CommandExecute<Toolbox<T>>>;
 }
 /**
-* Output with this verbosity won't write anything at all.
-*/
+ * Output with this verbosity won't write anything at all.
+ */
 declare const VERBOSITY_QUIET = 16;
 /**
-* Output with this verbosity will write default content.
-*/
+ * Output with this verbosity will write default content.
+ */
 declare const VERBOSITY_NORMAL = 32;
 /**
-* Output with this verbosity will be more detailed.
-*/
+ * Output with this verbosity will be more detailed.
+ */
 declare const VERBOSITY_VERBOSE = 64;
 /**
-* Output with this verbosity will reveal internals.
-*/
+ * Output with this verbosity will reveal internals.
+ */
 declare const VERBOSITY_DEBUG = 128;
 /**
-* Helper types for creating type-safe commands with autocomplete support.
-* These types help you define your options and environment variables with full TypeScript autocomplete.
-* Use these types to create type-safe Toolbox interfaces for your commands.
-* @example
-* ```typescript
-* import { CreateOptions, CreateEnv, type Toolbox } from '@visulima/cerebro';
-*
-* // Define options with their original names (they'll be converted to camelCase)
-* type BuildOptions = CreateOptions<{
-*   "output-dir": string | undefined;
-*   "verbose": boolean | undefined;
-*   "port": number | undefined;
-* }>;
-* // Result: { outputDir: string | undefined, verbose: boolean | undefined, port: number | undefined }
-*
-* // Define environment variables (UPPER_SNAKE_CASE -> camelCase)
-* type BuildEnv = CreateEnv<{
-*   "API_KEY": string | undefined;
-*   "DEBUG": boolean | undefined;
-* }>;
-* // Result: { apiKey: string | undefined, debug: boolean | undefined }
-*
-* // Use in your command
-* cli.addCommand({
-*   name: "build",
-*   options: [
-*     { name: "output-dir", type: String },
-*     { name: "verbose", type: Boolean },
-*     { name: "port", type: Number }
-*   ],
-*   env: [
-*     { name: "API_KEY", type: String },
-*     { name: "DEBUG", type: Boolean }
-*   ],
-*   execute: ({ options, env }: Toolbox<Console, BuildOptions, BuildEnv>) => {
-*     // Full autocomplete on options.outputDir, options.verbose, env.apiKey, etc.
-*     console.log(options.outputDir, options.verbose, env.apiKey);
-*   }
-* });
-* ```
-*/
+ * Helper types for creating type-safe commands with autocomplete support.
+ * These types help you define your options and environment variables with full TypeScript autocomplete.
+ * Use these types to create type-safe Toolbox interfaces for your commands.
+ * @example
+ * ```typescript
+ * import { CreateOptions, CreateEnv, type Toolbox } from '@visulima/cerebro';
+ *
+ * // Define options with their original names (they'll be converted to camelCase)
+ * type BuildOptions = CreateOptions<{
+ *   "output-dir": string | undefined;
+ *   "verbose": boolean | undefined;
+ *   "port": number | undefined;
+ * }>;
+ * // Result: { outputDir: string | undefined, verbose: boolean | undefined, port: number | undefined }
+ *
+ * // Define environment variables (UPPER_SNAKE_CASE -> camelCase)
+ * type BuildEnv = CreateEnv<{
+ *   "API_KEY": string | undefined;
+ *   "DEBUG": boolean | undefined;
+ * }>;
+ * // Result: { apiKey: string | undefined, debug: boolean | undefined }
+ *
+ * // Use in your command
+ * cli.addCommand({
+ *   name: "build",
+ *   options: [
+ *     { name: "output-dir", type: String },
+ *     { name: "verbose", type: Boolean },
+ *     { name: "port", type: Number }
+ *   ],
+ *   env: [
+ *     { name: "API_KEY", type: String },
+ *     { name: "DEBUG", type: Boolean }
+ *   ],
+ *   execute: ({ options, env }: Toolbox<Console, BuildOptions, BuildEnv>) => {
+ *     // Full autocomplete on options.outputDir, options.verbose, env.apiKey, etc.
+ *     console.log(options.outputDir, options.verbose, env.apiKey);
+ *   }
+ * });
+ * ```
+ */
 /**
-* Converts option names to camelCase for the options object.
-* Options like "output-dir" become "outputDir" in the toolbox.
-* @example
-* ```typescript
-* // Option name: "output-dir" -> options.outputDir
-* // Option name: "api_key" -> options.apiKey
-* // Option name: "verbose" -> options.verbose
-* ```
-*/
+ * Converts option names to camelCase for the options object.
+ * Options like "output-dir" become "outputDir" in the toolbox.
+ * @example
+ * ```typescript
+ * // Option name: "output-dir" -> options.outputDir
+ * // Option name: "api_key" -> options.apiKey
+ * // Option name: "verbose" -> options.verbose
+ * ```
+ */
 type OptionNameToCamelCase<T extends string> = T extends `${infer Start}-${infer Rest}` ? `${Lowercase<Start>}${Capitalize<OptionNameToCamelCase<Rest>>}` : T extends `${infer Start}_${infer Rest}` ? `${Lowercase<Start>}${Capitalize<OptionNameToCamelCase<Rest>>}` : Lowercase<T>;
 /**
-* Helper type to create a type-safe options object from option definitions.
-* @example
-* ```typescript
-* type MyOptions = CreateOptions<{
-*   "output-dir": string | undefined;
-*   "verbose": boolean | undefined;
-*   "port": number | undefined;
-* }>;
-* // Result: { outputDir: string | undefined, verbose: boolean | undefined, port: number | undefined }
-* ```
-*/
-type CreateOptions<T extends Record<string, unknown>> = { [K in keyof T as OptionNameToCamelCase<K & string>]: T[K] };
+ * Helper type to create a type-safe options object from option definitions.
+ * @example
+ * ```typescript
+ * type MyOptions = CreateOptions<{
+ *   "output-dir": string | undefined;
+ *   "verbose": boolean | undefined;
+ *   "port": number | undefined;
+ * }>;
+ * // Result: { outputDir: string | undefined, verbose: boolean | undefined, port: number | undefined }
+ * ```
+ */
+type CreateOptions<T extends Record<string, unknown>> = { [K in keyof T as OptionNameToCamelCase<K & string>]: T[K]; };
 /**
-* Helper type to create a type-safe environment variables object from env definitions.
-* Environment variable names are converted from UPPER_SNAKE_CASE to camelCase.
-* @example
-* ```typescript
-* type MyEnv = CreateEnv<{
-*   "API_KEY": string | undefined;
-*   "DEBUG": boolean | undefined;
-* }>;
-* // Result: { apiKey: string | undefined, debug: boolean | undefined }
-* ```
-*/
-type CreateEnv<T extends Record<string, unknown>> = { [K in keyof T as OptionNameToCamelCase<K & string>]: T[K] };
+ * Helper type to create a type-safe environment variables object from env definitions.
+ * Environment variable names are converted from UPPER_SNAKE_CASE to camelCase.
+ * @example
+ * ```typescript
+ * type MyEnv = CreateEnv<{
+ *   "API_KEY": string | undefined;
+ *   "DEBUG": boolean | undefined;
+ * }>;
+ * // Result: { apiKey: string | undefined, debug: boolean | undefined }
+ * ```
+ */
+type CreateEnv<T extends Record<string, unknown>> = { [K in keyof T as OptionNameToCamelCase<K & string>]: T[K]; };
 /**
-* Builds a `loader` for commands whose handler lives as a named export in a
-* shared handler module (the typical pattern when one file holds multiple
-* subcommands' execute functions).
-* @example
-* ```ts
-* // commands/cache/handler.ts
-* export const cacheListExecute: CommandExecute<Toolbox> = async (toolbox) => { ... };
-* export const cacheCleanExecute: CommandExecute<Toolbox> = async (toolbox) => { ... };
-*
-* // commands/cache/index.ts
-* cli.addCommand({
-*     name: "list",
-*     loader: lazyNamed(() => import("./handler"), "cacheListExecute"),
-* });
-* ```
-*/
+ * Builds a `loader` for commands whose handler lives as a named export in a
+ * shared handler module (the typical pattern when one file holds multiple
+ * subcommands' execute functions).
+ * @example
+ * ```ts
+ * // commands/cache/handler.ts
+ * export const cacheListExecute: CommandExecute<Toolbox> = async (toolbox) => { ... };
+ * export const cacheCleanExecute: CommandExecute<Toolbox> = async (toolbox) => { ... };
+ *
+ * // commands/cache/index.ts
+ * cli.addCommand({
+ *     name: "list",
+ *     loader: lazyNamed(() => import("./handler"), "cacheListExecute"),
+ * });
+ * ```
+ */
 declare const lazyNamed: <M extends Record<string, unknown>, K extends keyof M, TContext>(load: () => Promise<M>, key: K) => () => Promise<LazyCommandModule<TContext>>;
 declare global {
   namespace Cerebro {
     /**
-    * Extend this interface to add custom properties to the Toolbox.
-    * This allows plugins and extensions to add type-safe properties to the toolbox.
-    * @example
-    * ```typescript
-    * declare global {
-    *   namespace Cerebro {
-    *     interface ExtensionOverrides {
-    *       // Add custom properties with full type safety
-    *       fs: {
-    *         readFile: (path: string) => Promise<string>;
-    *         writeFile: (path: string, content: string) => Promise<void>;
-    *       };
-    *       http: {
-    *         get: <T>(url: string) => Promise<T>;
-    *         post: <T>(url: string, data: unknown) => Promise<T>;
-    *       };
-    *       myCustomUtil: () => void;
-    *     }
-    *   }
-    * }
-    *
-    * // Now in your commands, you get full autocomplete:
-    * cli.addCommand({
-    *   name: "example",
-    *   execute: ({ fs, http, myCustomUtil }) => {
-    *     // ✅ Full autocomplete and type safety!
-    *     const content = await fs.readFile("file.txt");
-    *     const data = await http.get<MyType>("https://api.example.com");
-    *     myCustomUtil();
-    *   }
-    * });
-    * ```
-    */
+     * Extend this interface to add custom properties to the Toolbox.
+     * This allows plugins and extensions to add type-safe properties to the toolbox.
+     * @example
+     * ```typescript
+     * declare global {
+     *   namespace Cerebro {
+     *     interface ExtensionOverrides {
+     *       // Add custom properties with full type safety
+     *       fs: {
+     *         readFile: (path: string) => Promise<string>;
+     *         writeFile: (path: string, content: string) => Promise<void>;
+     *       };
+     *       http: {
+     *         get: <T>(url: string) => Promise<T>;
+     *         post: <T>(url: string, data: unknown) => Promise<T>;
+     *       };
+     *       myCustomUtil: () => void;
+     *     }
+     *   }
+     * }
+     *
+     * // Now in your commands, you get full autocomplete:
+     * cli.addCommand({
+     *   name: "example",
+     *   execute: ({ fs, http, myCustomUtil }) => {
+     *     // ✅ Full autocomplete and type safety!
+     *     const content = await fs.readFile("file.txt");
+     *     const data = await http.get<MyType>("https://api.example.com");
+     *     myCustomUtil();
+     *   }
+     * });
+     * ```
+     */
     export interface ExtensionOverrides {}
   }
 }
 /**
-* Main entry point for the Cerebro CLI framework.
-*
-* This module provides a lightweight, extensible CLI framework for building command-line applications.
-* It supports plugins, subcommands, argument parsing, help generation, and more.
-* @example
-* ```typescript
-* import { createCerebro } from '@visulima/cerebro';
-*
-* const cli = createCerebro('my-app', {
-*   packageName: 'my-app',
-*   packageVersion: '1.0.0'
-* });
-*
-* cli.addCommand({
-*   name: 'greet',
-*   description: 'Greet someone',
-*   argument: {
-*     name: 'name',
-*     description: 'Name to greet',
-*     type: String
-*   },
-*   execute: ({ argument }) => {
-*     console.log(`Hello, ${argument[0]}!`);
-*   }
-* });
-*
-* cli.run();
-* ```
-*/
-/**
-* Creates a new Cerebro CLI instance.
-*
-* This is the main factory function for creating CLI applications with Cerebro.
-* The returned CLI instance can be configured with commands, plugins, and options.
-* @template T - The console type (defaults to Console)
-* @param name The name of the CLI application
-* @param options Configuration options for the CLI
-* @returns A configured Cerebro CLI instance
-* @example
-* ```typescript
-* const cli = createCerebro('my-app', {
-*   packageName: 'my-app',
-*   packageVersion: '1.0.0'
-* });
-* ```
-*/
+ * Creates a new Cerebro CLI instance.
+ *
+ * This is the main factory function for creating CLI applications with Cerebro.
+ * The returned CLI instance can be configured with commands, plugins, and options.
+ * @template T - The console type (defaults to Console)
+ * @param name The name of the CLI application
+ * @param options Configuration options for the CLI
+ * @returns A configured Cerebro CLI instance
+ * @example
+ * ```typescript
+ * const cli = createCerebro('my-app', {
+ *   packageName: 'my-app',
+ *   packageVersion: '1.0.0'
+ * });
+ * ```
+ */
 declare const createCerebro: <T extends Console = Console>(name: string, options?: CliOptions<T>) => InstanceType<typeof Cli<T>>;
 export { Cli as Cerebro, type CerebroFs, type Cli$1 as Cli, type CliOptions, type CliRunOptions, type Command, type CommandExecute, type CreateEnv, type CreateOptions, type LazyCommandModule, type OptionDefinition, type OptionNameToCamelCase, type Plugin, type RunCommandOptions, type Toolbox, VERBOSITY_DEBUG, VERBOSITY_NORMAL, VERBOSITY_QUIET, VERBOSITY_VERBOSE, createCerebro, lazyNamed };