@visulima/cerebro 2.0.3 → 2.1.1

package/README.md

@@ -3,10 +3,10 @@
   <p>
   Cerebro is a delightful toolkit for building cross-runtime command-line interfaces (CLIs) for Node.js, Deno, and Bun, built on top of
 
-[boxen](https://github.com/visulima/visulima/tree/main/packages/boxen),
-[colorize](https://github.com/visulima/visulima/tree/main/packages/colorize),
-[cli-table3](https://github.com/cli-table/cli-table3),
-[command-line-args](https://github.com/75lb/command-line-args) and
+[@visulima/boxen](https://github.com/visulima/visulima/tree/main/packages/boxen),
+[@visulima/colorize](https://github.com/visulima/visulima/tree/main/packages/colorize),
+[@visulima/command-line-args](https://github.com/visulima/visulima/tree/main/packages/command-line-args),
+[@visulima/tabular](https://github.com/visulima/visulima/tree/main/packages/tabular) and
 [fastest-levenshtein](https://github.com/ka-weihe/fastest-levenshtein)
 
 <br />
@@ -53,30 +53,228 @@ pnpm add @visulima/cerebro
 ## Usage
 
 ```ts
-import Cli from "@visulima/cerebro";
+import { Cerebro } from "@visulima/cerebro";
 
 // Create a CLI runtime
-const cli = new Cli("cerebro");
+const cli = new Cerebro("my-cli");
 
-// Your command
+// Add commands with options and arguments
 cli.addCommand({
-    name: "main:colors",
-    description: "Output colors", // This is used in the help output
-    execute: ({ logger }) => {
-        logger.info("Colors command");
+    name: "build",
+    description: "Build the project",
+    options: [
+        {
+            name: "output",
+            alias: "o",
+            type: String,
+            description: "Output directory",
+            defaultValue: "dist"
+        },
+        {
+            name: "production",
+            alias: "p",
+            type: Boolean,
+            description: "Build for production"
+        },
+        {
+            name: "watch",
+            alias: "w",
+            type: Boolean,
+            description: "Watch for changes"
+        }
+    ],
+    argument: {
+        name: "target",
+        description: "Build target (optional)",
+        type: String
+    },
+    execute: ({ options, argument, logger, env }) => {
+        const target = argument[0] || "all";
+        const outputDir = options.output;
+
+        logger.info(`Building target: ${target}`);
+        logger.info(`Output directory: ${outputDir}`);
+
+        if (options.production) {
+            logger.info("Production build enabled");
+        }
+
+        if (options.watch) {
+            logger.info("Watch mode enabled");
+        }
+
+        if (env.NODE_ENV) {
+            logger.info(`Environment: ${env.NODE_ENV}`);
+        }
+    },
+});
+
+// Add another command with environment variables
+cli.addCommand({
+    name: "deploy",
+    description: "Deploy the application",
+    env: [
+        {
+            name: "DEPLOY_ENV",
+            description: "Deployment environment",
+            type: String,
+            defaultValue: "staging"
+        },
+        {
+            name: "API_KEY",
+            description: "API key for deployment",
+            type: String
+        }
+    ],
+    execute: ({ env, logger }) => {
+        logger.info(`Deploying to ${env.DEPLOY_ENV}`);
+        if (env.API_KEY) {
+            logger.info("Using provided API key");
+        }
     },
 });
 
 await cli.run();
 ```
 
-Now you can run your CLI with `node index.js` (or `deno run index.js`, `bun index.js`) and you should see the following output:
+Now you can run your CLI with `node index.js` (or `deno run index.js`, `bun index.js`). Here are some example usages:
+
+```bash
+# Show help
+node index.js --help
+
+# Build with default options
+node index.js build
+
+# Build specific target with custom output
+node index.js build --output ./build client
+
+# Production build with watch mode
+node index.js build --production --watch
+
+# Deploy (uses environment variables)
+node index.js deploy
+```
+
+You should see help output and command execution based on the options provided:
 
 ![Cli Output](./__assets__/cli_output.png)
 
+## Toolbox API
+
+When your command's `execute` function is called, it receives a toolbox object with various utilities and context. Here's what you can access:
+
+### Core Properties
+
+- **`logger`**: Logger instance for output (debug, info, warn, error)
+- **`options`**: Parsed command-line options (camelCase keys)
+- **`argument`**: Array of positional arguments
+- **`env`**: Environment variables (camelCase keys)
+- **`runtime`**: Reference to the CLI instance
+- **`argv`**: Original command-line arguments array
+
+### Example Usage
+
+```ts
+cli.addCommand({
+    name: "example",
+    description: "Example command showing toolbox usage",
+    options: [
+        { name: "verbose", alias: "v", type: Boolean, description: "Verbose output" },
+        { name: "count", alias: "c", type: Number, description: "Count value", defaultValue: 1 }
+    ],
+    argument: {
+        name: "input",
+        description: "Input file",
+        type: String
+    },
+    env: [
+        { name: "DEBUG", type: Boolean, description: "Debug mode" }
+    ],
+    execute: ({ logger, options, argument, env, runtime, argv }) => {
+        // Use logger for output
+        logger.info("Command started");
+
+        // Access parsed options
+        if (options.verbose) {
+            logger.debug(`Count: ${options.count}`);
+        }
+
+        // Access positional arguments
+        if (argument.length > 0) {
+            logger.info(`Processing file: ${argument[0]}`);
+        }
+
+        // Access environment variables
+        if (env.debug) {
+            logger.debug("Debug mode enabled");
+        }
+
+        // Access CLI instance
+        logger.info(`CLI name: ${runtime.cliName}`);
+
+        // Access original argv
+        logger.debug(`Full command: ${argv.join(' ')}`);
+    },
+});
+```
+
+## Built-in Commands
+
+Cerebro comes with several built-in commands that are automatically available:
+
+### Help Command
+
+The help command is automatically added to your CLI and provides usage information for all commands.
+
+```bash
+my-cli help
+my-cli help <command>
+```
+
+### Version Command
+
+Display version information for your CLI.
+
+```ts
+import { Cerebro } from "@visulima/cerebro";
+import versionCommand from "@visulima/cerebro/command/version";
+
+const cli = new Cerebro("my-cli", {
+  packageName: "my-cli",
+  packageVersion: "1.0.0"
+});
+
+cli.addCommand(versionCommand);
+
+await cli.run();
+```
+
+```bash
+my-cli version
+```
+
+### Readme Generator Command
+
+Generate README documentation for your CLI commands.
+
+```ts
+import { Cerebro } from "@visulima/cerebro";
+import readmeCommand from "@visulima/cerebro/command/readme-generator";
+
+const cli = new Cerebro("my-cli");
+cli.addCommand(readmeCommand);
+
+await cli.run();
+```
+
+```bash
+my-cli readme-generator
+```
+
 ## Shell Completions
 
-Cerebro supports shell autocompletions for bash, zsh, fish, and powershell through the optional `@bomb.sh/tab` integration.
+Cerebro supports intelligent shell autocompletions for **bash**, **zsh**, **fish**, and **powershell** through the optional `@bomb.sh/tab` integration. The completion system automatically detects your current shell and runtime, providing context-aware suggestions for commands, options, and arguments.
 
 ### Installation
 
@@ -86,17 +284,27 @@ To enable completions, first install the optional peer dependency:
 pnpm add @bomb.sh/tab
 ```
 
+Or with other package managers:
+
+```sh
+npm install @bomb.sh/tab
+yarn add @bomb.sh/tab
+```
+
 ### Adding Completion Command
 
-Import and add the completion command to your CLI:
+Import and add the completion command to your CLI. The completion command supports two options:
+
+- **`--shell`**: Shell type (bash, zsh, fish, powershell) - auto-detected by default
+- **`--runtime`**: JavaScript runtime (node, bun, deno) - auto-detected by default
 
 ```ts
-import Cli from "@visulima/cerebro";
+import { Cerebro } from "@visulima/cerebro";
 import completionCommand from "@visulima/cerebro/command/completion";
 
-const cli = new Cli("my-cli");
+const cli = new Cerebro("my-cli");
 
-// Add your commands
+// Add your commands with options
 cli.addCommand({
     name: "build",
     description: "Build the project",
@@ -107,6 +315,12 @@ cli.addCommand({
             type: String,
             description: "Output directory",
         },
+        {
+            name: "production",
+            alias: "p",
+            type: Boolean,
+            description: "Production build",
+        },
     ],
     execute: ({ options }) => {
         console.log(`Building to ${options.output || "dist"}`);
@@ -121,28 +335,69 @@ await cli.run();
 
 ### Generating Completion Scripts
 
-Users can generate completion scripts for their shell:
+Users can generate completion scripts for their shell. The completion command will automatically detect your shell and runtime, but you can override them if needed:
 
 ```bash
-# For zsh
+# Auto-detect shell and runtime (recommended)
+my-cli completion > ~/.my-cli-completion.sh
+echo 'source ~/.my-cli-completion.sh' >> ~/.bashrc  # or ~/.zshrc
+
+# Explicitly specify shell
 my-cli completion --shell=zsh > ~/.my-cli-completion.zsh
-echo 'source ~/.my-cli-completion.zsh' >> ~/.zshrc
+my-cli completion --shell=bash > ~/.my-cli-completion.bash
+my-cli completion --shell=fish > ~/.config/fish/completions/my-cli.fish
+my-cli completion --shell=powershell > ~/.my-cli-completion.ps1
+
+# Override runtime detection
+my-cli completion --runtime=node --shell=zsh > ~/.my-cli-completion.zsh
+```
 
-# For bash
+### Setup Instructions
+
+**Bash:**
+```bash
 my-cli completion --shell=bash > ~/.my-cli-completion.bash
 echo 'source ~/.my-cli-completion.bash' >> ~/.bashrc
+source ~/.bashrc
+```
 
-# For fish
+**Zsh:**
+```bash
+my-cli completion --shell=zsh > ~/.my-cli-completion.zsh
+echo 'source ~/.my-cli-completion.zsh' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Fish:**
+```bash
 my-cli completion --shell=fish > ~/.config/fish/completions/my-cli.fish
 ```
 
-After setting up, users can use `TAB` to autocomplete commands and options.
+**PowerShell:**
+```powershell
+my-cli completion --shell=powershell > $PROFILE.CurrentUserAllHosts
+. $PROFILE.CurrentUserAllHosts
+```
+
+After setting up, users can press `TAB` to autocomplete:
+- Command names
+- Option flags (both long `--option` and short `-o`)
+- Option values (when applicable)
+- Subcommands
+
+### Troubleshooting
+
+If completions don't work:
+1. Ensure `@bomb.sh/tab` is installed
+2. Verify the completion script was sourced in your shell profile
+3. Try restarting your shell or running `source ~/.bashrc` (or equivalent)
+4. Check that your CLI name matches the completion script filename
 
 ## Supported Runtimes
 
 Cerebro supports multiple JavaScript runtimes:
 
-- **Node.js**: 18+ (follows [Node.js' release schedule](https://github.com/nodejs/release#release-schedule))
+- **Node.js**: >=20.19 <=25.x (follows [Node.js' release schedule](https://github.com/nodejs/release#release-schedule))
 - **Deno**: 1.0+
 - **Bun**: 1.0+
 

package/dist/cli.d.ts

@@ -0,0 +1,203 @@
+import PluginManager from "./plugin-manager.d.ts";
+import type { Cli as ICli, CliRunOptions, CommandSection as ICommandSection, ExtendedLogger, 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 ExtendedLogger = ExtendedLogger> = {
+    argv?: ReadonlyArray<string>;
+    cwd?: string;
+    logger?: T;
+    packageName?: string;
+    packageVersion?: string;
+};
+export declare class Cli<T extends ExtendedLogger = ExtendedLogger> implements ICli {
+    #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>): this;
+    /**
+     * 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): this;
+    /**
+     * Gets the plugin manager instance for advanced plugin management.
+     * @returns The plugin manager instance
+     */
+    getPluginManager(): PluginManager;
+    /**
+     * 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>;
+    /**
+     * 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/commands/completion-command.d.ts

@@ -1,6 +1,6 @@
-import { b as Command } from '../packem_shared/plugin-manager-BjEuiNxv.js';
-import '@visulima/tabular';
-
-declare const completionCommand: Command;
-
-export { completionCommand as default };
+import type { Command as ICommand } from "../types/command.d.ts";
+/**
+ * Generates shell completion scripts for the CLI application.
+ */
+declare const completionCommand: ICommand;
+export default completionCommand;

package/dist/commands/help-command.d.ts

@@ -1,12 +1,10 @@
-import { b as Command, O as OptionDefinition, T as Toolbox } from '../packem_shared/plugin-manager-BjEuiNxv.js';
-import '@visulima/tabular';
-
-declare class HelpCommand implements Command {
+import type { Command as ICommand, OptionDefinition } from "../types/command.d.ts";
+import type { Toolbox as IToolbox } from "../types/toolbox.d.ts";
+declare class HelpCommand implements ICommand {
     name: string;
     options: OptionDefinition<string>[];
     private readonly commands;
-    constructor(commands: Map<string, Command>);
-    execute(toolbox: Toolbox): void;
+    constructor(commands: Map<string, ICommand>);
+    execute(toolbox: IToolbox): void;
 }
-
-export { HelpCommand as default };
+export default HelpCommand;

package/dist/commands/help-command.js

@@ -1 +1 @@
-import"@visulima/colorize";import{O as p}from"../packem_shared/help-command-C_CdZQSd.js";import"../packem_shared/index-DQ3pvLQH.js";export{p as default};
+import"@visulima/colorize";import{A as p}from"../packem_shared/help-command-Ddt6rdio.js";import"../packem_shared/index-DQ3pvLQH.js";export{p as default};

package/dist/commands/readme-command.d.ts

@@ -1,6 +1,6 @@
-import { b as Command } from '../packem_shared/plugin-manager-BjEuiNxv.js';
-import '@visulima/tabular';
-
-declare const readmeCommand: Command;
-
-export { readmeCommand as default };
+import type { Command as ICommand } from "../types/command.d.ts";
+/**
+ * Generates README documentation for cerebro CLI commands.
+ */
+declare const readmeCommand: ICommand;
+export default readmeCommand;

package/dist/commands/version-command.d.ts

@@ -1,6 +1,3 @@
-import { b as Command } from '../packem_shared/plugin-manager-BjEuiNxv.js';
-import '@visulima/tabular';
-
-declare const _default: Command;
-
-export { _default as default };
+import type { Command as ICommand } from "../types/command.d.ts";
+declare const _default: ICommand;
+export default _default;

package/dist/constants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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

@@ -0,0 +1,7 @@
+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<string> | EnvDefinition<number> | EnvDefinition<boolean>)[];
+export default defaultEnv;

package/dist/default-options.d.ts

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