@visulima/cerebro 3.0.3 → 3.0.5

package/dist/packem_shared/command.d-DbhtfXF4.d.ts

@@ -1,639 +0,0 @@
-import { TableOptions } from '@visulima/tabular';
-/**
-* Definition for a command-line option.
-*
-* The optional `Name` and `Value` type parameters allow {@link CommandLineOptions}
-* to be inferred from an `as const` array of definitions. They default to the
-* loose runtime shape so plain `OptionDefinition` usage is unaffected.
-*/
-interface OptionDefinition$1<Name extends string = string, Value = unknown> {
-  /**
-  * A getopt-style short option name. Can be any single character except a digit or hyphen.
-  */
-  alias?: string;
-  /**
-  * Any values unaccounted for by an option definition will be set on the `defaultOption`. This flag is typically set
-  * on the most commonly-used option to enable more concise usage.
-  */
-  defaultOption?: boolean;
-  /**
-  * An initial value for the option.
-  */
-  defaultValue?: Value;
-  /**
-  * One or more group names the option belongs to.
-  */
-  group?: string | string[];
-  /**
-  * Identical to `multiple` but with greedy parsing disabled.
-  */
-  lazyMultiple?: boolean;
-  /**
-  * Set this flag if the option accepts multiple values. In the output, you will receive an array of values each passed through the `type` function.
-  */
-  multiple?: boolean;
-  /**
-  * The long option name.
-  */
-  name: Name;
-  /**
-  * A setter function (you receive the output from this) enabling you to be specific about the type and value received. Typical values
-  * are `String` (the default), `Number` and `Boolean` but you can use a custom function. If no option value was set you will receive `null`.
-  */
-  type?: (input: string) => Value;
-}
-/**
-* Resolve a single {@link OptionDefinition} to the type of its parsed value,
-* taking `type`, `multiple`/`lazyMultiple` and `defaultValue` into account.
-*
-* Part of the public type surface: re-exported from the package entry and used by
-* {@link InferCommandLineOptions}.
-*/
-/** A Content section comprises a header and one or more lines of content. */
-interface Content {
-  /**
-  * Overloaded property, accepting data in one of four formats.
-  * 1. A single string (one line of text).
-  * 2. An array of strings (multiple lines of text).
-  * 3. An array of arrays (recordset-style data). In this case, the data will be rendered in table format.
-  * 4. An object with two properties - data and options. In this case, the data and options will be passed directly to the underlying table module for rendering.
-  */
-  content?: string[] | string[][] | string | {
-    data: string[][];
-    options: TableOptions;
-  };
-  /** The section header, always bold and underlined. */
-  header?: string;
-  /** Set to true to avoid indentation and wrapping. Useful for banners. */
-  raw?: boolean;
-}
-/**
-* Context provided to plugins during initialization
-*/
-interface PluginContext<T extends Console = Console> {
-  /** The CLI instance */
-  cli: Cli<T>;
-  /** Current working directory */
-  cwd: string;
-  /** Logger instance */
-  logger: T;
-}
-/**
-* Plugin interface with lifecycle hooks
-*/
-interface Plugin<T extends Console = Console> {
-  /**
-  * Called after command execution completes successfully
-  * @param toolbox The command toolbox
-  * @param result The result returned by the command
-  */
-  afterCommand?: (toolbox: Toolbox<T>, result: unknown) => Promise<void> | void;
-  /**
-  * Called before command execution
-  * @param toolbox The command toolbox
-  */
-  beforeCommand?: (toolbox: Toolbox<T>) => Promise<void> | void;
-  /** Plugin dependencies (other plugin names that must be loaded first) */
-  dependencies?: string[];
-  /** Plugin description */
-  description?: string;
-  /**
-  * Called during command execution (for plugins that extend toolbox functionality)
-  * @param toolbox The command toolbox
-  */
-  execute?: (toolbox: Toolbox<T>) => Promise<void> | void;
-  /**
-  * Called once during plugin initialization
-  * @param context The plugin context
-  */
-  init?: (context: PluginContext<T>) => Promise<void> | void;
-  /** Plugin name (must be unique) */
-  name: string;
-  /**
-  * Called when an error occurs during command execution
-  * @param error The error that occurred
-  * @param toolbox The command toolbox
-  */
-  onError?: (error: Error, toolbox: Toolbox<T>) => Promise<void> | void;
-  /** Plugin version */
-  version?: string;
-}
-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;
-}
-type CommandSection = {
-  footer?: string;
-  header?: string;
-};
-type CliRunOptions = {
-  [key: string]: unknown;
-  /**
-  * Whether to automatically dispose/cleanup the CLI instance after execution
-  * @default true
-  */
-  autoDispose?: boolean;
-  shouldExitProcess?: boolean;
-};
-type RunCommandOptions = {
-  /**
-  * Extra options to merge into the command's options.
-  * These will be merged with the command's default options and parsed arguments.
-  * Use this to override or add additional options programmatically.
-  * @default Empty object
-  */
-  [key: string]: unknown;
-  /**
-  * Command-line arguments to pass to the command.
-  * If not provided, uses the default argv from the CLI instance.
-  * These arguments will be parsed and merged with the command's options.
-  * @default Empty array
-  */
-  argv?: string[];
-};
-interface Cli<T extends Console> {
-  /**
-  * Add an arbitrary command to the CLI.
-  * @param command The command to add.
-  * @returns self
-  */
-  addCommand: <OD extends OptionDefinition<unknown> = OptionDefinition<unknown>>(command: Command<OD, T>) => this;
-  /**
-  * Add a global option available to all commands.
-  * Global options are parsed alongside command options and shown in help output.
-  * @param option The option definition
-  * @returns self
-  */
-  addGlobalOption: <V = unknown>(option: OptionDefinition<V>) => this;
-  /**
-  * Add a plugin to extend the CLI functionality
-  * @param plugin The plugin to add.
-  * @returns self
-  */
-  addPlugin: (plugin: Plugin<T>) => this;
-  /**
-  * Disposes the CLI instance and cleans up resources
-  * @returns void
-  */
-  dispose: () => void;
-  getCliName: () => string;
-  getCommands: () => Map<string, Command<OptionDefinition<unknown>, T>>;
-  getCommandSection: () => CommandSection;
-  getCwd: () => string;
-  /**
-  * Gets all global options (built-in + custom).
-  */
-  getGlobalOptions: () => OptionDefinition<unknown>[];
-  getPackageName: () => string | undefined;
-  getPackageVersion: () => string | undefined;
-  /**
-  * Get the plugin manager instance
-  * @returns The plugin manager
-  */
-  getPluginManager: () => PluginManager<T>;
-  run: (extraOptions?: CliRunOptions) => Promise<void>;
-  /**
-  * Runs a command programmatically from within another command.
-  * This allows commands to call other commands during execution.
-  * @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 (or void if command doesn't return a value)
-  * @throws {Error} If the specified command doesn't exist or command arguments are invalid
-  * @example
-  * ```typescript
-  * cli.addCommand({
-  *   name: 'deploy',
-  *   execute: async ({ runtime, logger }) => {
-  *     logger.info('Building...');
-  *     const buildResult = await runtime.runCommand('build', { argv: ['--production'] });
-  *     // buildResult is the return value from the build command's execute function
-  *
-  *     logger.info('Testing...');
-  *     await runtime.runCommand('test', { argv: ['--coverage'] });
-  *   }
-  * });
-  * ```
-  */
-  runCommand: (commandName: string, options?: RunCommandOptions) => Promise<unknown>;
-  setCommandSection: (commandSection: CommandSection) => this;
-  /**
-  * Set a default command, to display a different command if cli is call without command.
-  * @param commandName
-  * @returns self
-  */
-  setDefaultCommand: (commandName: string) => this;
-}
-/**
-* Any of the output types [[OUTPUT_NORMAL]], [[OUTPUT_RAW]] and [[OUTPUT_PLAIN]].
-*/
-type OutputType = 1 | 2 | 4;
-/**
-* Any of the verbosity types
-* [[VERBOSITY_QUIET]], [[VERBOSITY_NORMAL]], [[VERBOSITY_VERBOSE]] and [[VERBOSITY_DEBUG]].
-*/
-type VERBOSITY_LEVEL = 16 | 32 | 64 | 128 | 256;
-/**
-* A flexible object for the many "options" objects we throw around in cerebro.
-*/
-type Options = Record<string | symbol, unknown>;
-/**
-* Runtime-injected filesystem adapter. A subset of `node:fs/promises` covering
-* the operations commonly used by CLI commands (config files, credentials,
-* cache paths). Defaults to `node:fs/promises` at runtime, but can be swapped
-* for an in-memory adapter in tests or a sandbox in MCP/JustBash environments.
-*/
-interface CerebroFs {
-  access: (path: string, mode?: number) => Promise<void>;
-  mkdir: (path: string, options?: {
-    recursive?: boolean;
-  }) => Promise<string | undefined>;
-  readdir: (path: string) => Promise<string[]>;
-  readFile: ((path: string) => Promise<Uint8Array>) & ((path: string, encoding: BufferEncoding) => Promise<string>);
-  rm: (path: string, options?: {
-    force?: boolean;
-    recursive?: boolean;
-  }) => Promise<void>;
-  stat: (path: string) => Promise<{
-    isDirectory: () => boolean;
-    isFile: () => boolean;
-  }>;
-  writeFile: (path: string, data: string | Uint8Array, encoding?: BufferEncoding) => Promise<void>;
-}
-/**
-* Runtime-injected process info. Snapshot of cwd / env / argv / platform / arch
-* captured at CLI construction time, plus an `exit` function and a `stdin`
-* buffer for tests and sandbox runtimes.
-*
-* Prefer reading these from the toolbox over reaching for global `process` so
-* commands stay portable across Node, Deno, Bun, and mocked test runtimes.
-*/
-interface CerebroProcess {
-  /** CPU architecture, e.g. "x64", "arm64". */
-  arch: string;
-  /** The full command-line arguments array (same shape as `process.argv`). */
-  argv: ReadonlyArray<string>;
-  /** Working directory the CLI was constructed with. */
-  cwd: string;
-  /** Environment variables. May be the host `process.env` or an injected snapshot. */
-  env: Record<string, string | undefined>;
-  /**
-  * Terminate the process with the given exit code. Defaults to the
-  * runtime-agnostic exit helper, but can be overridden via `CliOptions.exit`
-  * to capture exit codes in tests instead of killing the runner.
-  */
-  exit: (code?: number) => void;
-  /** OS platform, e.g. "linux", "darwin", "win32". */
-  platform: string;
-  /**
-  * Buffered stdin content. Empty string when there is no piped input.
-  * Tests and sandbox runtimes can populate this without wiring real streams.
-  */
-  stdin: string;
-}
-/**
-* Type-safe Toolbox interface with customizable options and environment variable types.
-* @template TLogger - The logger type (defaults to Console)
-* @template TOptions - The options type (defaults to Options/Record&lt;string, unknown>)
-* @template TEnv - The environment variables type (defaults to Record&lt;string, unknown>)
-*/
-interface Toolbox<TLogger extends Console = Console, TOptions extends Record<string, unknown> = Options, TEnv extends Record<string, unknown> = Record<string, unknown>> extends Cerebro.ExtensionOverrides {
-  /**
-  * The argument passed to the command.
-  * For example, if you run `cerebro foo bar baz`, then this will be `["foo", "bar", "baz"]`.
-  * @example
-  * ```typescript
-  * cli.addCommand({
-  *   name: "copy",
-  *   argument: {
-  *     name: "files",
-  *     type: String,
-  *     description: "Files to copy"
-  *   },
-  *   execute: ({ argument }) => {
-  *     // argument is an array of strings
-  *     // argument[0] is the first file, argument[1] is the second, etc.
-  *     argument.forEach((file) => console.log(`Copying ${file}...`));
-  *   }
-  * });
-  * ```
-  */
-  argument: string[];
-  argv: ReadonlyArray<string>;
-  /**
-  * The command that is being executed.
-  */
-  command: Command;
-  /**
-  * The name of the command that is being executed.
-  */
-  commandName: string;
-  /**
-  * Alias for `logger`. Exposed under the `console` name so commands can
-  * write portable `({ console }) => console.log(...)` code without reaching
-  * for the global `console`. The injected value is the same object as
-  * `toolbox.logger`, so verbosity-aware methods (`debug`) keep working.
-  */
-  console: TLogger;
-  /**
-  * Environment variables processed from the command definition.
-  * Values are transformed according to their type definitions and default values.
-  * @example
-  * ```typescript
-  * // Define env types when creating command
-  * type MyEnv = { apiKey: string; debug: boolean };
-  *
-  * cli.addCommand({
-  *   name: "build",
-  *   env: [
-  *     { name: "API_KEY", type: String },
-  *     { name: "DEBUG", type: Boolean }
-  *   ],
-  *   execute: ({ env }) => {
-  *     // env.apiKey and env.debug are now typed!
-  *     console.log(env.apiKey, env.debug);
-  *   }
-  * });
-  * ```
-  */
-  env: TEnv;
-  /**
-  * Filesystem adapter. Defaults to `node:fs/promises`, but can be swapped via
-  * `CliOptions.fs` for tests (in-memory adapter) or sandboxed runtimes
-  * (JustBash, MCP). Prefer `toolbox.fs` over a direct `node:fs/promises`
-  * import inside command actions to keep them portable and testable.
-  */
-  fs: CerebroFs;
-  /** The logger instance. */
-  logger: TLogger;
-  /**
-  * Any optional parameters. Typically coming from command-line
-  * argument like this: `--force -p tsconfig-mjson`.
-  * @example
-  * ```typescript
-  * // Define options type for better autocomplete
-  * type MyOptions = {
-  *   output?: string;
-  *   verbose?: boolean;
-  *   port?: number;
-  * };
-  *
-  * cli.addCommand({
-  *   name: "serve",
-  *   options: [
-  *     { name: "output", type: String },
-  *     { name: "verbose", type: Boolean },
-  *     { name: "port", type: Number }
-  *   ],
-  *   execute: ({ options }: { options: MyOptions }) => {
-  *     // options.output, options.verbose, options.port are typed!
-  *     console.log(options.output, options.verbose, options.port);
-  *   }
-  * });
-  * ```
-  */
-  options: TOptions;
-  /**
-  * Runtime process info — cwd, env, argv, exit, platform, arch, stdin —
-  * captured at CLI construction. Prefer `toolbox.process` over reaching for
-  * the global `process` so commands stay portable across Node, Deno, Bun,
-  * and mocked test runtimes. `process.exit` honors the `CliOptions.exit`
-  * override, which lets tests assert exit codes without killing the runner.
-  */
-  process: CerebroProcess;
-  /**
-  * Raw tokens that command-line-args could not assign to a defined
-  * option — typically everything after a `--` separator, since
-  * cerebro runs the parser with `stopAtFirstUnknown: true`.
-  *
-  * Use this for passthrough patterns like
-  * `my-cmd foo bar -- --flag=value --other`, where everything after
-  * `--` is forwarded to an inner tool (`create-vite`, a template
-  * runner, etc.). Empty array when there was no `--` segment.
-  * @example
-  * ```typescript
-  * cli.addCommand({
-  *   name: "create",
-  *   argument: { name: "template", type: String },
-  *   execute: ({ argument, rawUnknown }) => {
-  *     // `vis create vite my-app -- --template react-ts`
-  *     // → argument === ["vite", "my-app"]
-  *     // → rawUnknown === ["--template", "react-ts"]
-  *     spawnSync("npm", ["create", "vite", ...rawUnknown]);
-  *   },
-  * });
-  * ```
-  */
-  rawUnknown: ReadonlyArray<string>;
-  /**
-  * This is the instance of the CLI that is running the command.
-  */
-  runtime: Cli<TLogger>;
-}
-type TypeConstructor<T> = (value: unknown) => T extends (infer R)[] ? R | undefined : T | undefined;
-/**
-* Type constructor for environment variables.
-* Environment variables are always strings (or undefined), so the transform function receives string | undefined.
-*/
-type EnvTypeConstructor<T> = (value: string | undefined) => T extends (infer R)[] ? R | undefined : T | undefined;
-type MultiplePropertyOptions<T> = T extends ReadonlyArray<unknown> ? {
-  lazyMultiple: true;
-} | {
-  multiple: true;
-} : unknown;
-type OptionDefinition<T> = MultiplePropertyOptions<T> & Omit<OptionDefinition$1, "type|defaultValue"> & {
-  /**
-  * Restricts the accepted values for this option to a fixed set, validated
-  * at parse time (like commander's `.choices()` / yargs `choices`). The
-  * provided value(s) are compared by string equality; for `multiple`
-  * options every provided value must be a member of the set.
-  * @example
-  * ```typescript
-  * { name: "format", type: String, choices: ["json", "yaml", "table"] }
-  * ```
-  */
-  choices?: ReadonlyArray<string>;
-  /**
-  * A string or array of strings indicating the conflicting option(s).
-  * Note: The default value for an option does not cause a conflict.
-  */
-  conflicts?: string[] | string;
-  /** An initial value for the option. */
-  defaultValue?: T;
-  /** A string describing the option. */
-  description?: string;
-  /** Option is hidden from help */
-  hidden?: boolean;
-  implies?: Record<string, unknown>; /** Specifies whether the variable is required. */
-  required?: boolean;
-  /**
-  * A setter function (you receive the output from this) enabling you to be specific about the type and value received. Typical values
-  * are `String`, `Number` and `Boolean` but you can use a custom function.
-  */
-  type?: TypeConstructor<T>;
-  /** A string to replace the default type string (e.g. &lt;string>). It's often more useful to set a more descriptive type label, like &lt;ms>, &lt;files>, &lt;command>, etc.. */
-  typeLabel?: string;
-};
-type ArgumentDefinition<T = unknown> = Omit<OptionDefinition<T>, "multiple|lazyMultiple|defaultOption|alias|group|defaultValue">;
-/**
-* Environment variable definition for commands.
-* Used to document and provide type-safe access to environment variables a command supports.
-* @template T The type of the environment variable value
-*/
-interface EnvDefinition<T = string> {
-  /** Default value if the environment variable is not set */
-  defaultValue?: T;
-  /** A description of what the environment variable does */
-  description?: string;
-  /** Environment variable is hidden from help */
-  hidden?: boolean;
-  /** The name of the environment variable */
-  name: string;
-  /**
-  * A transform function to convert the string environment variable value to the desired type.
-  * Typical values are `String`, `Number`, `Boolean` or custom functions.
-  * The function receives `string | undefined` and should return the transformed value.
-  */
-  type?: EnvTypeConstructor<T>;
-  /** A string to replace the default type string (e.g. &lt;string>). Useful for more descriptive type labels. */
-  typeLabel?: string;
-}
-/**
-* Command interface with type-safe options and environment variables.
-* @template O - The option definition type
-* @template TContext - The toolbox context type (allows custom typing for better autocomplete)
-* @example
-* ```typescript
-* // Define your options type for autocomplete
-* type BuildOptions = {
-*   output?: string;
-*   production?: boolean;
-*   watch?: boolean;
-* };
-*
-* type BuildEnv = {
-*   apiKey?: string;
-*   debug?: boolean;
-* };
-*
-* cli.addCommand({
-*   name: "build",
-*   options: [
-*     { name: "output", type: String, alias: "o" },
-*     { name: "production", type: Boolean },
-*     { name: "watch", type: Boolean }
-*   ],
-*   env: [
-*     { name: "API_KEY", type: String },
-*     { name: "DEBUG", type: Boolean }
-*   ],
-*   execute: ({ options, env }: Toolbox<Console, BuildOptions, BuildEnv>) => {
-*     // Full autocomplete on options and env!
-*     console.log(options.output, options.production, env.apiKey);
-*   }
-* });
-* ```
-*/
-/**
-* Handler signature for commands. Used by both `execute` and the resolved default export of `loader`.
-*/
-type CommandExecute<TContext> = ((toolbox: TContext) => Promise<void>) | ((toolbox: TContext) => void);
-/**
-* Module shape returned by a command `loader`. The default export is the command handler.
-*/
-interface LazyCommandModule<TContext> {
-  default: CommandExecute<TContext>;
-}
-interface Command<O extends OptionDefinition<unknown> = OptionDefinition<unknown>, TLogger extends Console = Console, TContext extends Toolbox<TLogger> = Toolbox<TLogger>> {
-  /** Potential other names for this command */
-  alias?: string[] | string;
-  /** Positional argument */
-  argument?: ArgumentDefinition;
-  /** The command path, an array that describes how to get to this command */
-  commandPath?: string[];
-  /** A tweet-sized summary of your command */
-  description?: string;
-  /** Environment variables supported by this command */
-  env?: (EnvDefinition<boolean> | EnvDefinition<number> | EnvDefinition)[];
-  /** The full command examples, can be multiple lines */
-  examples?: string[] | string[][];
-  /**
-  * The function for running your command, can be async.
-  * Either `execute` or `loader` must be provided (but not both).
-  */
-  execute?: CommandExecute<TContext>;
-  /** The path to the file name for this command. */
-  file?: string;
-  /** Group commands together under a heading */
-  group?: string;
-  /** Should your command be shown in the listings  */
-  hidden?: boolean;
-  /**
-  * Lazily loads the command handler on first execution. The module's default export is used as the handler.
-  * Either `execute` or `loader` must be provided (but not both).
-  * Help, completion, and validation work from the metadata declared on this object and never trigger the loader.
-  * @example
-  * ```typescript
-  * cli.addCommand({
-  *   name: "build",
-  *   description: "Build the project",
-  *   options: [{ name: "output", type: String }],
-  *   loader: () => import("./commands/build"),
-  * });
-  *
-  * // commands/build.ts
-  * export default ({ options }) => { ... };
-  * ```
-  */
-  loader?: () => Promise<LazyCommandModule<TContext>>;
-  /** The name of your command */
-  name: string;
-  options?: (O | OptionDefinition<boolean[]> | OptionDefinition<boolean> | OptionDefinition<number[]> | OptionDefinition<number> | OptionDefinition<string[]> | OptionDefinition<string>)[];
-  usage?: Content[];
-}
-export { ArgumentDefinition as A, Command as C, EnvDefinition as E, LazyCommandModule as L, OptionDefinition as O, Plugin as P, RunCommandOptions as R, Toolbox as T, VERBOSITY_LEVEL as V, CerebroFs as a, CommandSection as b, PluginManager as c, CliRunOptions as d, CommandExecute as e, Cli as f, CerebroProcess as g, OutputType as h, PluginContext as i };