@visulima/cerebro 3.0.0-alpha.3 → 3.0.0-alpha.30

package/dist/index.d.ts

@@ -1,99 +1,505 @@
-import type { CliOptions } from './cli.d.ts';
-import { Cli } from './cli.d.ts';
+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/plugin-manager.d-BSQtHbWS.js";
+export { type A as ArgumentDefinition, type g as CerebroProcess, type E as EnvDefinition, type h as OutputType, type i as PluginContext, type V as VERBOSITY_LEVEL } from "./packem_shared/plugin-manager.d-BSQtHbWS.js";
+export { V as VisulimaError } from "./packem_shared/index.d-Br8HpP0A.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.
+  */
+  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.
+  */
+  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).
+  */
+  fs?: CerebroFs;
+  logger?: T;
+  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.
+  */
+  stdin?: string;
+};
+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
+  */
+  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: CommandSection): this;
+  /**
+  * 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');
+  * ```
+  */
+  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: 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',
+  * });
+  * ```
+  */
+  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, Command<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>;
+  /**
+  * 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);
+  * ```
+  */
+  getAction(commandName: string): Promise<CommandExecute<Toolbox<T>>>;
+}
+/**
+* Output with this verbosity won't write anything at all.
+*/
+declare const VERBOSITY_QUIET = 16;
+/**
+* Output with this verbosity will write default content.
+*/
+declare const VERBOSITY_NORMAL = 32;
+/**
+* Output with this verbosity will be more detailed.
+*/
+declare const VERBOSITY_VERBOSE = 64;
+/**
+* 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);
+*   }
+* });
+* ```
+*/
+/**
+* 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 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"),
+* });
+* ```
+*/
+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();
-         *   }
-         * });
-         * ```
-         */
-        interface ExtensionOverrides {
-        }
-    }
+  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();
+    *   }
+    * });
+    * ```
+    */
+    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();
- * ```
- */
-export type { CliOptions } from './cli.d.ts';
-export { Cli as Cerebro } from './cli.d.ts';
-export { VERBOSITY_DEBUG, VERBOSITY_NORMAL, VERBOSITY_QUIET, VERBOSITY_VERBOSE } from './constants.d.ts';
-export type { Cli, CliRunOptions, OutputType, RunCommandOptions, VERBOSITY_LEVEL } from './types/cli.d.ts';
-export type { ArgumentDefinition, Command, EnvDefinition, OptionDefinition } from './types/command.d.ts';
-export type { CreateEnv, CreateOptions, OptionNameToCamelCase } from './types/option-types.d.ts';
-export type { Plugin, PluginContext } from './types/plugin.d.ts';
-export type { Toolbox } from './types/toolbox.d.ts';
-export { VisulimaError } from "@visulima/error";
+* 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'
- * });
- * ```
- */
-export declare const createCerebro: <T extends Console = Console>(name: string, options?: CliOptions<T>) => InstanceType<typeof Cli<T>>;
+* 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 };

package/dist/index.js

@@ -1 +1 @@
-var t=Object.defineProperty;var o=(r,e)=>t(r,"name",{value:e,configurable:!0});import{Cli as a}from"./packem_shared/Cerebro-aPZjbfzf.js";import{VERBOSITY_DEBUG as V,VERBOSITY_NORMAL as b,VERBOSITY_QUIET as c,VERBOSITY_VERBOSE as f}from"./packem_shared/VERBOSITY_QUIET-XPultrIA.js";import{p as I}from"./packem_shared/isVisulimaError-jVZgumOU-C4fgdbWg.js";var E=Object.defineProperty,O=o((r,e)=>E(r,"name",{value:e,configurable:!0}),"t");const p=O((r,e)=>new a(r,e),"createCerebro");export{a as Cerebro,V as VERBOSITY_DEBUG,b as VERBOSITY_NORMAL,c as VERBOSITY_QUIET,f as VERBOSITY_VERBOSE,I as VisulimaError,p as createCerebro};
+var a=Object.defineProperty;var o=(r,e)=>a(r,"name",{value:e,configurable:!0});import{Cli as t}from"./packem_shared/Cerebro-BN_nIZ8z.js";import{VERBOSITY_DEBUG as R,VERBOSITY_NORMAL as V,VERBOSITY_QUIET as b,VERBOSITY_VERBOSE as c}from"./packem_shared/VERBOSITY_QUIET-XPultrIA.js";import{lazyNamed as n}from"./packem_shared/lazyNamed-DOmefeJM.js";import{p as S}from"./packem_shared/isVisulimaError-jVZgumOU-C4fgdbWg.js";var E=Object.defineProperty,m=o((r,e)=>E(r,"name",{value:e,configurable:!0}),"t");const f=m((r,e)=>new t(r,e),"createCerebro");export{t as Cerebro,R as VERBOSITY_DEBUG,V as VERBOSITY_NORMAL,b as VERBOSITY_QUIET,c as VERBOSITY_VERBOSE,S as VisulimaError,f as createCerebro,n as lazyNamed};