@visulima/cerebro 2.1.5 → 3.0.0-alpha.10

package/dist/packem_shared/Cerebro-bgCm5Tb1.js

@@ -0,0 +1,3444 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+import HelpCommand from '../commands/help-command.js';
+import { VERBOSITY_DEBUG, POSITIONALS_KEY, VERBOSITY_QUIET, VERBOSITY_VERBOSE, VERBOSITY_NORMAL } from './VERBOSITY_QUIET-Dp46zlLW.js';
+import { C as CerebroError } from './cerebro-error-GmJ3jN7Q.js';
+import { d as getEnv, f as getArgv, o as onProcessEvent, e as exitProcess, g as getCwd, h as getExecPath, i as getExecArgv } from './runtime-process-B6ZplyWn.js';
+import { distance } from 'fastest-levenshtein';
+const {
+  createRequire
+} = __cjs_getBuiltinModule("node:module");
+
+const defaultOptions = [
+  {
+    description: "Turn on verbose output",
+    group: "global",
+    name: "verbose",
+    type: Boolean
+  },
+  {
+    description: "Turn on debugging output",
+    group: "global",
+    name: "debug",
+    type: Boolean
+  },
+  {
+    alias: "h",
+    description: "Print out helpful usage information",
+    group: "global",
+    name: "help",
+    type: Boolean
+  },
+  {
+    alias: "q",
+    description: "Silence output",
+    group: "global",
+    name: "quiet",
+    type: Boolean
+  },
+  {
+    alias: "V",
+    description: "Print version info",
+    group: "global",
+    name: "version",
+    type: Boolean
+  },
+  {
+    description: "Turn off colored output",
+    group: "global",
+    name: "no-color",
+    type: Boolean
+  },
+  {
+    description: "Force colored output",
+    group: "global",
+    name: "color",
+    type: Boolean
+  }
+];
+
+class CommandNotFoundError extends CerebroError {
+  commandName;
+  constructor(commandName, suggestions = []) {
+    const message = `Command "${commandName}" not found${suggestions.length > 0 ? `. Did you mean: ${suggestions.join(", ")}?` : ""}`;
+    super(message, "COMMAND_NOT_FOUND", {
+      commandName,
+      suggestions
+    });
+    this.name = "CommandNotFoundError";
+    this.commandName = commandName;
+    if (suggestions.length > 0) {
+      this.hint = `Try one of these commands: ${suggestions.join(", ")}`;
+    }
+  }
+}
+
+class ConflictingOptionsError extends CerebroError {
+  option1;
+  option2;
+  constructor(option1, option2) {
+    super(`Options "${option1}" and "${option2}" cannot be used together`, "CONFLICTING_OPTIONS", { option1, option2 });
+    this.name = "ConflictingOptionsError";
+    this.option1 = option1;
+    this.option2 = option2;
+    this.hint = `Remove either --${option1} or --${option2}`;
+  }
+}
+
+class PluginError extends CerebroError {
+  pluginName;
+  constructor(pluginName, message, originalError) {
+    super(`Plugin "${pluginName}" error: ${message}`, "PLUGIN_ERROR", { originalError, pluginName });
+    this.name = "PluginError";
+    this.pluginName = pluginName;
+    if (originalError) {
+      this.cause = originalError;
+    }
+  }
+}
+
+class PluginManager {
+  logger;
+  plugins = /* @__PURE__ */ new Map();
+  initialized = false;
+  cachedDependencyOrder = void 0;
+  constructor(logger) {
+    this.logger = logger;
+  }
+  /**
+   * Checks if any plugins are registered.
+   * @returns True if at least one plugin is registered
+   */
+  hasPlugins() {
+    return this.plugins.size > 0;
+  }
+  /**
+   * Registers a plugin.
+   * @param plugin The plugin to register
+   * @throws {Error} If plugin name is already registered or dependencies are invalid
+   */
+  register(plugin) {
+    if (this.initialized) {
+      throw new Error(`Cannot register plugin "${plugin.name}" after initialization`);
+    }
+    if (this.plugins.has(plugin.name)) {
+      throw new Error(`Plugin "${plugin.name}" is already registered`);
+    }
+    const env = getEnv();
+    if (env.CEREBRO_OUTPUT_LEVEL === String(VERBOSITY_DEBUG)) {
+      this.logger.debug(`registering plugin: ${plugin.name}`);
+    }
+    this.plugins.set(plugin.name, plugin);
+    this.cachedDependencyOrder = void 0;
+  }
+  /**
+   * Initializes all registered plugins.
+   * @param context The plugin context for initialization
+   */
+  // eslint-disable-next-line sonarjs/cognitive-complexity
+  async init(context) {
+    if (this.initialized) {
+      throw new Error("PluginManager already initialized");
+    }
+    if (this.plugins.size === 0) {
+      this.logger.debug("no plugins registered, skipping initialization");
+      this.initialized = true;
+      return;
+    }
+    this.validateDependencies();
+    const orderedPlugins = this.getDependencyOrder();
+    this.logger.debug(`initializing ${String(orderedPlugins.length)} plugin(s)...`);
+    for (const plugin of orderedPlugins) {
+      if (typeof plugin.init === "function") {
+        this.logger.debug(`initializing plugin: ${plugin.name}`);
+        try {
+          await plugin.init(context);
+        } catch (error) {
+          const pluginError = new PluginError(
+            plugin.name,
+            `Failed to initialize: ${error instanceof Error ? error.message : String(error)}`,
+            error instanceof Error ? error : void 0
+          );
+          this.logger.error(pluginError.message);
+          throw pluginError;
+        }
+      }
+    }
+    this.initialized = true;
+  }
+  /**
+   * 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)
+   */
+  async executeLifecycle(hook, toolbox, result) {
+    if (!this.initialized) {
+      throw new Error("PluginManager not initialized");
+    }
+    if (this.plugins.size === 0) {
+      return;
+    }
+    const orderedPlugins = this.getDependencyOrder();
+    for (const plugin of orderedPlugins) {
+      const hookFunction = plugin[hook];
+      if (typeof hookFunction === "function") {
+        this.logger.debug(`executing ${hook} hook for plugin: ${plugin.name}`);
+        try {
+          await (hook === "afterCommand" ? hookFunction(toolbox, result) : hookFunction(toolbox));
+        } catch (error) {
+          this.logger.error(`Error in ${hook} hook for plugin "${plugin.name}":`, error);
+          throw error;
+        }
+      }
+    }
+  }
+  /**
+   * Executes error handlers for all plugins.
+   * @param error The error that occurred
+   * @param toolbox The command toolbox
+   */
+  async executeErrorHandlers(error, toolbox) {
+    if (!this.initialized) {
+      return;
+    }
+    if (this.plugins.size === 0) {
+      return;
+    }
+    const orderedPlugins = this.getDependencyOrder();
+    for (const plugin of orderedPlugins) {
+      if (typeof plugin.onError === "function") {
+        this.logger.debug(`executing error handler for plugin: ${plugin.name}`);
+        try {
+          await plugin.onError(error, toolbox);
+        } catch (handlerError) {
+          this.logger.error(`Error in error handler for plugin "${plugin.name}":`, handlerError);
+        }
+      }
+    }
+  }
+  /**
+   * Gets all registered plugins in dependency order.
+   * @returns Array of plugins sorted by dependencies
+   */
+  getDependencyOrder() {
+    if (this.cachedDependencyOrder !== void 0) {
+      return this.cachedDependencyOrder;
+    }
+    const ordered = [];
+    const visited = /* @__PURE__ */ new Set();
+    const visiting = /* @__PURE__ */ new Set();
+    const visit = (pluginName) => {
+      if (visited.has(pluginName)) {
+        return;
+      }
+      if (visiting.has(pluginName)) {
+        throw new Error(`Circular dependency detected involving plugin "${pluginName}"`);
+      }
+      const plugin = this.plugins.get(pluginName);
+      if (!plugin) {
+        throw new Error(`Plugin "${pluginName}" not found`);
+      }
+      visiting.add(pluginName);
+      if (plugin.dependencies) {
+        for (const dependency of plugin.dependencies) {
+          visit(dependency);
+        }
+      }
+      visiting.delete(pluginName);
+      visited.add(pluginName);
+      ordered.push(plugin);
+    };
+    for (const pluginName of this.plugins.keys()) {
+      visit(pluginName);
+    }
+    this.cachedDependencyOrder = ordered;
+    return ordered;
+  }
+  /**
+   * Validates that all plugin dependencies exist.
+   * @throws {Error} If any dependencies are missing
+   */
+  validateDependencies() {
+    for (const plugin of this.plugins.values()) {
+      if (plugin.dependencies) {
+        for (const dependency of plugin.dependencies) {
+          if (!this.plugins.has(dependency)) {
+            throw new Error(`Plugin "${plugin.name}" depends on "${dependency}" which is not registered`);
+          }
+        }
+      }
+    }
+  }
+}
+
+const optionIsBoolean = (option) => option.type?.name === "Boolean";
+
+const getTypeLabel = (definition) => {
+  let typeLabel = definition.type ? definition.type.name.toLowerCase() : "string";
+  const multiple = definition.multiple ?? definition.lazyMultiple ? "[]" : "";
+  if (typeLabel) {
+    typeLabel = typeLabel === "boolean" ? "" : `{underline ${typeLabel}${multiple}}`;
+  }
+  return typeLabel;
+};
+const mapOptionTypeLabel = (definition) => {
+  if (optionIsBoolean(definition)) {
+    return definition;
+  }
+  definition.typeLabel = definition.typeLabel ?? getTypeLabel(definition);
+  if (definition.defaultOption) {
+    definition.typeLabel = `${definition.typeLabel} (D)`;
+  }
+  if (definition.required) {
+    definition.typeLabel = `${definition.typeLabel} (R)`;
+  }
+  return definition;
+};
+
+const isShort = new RegExp(/^-([^\d-])$/);
+const isLong = new RegExp(/^--(\S+)/);
+const isCombined = new RegExp(/^-([^\d-]{2,})$/);
+const isOption$1 = (argument) => isShort.test(argument) || isLong.test(argument) || isCombined.test(argument);
+const commandLineCommands = (commands, argv) => {
+  const command = argv[0] && isOption$1(argv[0]) || argv.length === 0 ? null : argv.shift() ?? null;
+  if (!commands.includes(command)) {
+    const error = new Error(`Command not recognised: ${String(command)}`);
+    error.command = command;
+    error.name = "INVALID_COMMAND";
+    throw error;
+  }
+  return { argv, command };
+};
+
+class VisulimaError extends Error {
+  loc;
+  title;
+  /**
+   * A message that explains to the user how they can fix the error.
+   */
+  hint;
+  type = "VisulimaError";
+  constructor({ cause, hint, location, message, name, stack, title }) {
+    super(message, {
+      cause
+    });
+    this.title = title;
+    this.name = name;
+    this.stack = stack ?? this.stack;
+    this.loc = location;
+    this.hint = hint;
+  }
+  setLocation(location) {
+    this.loc = location;
+  }
+  setName(name) {
+    this.name = name;
+  }
+  setMessage(message) {
+    this.message = message;
+  }
+  setHint(hint) {
+    this.hint = hint;
+  }
+}
+
+class AlreadySetError extends VisulimaError {
+  optionName;
+  /**
+   * Creates a new AlreadySetError instance.
+   * @param optionName The name of the option that was already set
+   */
+  constructor(optionName) {
+    super({
+      cause: void 0,
+      hint: `Remove the duplicate option '${optionName}' from your command line arguments.`,
+      location: void 0,
+      message: `Option '${optionName}' is already set`,
+      name: "ALREADY_SET",
+      stack: void 0,
+      title: "Option Already Set"
+    });
+    this.optionName = optionName;
+    Object.setPrototypeOf(this, AlreadySetError.prototype);
+  }
+}
+
+class UnknownOptionError extends VisulimaError {
+  optionName;
+  /**
+   * Creates a new UnknownOptionError instance.
+   * @param optionName
+   */
+  constructor(optionName) {
+    super({
+      cause: void 0,
+      hint: `Check your option definitions or remove the unknown option '${optionName}' from your command line arguments.`,
+      location: void 0,
+      message: `Unknown option: --${optionName}`,
+      name: "UNKNOWN_OPTION",
+      stack: void 0,
+      title: "Unknown Option"
+    });
+    this.optionName = `--${optionName}`;
+    Object.setPrototypeOf(this, UnknownOptionError.prototype);
+  }
+}
+
+class UnknownValueError extends VisulimaError {
+  value;
+  /**
+   * Creates a new UnknownValueError instance.
+   * @param value The unknown value encountered
+   */
+  constructor(value) {
+    super({
+      hint: "Use a defined option or add a defaultOption to capture this value.",
+      message: `Unknown value: ${value}`,
+      name: "UNKNOWN_VALUE",
+      title: "Unknown Value"
+    });
+    this.value = value;
+    Object.setPrototypeOf(this, UnknownValueError.prototype);
+  }
+}
+
+class InvalidDefinitionsError extends VisulimaError {
+  /**
+   * Creates a new InvalidDefinitionsError instance.
+   * @param message The error message describing the invalid definition
+   * @param hint Optional hint for resolving the error
+   */
+  constructor(message, hint) {
+    super({
+      cause: void 0,
+      hint,
+      location: void 0,
+      message,
+      name: "INVALID_DEFINITIONS",
+      stack: void 0,
+      title: "Invalid Option Definition"
+    });
+    Object.setPrototypeOf(this, InvalidDefinitionsError.prototype);
+  }
+}
+
+const isBooleanType$2 = (type) => type === Boolean || typeof type === "function" && type.name.startsWith("Boolean");
+const isNumberType = (type) => type === Number || typeof type === "function" && type.name === "Number";
+const isStringType = (type) => type === String || typeof type === "function" && type.name === "String";
+const convertValue = (value, type) => {
+  if (Array.isArray(value)) {
+    if (isBooleanType$2(type)) {
+      return value.map(Boolean);
+    }
+    if (isNumberType(type)) {
+      return value.map(Number);
+    }
+    if (isStringType(type)) {
+      return value.map(String);
+    }
+    return value.map((item) => type(String(item)));
+  }
+  if (value === null) {
+    return null;
+  }
+  if (isBooleanType$2(type)) {
+    return Boolean(value);
+  }
+  if (isNumberType(type)) {
+    return Number(value);
+  }
+  if (isStringType(type)) {
+    return typeof value === "string" ? value : String(value);
+  }
+  return type(typeof value === "string" ? value : String(value));
+};
+const debug = (enable, message, namespace, ...args) => {
+  if (enable) {
+    console.debug(`[command-line-args:${namespace}] ${message}`, ...args);
+  }
+};
+const CAMEL_CASE_PATTERN = /-([a-z])/g;
+const NUMERIC_PATTERN = /^\d+$/;
+const isBooleanType$1 = (type) => type === Boolean || typeof type === "function" && type.name.startsWith("Boolean");
+const isSpecialKey = (key) => key.codePointAt(0) === 95;
+const appendToArrayMultiple = (existingValue, newValues) => {
+  if (Array.isArray(existingValue)) {
+    return [...existingValue, ...newValues];
+  }
+  return [existingValue, ...newValues];
+};
+const isUnsafeKey = (key) => key === "__proto__" || key === "constructor" || key === "prototype";
+const createOrAppendArray = (object, key, value, isArray = false) => {
+  if (object[key] === void 0) {
+    object[key] = isArray ? [value] : value;
+  } else if (isArray && Array.isArray(object[key])) {
+    object[key].push(value);
+  } else {
+    object[key] = [object[key], value];
+  }
+};
+const getDefinition = (name, definitionMap, aliasMap, caseInsensitiveNameMap, caseInsensitiveAliasMap) => {
+  let definition = definitionMap.get(name) ?? aliasMap.get(name);
+  if (!definition && caseInsensitiveNameMap) {
+    const lowercasedKey = name.toLowerCase();
+    definition = caseInsensitiveNameMap.get(lowercasedKey) ?? caseInsensitiveAliasMap?.get(lowercasedKey);
+  }
+  return definition;
+};
+const resolveArgs = (tokens, definitions, options, argv) => {
+  const debugEnabled = options.debug ?? false;
+  debug(debugEnabled, `resolveArgs called with options:`, "resolver", {
+    partial: options.partial,
+    stopAtFirstUnknown: options.stopAtFirstUnknown
+  });
+  debug(debugEnabled, "Starting argument resolution", "resolver");
+  debug(debugEnabled, "Tokens:", "resolver", tokens);
+  debug(debugEnabled, "Definitions:", "resolver", definitions);
+  debug(debugEnabled, "Processing tokens...", "resolver");
+  const definitionMap = /* @__PURE__ */ new Map();
+  const aliasMap = /* @__PURE__ */ new Map();
+  const caseInsensitiveNameMap = options.caseInsensitive ? /* @__PURE__ */ new Map() : void 0;
+  const caseInsensitiveAliasMap = options.caseInsensitive ? /* @__PURE__ */ new Map() : void 0;
+  const camelCaseMap = options.camelCase ? /* @__PURE__ */ new Map() : void 0;
+  const camelCaseReverseMap = options.camelCase ? /* @__PURE__ */ new Map() : void 0;
+  for (const definition of definitions) {
+    definitionMap.set(definition.name, definition);
+    if (definition.alias) {
+      aliasMap.set(definition.alias, definition);
+    }
+    if (options.caseInsensitive && caseInsensitiveNameMap) {
+      caseInsensitiveNameMap.set(definition.name.toLowerCase(), definition);
+      if (definition.alias && caseInsensitiveAliasMap) {
+        caseInsensitiveAliasMap.set(definition.alias.toLowerCase(), definition);
+      }
+    }
+    if (options.camelCase && camelCaseMap && camelCaseReverseMap) {
+      const camelCase = definition.name.replaceAll(CAMEL_CASE_PATTERN, (_, letter) => letter.toUpperCase());
+      camelCaseMap.set(definition.name, camelCase);
+      camelCaseReverseMap.set(camelCase, definition.name);
+    }
+  }
+  const output = {};
+  const values = {};
+  const unknownArgs = [];
+  const consumedPositionalIndices = /* @__PURE__ */ new Set();
+  let stoppedByTerminator = false;
+  const defaultOptionDefinition = definitions.find((d) => d.defaultOption);
+  const hasGroups = definitions.some((d) => d.group);
+  const hasNumberType = definitions.some((d) => d.type === Number);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.kind === "option-terminator") {
+      output._unknown = argv.slice(token.index);
+      stoppedByTerminator = true;
+      break;
+    }
+    if (token.kind === "option" && token.name) {
+      let definition = getDefinition(token.name, definitionMap, aliasMap, caseInsensitiveNameMap, caseInsensitiveAliasMap);
+      if (!definition && token.value === void 0 && hasNumberType && NUMERIC_PATTERN.test(token.name)) {
+        const numberDefinition = definitions.find((anyDefinition) => anyDefinition.type === Number);
+        if (numberDefinition) {
+          definition = numberDefinition;
+          token.value = token.name;
+          token.name = numberDefinition.name;
+        }
+      }
+      const optionName = definition ? definition.name : token.name;
+      const isMultiple = definition?.multiple;
+      const isLazyMultiple = definition?.lazyMultiple;
+      if (values[optionName] !== void 0 && !isMultiple && !isLazyMultiple && !options.partial) {
+        throw new AlreadySetError(optionName);
+      }
+      if (!definition && options.partial) {
+        const rawArgument = token.rawName ?? `--${token.name}${token.value !== void 0 && token.inlineValue ? `=${token.value}` : ""}`;
+        unknownArgs.push({ index: token.index, value: rawArgument });
+        continue;
+      }
+      if (!definition && options.stopAtFirstUnknown) {
+        output._unknown = argv.slice(token.index);
+        break;
+      }
+      if (!definition && !options.partial) {
+        throw new UnknownOptionError(token.name);
+      }
+      if (token.value === void 0) {
+        const nextToken = tokens[i + 1];
+        const isValueOnlyOptionToken = nextToken?.kind === "option" && !("name" in nextToken) && nextToken.value !== void 0;
+        const shouldConsumeValue = nextToken && definition && !(definition.type && isBooleanType$1(definition.type)) && (nextToken.kind === "positional" || isValueOnlyOptionToken);
+        const isDefaultOptionNonMultiple = definition && definition.defaultOption && !definition.multiple && !definition.lazyMultiple;
+        if (shouldConsumeValue && (!definition?.defaultOption || isDefaultOptionNonMultiple)) {
+          if (isMultiple) {
+            let currentIndex = i + 1;
+            const collectedValues = [];
+            while (currentIndex < tokens.length && (tokens[currentIndex].kind === "positional" || tokens[currentIndex].kind === "option" && !("name" in tokens[currentIndex]) && tokens[currentIndex].value !== void 0)) {
+              collectedValues.push(tokens[currentIndex].value);
+              consumedPositionalIndices.add(tokens[currentIndex].index);
+              currentIndex++;
+            }
+            values[optionName] = values[optionName] === void 0 ? collectedValues : appendToArrayMultiple(values[optionName], collectedValues);
+            i = currentIndex - 1;
+          } else if (isLazyMultiple) {
+            createOrAppendArray(values, optionName, nextToken.value, true);
+            consumedPositionalIndices.add(nextToken.index);
+            i++;
+          } else {
+            values[optionName] = nextToken.value;
+            consumedPositionalIndices.add(nextToken.index);
+            i++;
+          }
+        } else if (definition?.type && isBooleanType$1(definition.type)) {
+          createOrAppendArray(values, optionName, true, isMultiple);
+        } else {
+          values[optionName] = isMultiple ? [] : null;
+        }
+      } else {
+        let { value } = token;
+        if (definition?.type && isBooleanType$1(definition.type)) {
+          switch (value) {
+            case "": {
+              if (options.partial) {
+                values._unknown ??= [];
+                values._unknown.push(`${token.rawName ?? `--${token.name}`}${token.value ? `=${token.value}` : ""}`);
+                value = true;
+              } else {
+                throw new UnknownOptionError(token.name);
+              }
+              break;
+            }
+            case "false": {
+              value = false;
+              break;
+            }
+            case "true": {
+              value = true;
+              break;
+            }
+            default: {
+              value = true;
+            }
+          }
+        }
+        const collectedValues = [value];
+        if (isMultiple) {
+          let currentIndex = i + 1;
+          while (currentIndex < tokens.length && tokens[currentIndex].kind === "positional") {
+            collectedValues.push(tokens[currentIndex].value);
+            consumedPositionalIndices.add(tokens[currentIndex].index);
+            currentIndex++;
+          }
+          i = currentIndex - 1;
+        }
+        if (values[optionName] === void 0) {
+          values[optionName] = isMultiple || isLazyMultiple ? collectedValues : value;
+        } else if (isMultiple || isLazyMultiple) {
+          values[optionName] = appendToArrayMultiple(values[optionName], collectedValues);
+        } else {
+          values[optionName] = value;
+        }
+      }
+    } else if (token.kind === "positional" && options.stopAtFirstUnknown && !consumedPositionalIndices.has(token.index) && !defaultOptionDefinition) {
+      debug(debugEnabled, `Found unconsumed positional token at index ${String(token.index)}, stopping processing`, "resolver");
+      output._unknown = argv.slice(token.index);
+      break;
+    }
+  }
+  for (const [key, value] of Object.entries(values)) {
+    const definition = definitionMap.get(key);
+    if (definition && (definition.multiple || definition.lazyMultiple) && !Array.isArray(value)) {
+      values[key] = [value];
+    }
+  }
+  let stopAtUnknownArgvIndex = Number.POSITIVE_INFINITY;
+  if (options.stopAtFirstUnknown && !stoppedByTerminator) {
+    for (const token of tokens) {
+      if (token.kind === "option" && !definitionMap.has(token.name ?? "") && !aliasMap.has(token.name ?? "") && (!options.caseInsensitive || !caseInsensitiveNameMap?.has(token.name?.toLowerCase() ?? "") && !caseInsensitiveAliasMap?.has(token.name?.toLowerCase() ?? ""))) {
+        stopAtUnknownArgvIndex = token.index;
+        break;
+      }
+    }
+  }
+  if (defaultOptionDefinition) {
+    const positionalValues = [];
+    const positionalTokens = [];
+    for (const token of tokens) {
+      if (token.kind === "positional" && !consumedPositionalIndices.has(token.index) && token.index < stopAtUnknownArgvIndex) {
+        positionalValues.push(token.value);
+        positionalTokens.push(token);
+      }
+    }
+    if (positionalValues.length > 0) {
+      const existingValue = values[defaultOptionDefinition.name];
+      const isMultiple = defaultOptionDefinition.multiple ?? defaultOptionDefinition.lazyMultiple;
+      if (existingValue === void 0) {
+        if (isMultiple) {
+          positionalTokens.forEach((token) => consumedPositionalIndices.add(token.index));
+          values[defaultOptionDefinition.name] = positionalValues;
+        } else {
+          consumedPositionalIndices.add(positionalTokens[0].index);
+          values[defaultOptionDefinition.name] = positionalValues[0];
+        }
+      } else if (isMultiple) {
+        positionalTokens.forEach((token) => consumedPositionalIndices.add(token.index));
+        values[defaultOptionDefinition.name] = Array.isArray(existingValue) ? [...positionalValues, ...existingValue] : [...positionalValues, existingValue];
+      }
+    }
+  }
+  if (!options.partial) {
+    for (const token of tokens) {
+      if (token.kind === "positional" && !consumedPositionalIndices.has(token.index)) {
+        throw new UnknownValueError(argv[token.index]);
+      }
+    }
+  }
+  if (options.partial && !options.stopAtFirstUnknown) {
+    const allUnknownItems = [...unknownArgs];
+    if (values._unknown) {
+      const valueUnknownMap = /* @__PURE__ */ new Map();
+      for (const [i, element] of argv.entries()) {
+        valueUnknownMap.set(element, i);
+      }
+      for (const argument of values._unknown) {
+        const index = valueUnknownMap.get(argument);
+        if (index !== void 0) {
+          allUnknownItems.push({ index, value: argument });
+        }
+      }
+    }
+    for (const token of tokens) {
+      if (token.kind === "positional" && !consumedPositionalIndices.has(token.index)) {
+        allUnknownItems.push({ index: token.index, value: argv[token.index] });
+      }
+    }
+    if (allUnknownItems.length > 0) {
+      allUnknownItems.sort((a, b) => a.index - b.index);
+      output._unknown = allUnknownItems.map((item) => item.value);
+    }
+  }
+  if (options.stopAtFirstUnknown && !stoppedByTerminator) {
+    const firstUnknownOptionTokenIndex = tokens.findIndex(
+      (token) => token.kind === "option" && !definitionMap.has(token.name ?? "") && !aliasMap.has(token.name ?? "") && (!options.caseInsensitive || !caseInsensitiveNameMap?.has(token.name?.toLowerCase() ?? "") && !caseInsensitiveAliasMap?.has(token.name?.toLowerCase() ?? ""))
+    );
+    const firstUnconsumedPositionalTokenIndex = tokens.findIndex((token) => token.kind === "positional" && !consumedPositionalIndices.has(token.index));
+    let firstTokenIndex = -1;
+    if (firstUnknownOptionTokenIndex !== -1 && firstUnconsumedPositionalTokenIndex !== -1) {
+      firstTokenIndex = Math.min(firstUnknownOptionTokenIndex, firstUnconsumedPositionalTokenIndex);
+    } else if (firstUnknownOptionTokenIndex !== -1) {
+      firstTokenIndex = firstUnknownOptionTokenIndex;
+    } else if (firstUnconsumedPositionalTokenIndex !== -1) {
+      firstTokenIndex = firstUnconsumedPositionalTokenIndex;
+    }
+    if (firstTokenIndex >= 0) {
+      const argvIndex = tokens[firstTokenIndex].index;
+      output._unknown = argv.slice(argvIndex);
+    }
+  } else if (unknownArgs.length > 0 && !options.partial) {
+    output._unknown = unknownArgs.map((item) => item.value);
+  }
+  for (const [key, value] of Object.entries(values)) {
+    const finalKey = options.camelCase ? camelCaseMap?.get(key) ?? key : key;
+    const definition = definitionMap.get(key);
+    output[finalKey] = definition?.type ? convertValue(value, definition.type) : value === void 0 ? null : value;
+  }
+  for (const definition of definitions) {
+    const key = options.camelCase ? camelCaseMap?.get(definition.name) ?? definition.name : definition.name;
+    if (!(key in output) && definition.defaultValue !== void 0) {
+      const isMultipleDefinition = definition.multiple ?? definition.lazyMultiple;
+      if (isMultipleDefinition) {
+        output[key] = Array.isArray(definition.defaultValue) ? [...definition.defaultValue] : [definition.defaultValue];
+      } else {
+        output[key] = definition.defaultValue;
+      }
+    }
+  }
+  if (hasGroups) {
+    const groups = {};
+    const allOptions = {};
+    const ungroupedOptions = {};
+    for (const definition of definitions) {
+      if (definition.group) {
+        const groupArray = Array.isArray(definition.group) ? definition.group : [definition.group];
+        for (const group of groupArray) {
+          if (isUnsafeKey(group)) {
+            continue;
+          }
+          groups[group] ??= {};
+        }
+      }
+    }
+    for (const key of Object.keys(output)) {
+      if (!isSpecialKey(key)) {
+        allOptions[key] = output[key];
+        let originalKey = key;
+        if (options.camelCase) {
+          originalKey = camelCaseReverseMap?.get(key) ?? key;
+        }
+        const definition = definitionMap.get(originalKey);
+        if (definition?.group) {
+          const groupArray = Array.isArray(definition.group) ? definition.group : [definition.group];
+          for (const group of groupArray) {
+            if (isUnsafeKey(group)) {
+              continue;
+            }
+            if (groups[group]) {
+              groups[group][key] = output[key];
+            }
+          }
+        } else {
+          ungroupedOptions[key] = output[key];
+        }
+      }
+    }
+    const groupedOutput = { _all: allOptions };
+    for (const [group, groupOptions] of Object.entries(groups)) {
+      groupedOutput[group] = groupOptions;
+    }
+    if (Object.keys(ungroupedOptions).length > 0) {
+      groupedOutput._none = ungroupedOptions;
+    }
+    if (output._unknown) {
+      groupedOutput._unknown = output._unknown;
+    }
+    Object.keys(output).forEach((key) => delete output[key]);
+    Object.assign(output, groupedOutput);
+  }
+  debug(debugEnabled, "Final parsed result:", "resolver", output);
+  return output;
+};
+const HYPHEN_CHAR = "-";
+const HYPHEN_CODE = HYPHEN_CHAR.codePointAt(0);
+const EQUAL_CHAR = "=";
+const EQUAL_CODE = EQUAL_CHAR.codePointAt(0);
+const TERMINATOR = "--";
+const SHORT_OPTION_PREFIX = HYPHEN_CHAR;
+const LONG_OPTION_PREFIX = "--";
+const hasLongOptionPrefix = (argument) => argument.length > 2 && argument.startsWith(LONG_OPTION_PREFIX);
+const isLongOption = (argument) => hasLongOptionPrefix(argument) && !argument.includes(EQUAL_CHAR, 3);
+const isLongOptionAndValue = (argument) => hasLongOptionPrefix(argument) && argument.includes(EQUAL_CHAR, 3);
+const hasOptionValue = (value) => value !== void 0 && value.length > 0 && value.codePointAt(0) !== HYPHEN_CODE;
+const isShortOption = (argument) => {
+  if (argument.length !== 2 || argument.codePointAt(0) !== HYPHEN_CODE || argument.codePointAt(1) === HYPHEN_CODE) {
+    return false;
+  }
+  const secondCharCode = argument.codePointAt(1);
+  return secondCharCode !== void 0 && (secondCharCode < 48 || secondCharCode > 57);
+};
+const isShortOptionGroup = (argument) => {
+  if (argument.length <= 2) {
+    return false;
+  }
+  if (argument.codePointAt(0) !== HYPHEN_CODE) {
+    return false;
+  }
+  if (argument.codePointAt(1) === HYPHEN_CODE) {
+    return false;
+  }
+  return true;
+};
+const parseArgsTokens = (args) => {
+  const tokens = [];
+  const remainings = [...args];
+  let index = -1;
+  let groupCount = 0;
+  while (remainings.length > 0) {
+    const argument = remainings.shift();
+    if (argument === void 0) {
+      break;
+    }
+    const nextArgument = remainings[0];
+    if (groupCount > 0) {
+      groupCount--;
+    } else {
+      index++;
+    }
+    if (argument === TERMINATOR) {
+      tokens.push({
+        index,
+        kind: "option-terminator"
+      });
+      const mapped = remainings.map((argument_, index_) => {
+        return { index: index + index_ + 1, kind: "positional", value: argument_ };
+      });
+      tokens.push(...mapped);
+      index += remainings.length;
+      break;
+    }
+    if (isShortOption(argument)) {
+      const shortOption = argument.charAt(1);
+      let value;
+      if (groupCount) {
+        tokens.push({
+          index,
+          kind: "option",
+          name: shortOption,
+          rawName: argument,
+          value
+        });
+        if (groupCount === 1 && hasOptionValue(nextArgument)) {
+          value = remainings.shift();
+          tokens.push({
+            index,
+            kind: "option",
+            value
+          });
+        }
+      } else {
+        tokens.push({
+          index,
+          kind: "option",
+          name: shortOption,
+          rawName: argument,
+          value
+        });
+      }
+      if (value !== void 0) {
+        ++index;
+      }
+      continue;
+    }
+    if (isShortOptionGroup(argument) && !argument.includes(EQUAL_CHAR)) {
+      const expanded = [];
+      let shortValue = "";
+      let localHasShortValueSeparator = false;
+      for (let i = 1; i < argument.length; i++) {
+        const shortableOption = argument.charAt(i);
+        if (localHasShortValueSeparator) {
+          shortValue += shortableOption;
+        } else if (shortableOption.codePointAt(0) === EQUAL_CODE) {
+          localHasShortValueSeparator = true;
+        } else {
+          expanded.push(`${SHORT_OPTION_PREFIX}${shortableOption}`);
+        }
+      }
+      if (localHasShortValueSeparator) {
+        if (expanded.length > 0) {
+          const lastOption = expanded.pop();
+          expanded.push(`${lastOption}=${shortValue}`);
+        } else {
+          expanded.push(shortValue);
+        }
+      }
+      remainings.unshift(...expanded);
+      groupCount = expanded.length;
+      continue;
+    }
+    if (isLongOption(argument)) {
+      const longOption = argument.slice(2);
+      tokens.push({
+        index,
+        kind: "option",
+        name: longOption,
+        rawName: argument
+      });
+      continue;
+    }
+    if (isLongOptionAndValue(argument)) {
+      const equalIndex = argument.indexOf(EQUAL_CHAR);
+      const longOption = argument.slice(2, equalIndex);
+      const value = argument.slice(equalIndex + 1);
+      tokens.push({
+        index,
+        inlineValue: true,
+        kind: "option",
+        name: longOption,
+        rawName: argument,
+        value
+      });
+      continue;
+    }
+    if (argument.length > 2 && argument.codePointAt(0) === HYPHEN_CODE && argument.codePointAt(1) !== HYPHEN_CODE && argument.includes(EQUAL_CHAR)) {
+      const equalIndex = argument.indexOf(EQUAL_CHAR);
+      const shortOption = argument.charAt(1);
+      const value = argument.slice(equalIndex + 1);
+      tokens.push({
+        index,
+        inlineValue: true,
+        kind: "option",
+        name: shortOption,
+        rawName: argument,
+        value
+      });
+      continue;
+    }
+    tokens.push({
+      index,
+      kind: "positional",
+      value: argument
+    });
+  }
+  return tokens;
+};
+const DIGIT_PATTERN = /\d/;
+const isBooleanType = (type) => type !== void 0 && type !== null && (type === Boolean || typeof type === "function" && type.name.startsWith("Boolean"));
+const isValidCustomTypeFunction = (typeFunction) => (
+  // Accept any function as a valid type converter (Boolean, Number, String, or custom functions)
+  // We check only the type without invoking the function to avoid side effects
+  typeof typeFunction === "function"
+);
+const validateDefinitions = (definitions, caseInsensitive, debugOptions) => {
+  const debugEnabled = debugOptions?.debug ?? false;
+  debug(debugEnabled, "Validating definitions:", "validation", definitions, "caseInsensitive:", caseInsensitive);
+  const names = /* @__PURE__ */ new Set();
+  const aliases = /* @__PURE__ */ new Set();
+  const namesLower = /* @__PURE__ */ new Set();
+  const aliasesLower = /* @__PURE__ */ new Set();
+  let defaultOptionCount = 0;
+  for (const definition of definitions) {
+    debug(debugEnabled, "Checking definition:", "validation", definition);
+    if (!definition.name) {
+      debug(debugEnabled, "Validation failed: name is required", "validation");
+      throw new InvalidDefinitionsError("Invalid option definition: name is required");
+    }
+    if (typeof definition.name !== "string") {
+      throw new InvalidDefinitionsError("Invalid option definition: name must be a string");
+    }
+    if (definition.name.trim() === "") {
+      throw new InvalidDefinitionsError("Invalid option definition: name cannot be empty");
+    }
+    const nameLower = caseInsensitive ? definition.name.toLowerCase() : "";
+    if (names.has(definition.name) || caseInsensitive && namesLower.has(nameLower)) {
+      throw new InvalidDefinitionsError(`Invalid option definition: duplicate name '${definition.name}'`);
+    }
+    if (aliases.has(definition.name) || caseInsensitive && aliasesLower.has(nameLower)) {
+      throw new InvalidDefinitionsError(`Invalid option definition: name '${definition.name}' conflicts with an existing alias`);
+    }
+    names.add(definition.name);
+    if (caseInsensitive) {
+      namesLower.add(nameLower);
+    }
+    if (definition.alias !== void 0) {
+      if (typeof definition.alias !== "string") {
+        throw new InvalidDefinitionsError("Invalid option definition: alias must be a string");
+      }
+      if (definition.alias.length !== 1) {
+        throw new InvalidDefinitionsError("Invalid option definition: alias must be a single character");
+      }
+      if (DIGIT_PATTERN.test(definition.alias)) {
+        throw new InvalidDefinitionsError("Invalid option definition: alias cannot be numeric");
+      }
+      if (definition.alias === "-") {
+        throw new InvalidDefinitionsError('Invalid option definition: alias cannot be "-"');
+      }
+      const aliasLower = caseInsensitive ? definition.alias.toLowerCase() : "";
+      if (aliases.has(definition.alias) || caseInsensitive && aliasesLower.has(aliasLower)) {
+        throw new InvalidDefinitionsError(`Invalid option definition: duplicate alias '${definition.alias}'`);
+      }
+      if (names.has(definition.alias) || caseInsensitive && namesLower.has(aliasLower)) {
+        throw new InvalidDefinitionsError(`Invalid option definition: alias '${definition.alias}' conflicts with an existing option name`);
+      }
+      aliases.add(definition.alias);
+      if (caseInsensitive) {
+        aliasesLower.add(aliasLower);
+      }
+    }
+    if (definition.defaultOption) {
+      defaultOptionCount++;
+      if (definition.type !== void 0 && isBooleanType(definition.type)) {
+        throw new InvalidDefinitionsError("Invalid option definition: defaultOption cannot be Boolean type");
+      }
+    }
+    if (definition.type !== void 0) {
+      const isValidType = definition.type === Boolean || definition.type === Number || definition.type === String || typeof definition.type === "function" && isValidCustomTypeFunction(definition.type);
+      if (!isValidType) {
+        throw new InvalidDefinitionsError("Invalid option definition: invalid type");
+      }
+    }
+  }
+  if (defaultOptionCount > 1) {
+    debug(debugEnabled, "Validation failed: multiple defaultOptions not allowed", "validation");
+    throw new InvalidDefinitionsError("Invalid option definition: multiple defaultOptions not allowed");
+  }
+  debug(debugEnabled, "Validation completed successfully", "validation");
+};
+const commandLineArgs = (optionDefinitions, options = {}) => {
+  const debugEnabled = options.debug ?? false;
+  debug(debugEnabled, "Starting command-line-args parsing", "index");
+  debug(debugEnabled, "Options:", "index", options);
+  const effectiveOptions = { ...options };
+  if (effectiveOptions.stopAtFirstUnknown) {
+    effectiveOptions.partial = true;
+  }
+  const definitions = Array.isArray(optionDefinitions) ? optionDefinitions : [optionDefinitions];
+  debug(debugEnabled, "Normalized definitions:", "index", definitions);
+  validateDefinitions(definitions, effectiveOptions.caseInsensitive, debugEnabled ? effectiveOptions : void 0);
+  let { argv } = effectiveOptions;
+  if (!argv) {
+    argv = process.argv.slice(2);
+    if (process.execArgv.length > 0) {
+      const execArgs = new Set(process.execArgv);
+      argv = argv.filter((argument) => !execArgs.has(argument));
+    }
+  }
+  debug(debugEnabled, "Using argv:", "index", argv);
+  let normalizedArgv = argv;
+  if (effectiveOptions.caseInsensitive) {
+    normalizedArgv = argv.map((argument) => {
+      if (argument.startsWith("--")) {
+        const equalsIndex = argument.indexOf("=");
+        const optionName = equalsIndex === -1 ? argument.slice(2) : argument.slice(2, equalsIndex);
+        const normalizedName = optionName.toLowerCase();
+        return equalsIndex === -1 ? `--${normalizedName}` : `--${normalizedName}${argument.slice(equalsIndex)}`;
+      }
+      if (argument.startsWith("-") && !argument.startsWith("--") && argument.length > 1) {
+        const flagsAndRest = argument.slice(1).split("=", 2);
+        const flags = flagsAndRest[0];
+        const rest = flagsAndRest[1];
+        if (!flags) {
+          return argument;
+        }
+        const lowered = flags.toLowerCase();
+        return rest === void 0 ? `-${lowered}` : `-${lowered}=${rest}`;
+      }
+      return argument;
+    });
+  }
+  const tokens = parseArgsTokens(normalizedArgv.map(String));
+  debug(debugEnabled, "Tokenized arguments:", "index", tokens);
+  const result = resolveArgs(tokens, definitions, effectiveOptions, argv);
+  debug(debugEnabled, "Command-line-args parsing completed", "index");
+  return result;
+};
+
+class EmptyToolbox {
+  result;
+  argv;
+  options;
+  argument;
+  command;
+  commandName;
+  env;
+  logger;
+  runtime;
+  constructor(commandName, command) {
+    this.commandName = commandName;
+    this.command = command;
+  }
+}
+
+const argumentNameRegExp = /^-{1,2}(\w+)(=(.+))?$/;
+const getParameterOption = (argument, options, optionMapByName, optionMapByAlias) => {
+  const regExpResult = argumentNameRegExp.exec(argument);
+  if (regExpResult === null) {
+    return {};
+  }
+  const nameOrAlias = regExpResult[1];
+  if (!nameOrAlias) {
+    return {};
+  }
+  const option = optionMapByName && optionMapByAlias ? optionMapByName.get(nameOrAlias) ?? optionMapByAlias.get(nameOrAlias) : options.find((o) => o.name === nameOrAlias || o.alias === nameOrAlias);
+  if (option !== void 0) {
+    return { argName: option.name, argValue: regExpResult[3], option };
+  }
+  return {};
+};
+
+const convertType = (value, option) => {
+  if (option.type === void 0) {
+    return value;
+  }
+  if (option.type.name === "Boolean") {
+    if (value === "true" || value === "1") {
+      return option.type(true);
+    }
+    if (value === "false" || value === "0") {
+      return option.type(false);
+    }
+  }
+  return option.type(value);
+};
+const booleanValue$1 = /* @__PURE__ */ new Set(["0", "1", "false", "true"]);
+const getBooleanValues = (arguments_, options, optionMapByName, optionMapByAlias) => {
+  if (options.length === 0 || arguments_.length === 0) {
+    return {};
+  }
+  const getBooleanValue = (argumentsAndLastOption, argument) => {
+    const { argName, argValue, option } = getParameterOption(argument, options, optionMapByName, optionMapByAlias);
+    const { lastOption } = argumentsAndLastOption;
+    if (option && optionIsBoolean(option) && argValue && argName) {
+      argumentsAndLastOption.partial[argName] = convertType(
+        argValue,
+        option
+      );
+    } else if (argumentsAndLastOption.lastName && lastOption && optionIsBoolean(lastOption) && booleanValue$1.has(argument)) {
+      argumentsAndLastOption.partial[argumentsAndLastOption.lastName] = convertType(
+        argument,
+        lastOption
+      );
+    }
+    return { lastName: argName, lastOption: option, partial: argumentsAndLastOption.partial };
+  };
+  return arguments_.reduce(getBooleanValue, { partial: {} }).partial;
+};
+
+const booleanValue = /* @__PURE__ */ new Set(["0", "1", "false", "true"]);
+const removeBooleanValues = (arguments_, options, optionMapByName, optionMapByAlias) => {
+  if (options.length === 0 || arguments_.length === 0) {
+    return arguments_;
+  }
+  const removeBooleanArguments = (argumentsAndLastValue, argument) => {
+    const { argValue, option } = getParameterOption(argument, options, optionMapByName, optionMapByAlias);
+    const { lastOption } = argumentsAndLastValue;
+    if (lastOption && optionIsBoolean(lastOption) && booleanValue.has(argument)) {
+      const { args } = argumentsAndLastValue;
+      const result = args.slice(0, -1);
+      return { args: result };
+    }
+    if (option && optionIsBoolean(option) && argValue) {
+      return { args: argumentsAndLastValue.args };
+    }
+    const newArgs = [...argumentsAndLastValue.args, argument];
+    return { args: newArgs, lastOption: option };
+  };
+  return arguments_.reduce(removeBooleanArguments, { args: [] }).args;
+};
+
+const mergeArguments = (argumentLists) => {
+  const argumentsByName = /* @__PURE__ */ new Map();
+  for (const argument of argumentLists) {
+    const existing = argumentsByName.get(argument.name);
+    if (existing) {
+      argumentsByName.set(argument.name, { ...existing, ...argument });
+    } else {
+      argumentsByName.set(argument.name, argument);
+    }
+  }
+  return [...argumentsByName.values()];
+};
+
+const transformBooleanEnv = (value) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  const normalized = value.toLowerCase().trim();
+  return normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on";
+};
+const transformEnvValue = (envDefinition, envValue) => {
+  if (!envDefinition.type) {
+    return envValue;
+  }
+  if (envValue === void 0) {
+    return void 0;
+  }
+  const isBooleanType = envDefinition.type === Boolean || typeof envDefinition.type === "function" && envDefinition.type.name === "Boolean";
+  if (isBooleanType) {
+    return transformBooleanEnv(envValue);
+  }
+  const isNumberType = envDefinition.type === Number || typeof envDefinition.type === "function" && envDefinition.type.name === "Number";
+  if (isNumberType) {
+    const parsed = Number.parseFloat(envValue);
+    return Number.isNaN(parsed) ? void 0 : parsed;
+  }
+  const isStringType = envDefinition.type === String || typeof envDefinition.type === "function" && envDefinition.type.name === "String";
+  if (isStringType) {
+    return envValue;
+  }
+  return envDefinition.type(envValue);
+};
+const UNDERSCORE_CHAR_PATTERN = /_./g;
+const LEADING_UPPERCASE_PATTERN = /^[A-Z]/;
+const toCamelCase = (name) => name.toLowerCase().replaceAll(UNDERSCORE_CHAR_PATTERN, (match) => match[1]?.toUpperCase() ?? match).replace(LEADING_UPPERCASE_PATTERN, (char) => char.toLowerCase());
+const processEnvVariables = (envDefinitions) => {
+  if (!envDefinitions || envDefinitions.length === 0) {
+    return {};
+  }
+  const result = {};
+  const env = getEnv();
+  for (const envDefinition of envDefinitions) {
+    const envValue = env[envDefinition.name];
+    const transformedValue = transformEnvValue(envDefinition, envValue);
+    const finalValue = transformedValue === void 0 ? envDefinition.defaultValue : transformedValue;
+    const camelCaseName = toCamelCase(envDefinition.name);
+    result[camelCaseName] = finalValue;
+  }
+  return result;
+};
+
+const buildOptionMaps = (commandOptions) => {
+  const optionMapByName = /* @__PURE__ */ new Map();
+  const optionMapByAlias = /* @__PURE__ */ new Map();
+  for (const option of commandOptions) {
+    optionMapByName.set(option.name, option);
+    if (option.alias) {
+      const aliases = Array.isArray(option.alias) ? option.alias : [option.alias];
+      for (const alias of aliases) {
+        optionMapByAlias.set(alias, option);
+      }
+    }
+  }
+  return { optionMapByAlias, optionMapByName };
+};
+const prepareToolbox = (command, parsedArgs, booleanValues, extraOptions) => {
+  const toolbox = new EmptyToolbox(command.name, command);
+  const { _all, positionals } = parsedArgs;
+  const hasBooleanValues = Object.keys(booleanValues).length > 0;
+  const mergedAll = hasBooleanValues ? { ..._all, ...booleanValues } : _all;
+  if (POSITIONALS_KEY in mergedAll) {
+    delete mergedAll[POSITIONALS_KEY];
+  }
+  toolbox.argument = positionals?.[POSITIONALS_KEY] ?? [];
+  const hasExtraOptions = Object.keys(extraOptions).length > 0;
+  toolbox.options = hasExtraOptions ? { ...mergedAll, ...extraOptions } : mergedAll;
+  toolbox.env = processEnvVariables(command.env);
+  return toolbox;
+};
+const processCommandArgs = (command, commandArguments, defaultOptions) => {
+  const commandOptions = command.options ?? [];
+  const hasCommandOptions = commandOptions.length > 0;
+  let arguments_ = hasCommandOptions ? mergeArguments([...commandOptions, ...defaultOptions]) : mergeArguments(defaultOptions);
+  if (arguments_.length > 0) {
+    for (const argument of arguments_) {
+      if (argument.multiple && argument.lazyMultiple) {
+        throw new Error(`Argument "${argument.name}" cannot have both multiple and lazyMultiple options, please choose one.`);
+      }
+    }
+  }
+  if (command.argument) {
+    arguments_ = [
+      {
+        defaultOption: true,
+        description: command.argument.description,
+        group: "positionals",
+        multiple: true,
+        name: POSITIONALS_KEY,
+        type: command.argument.type,
+        typeLabel: command.argument.typeLabel
+      },
+      ...arguments_
+    ];
+  }
+  let argvForParsing;
+  let booleanValues;
+  if (hasCommandOptions) {
+    const { optionMapByAlias, optionMapByName } = buildOptionMaps(commandOptions);
+    argvForParsing = removeBooleanValues(commandArguments, commandOptions, optionMapByName, optionMapByAlias);
+    booleanValues = getBooleanValues(commandArguments, commandOptions, optionMapByName, optionMapByAlias);
+  } else {
+    argvForParsing = commandArguments;
+    booleanValues = {};
+  }
+  const parsedArgs = commandLineArgs(arguments_, {
+    argv: argvForParsing,
+    camelCase: true,
+    partial: true,
+    stopAtFirstUnknown: true
+  });
+  return { arguments_, booleanValues, parsedArgs };
+};
+const executeCommand = async (command, toolbox, _commandArgs) => command.execute(toolbox);
+
+class CommandValidationError extends CerebroError {
+  commandName;
+  missingOptions;
+  constructor(commandName, missingOptions) {
+    super(`Command "${commandName}" is missing required options: ${missingOptions.join(", ")}`, "COMMAND_VALIDATION_ERROR", {
+      commandName,
+      missingOptions
+    });
+    this.name = "CommandValidationError";
+    this.commandName = commandName;
+    this.missingOptions = missingOptions;
+    this.hint = `Provide the following required options: ${missingOptions.join(", ")}`;
+  }
+}
+
+const listMissingArguments = (commandLineConfig, parsedArguments, onlyRequired = false) => {
+  const missing = [];
+  for (const config of commandLineConfig) {
+    if (!onlyRequired && !config.required) {
+      continue;
+    }
+    if (parsedArguments[config.name] !== void 0) {
+      continue;
+    }
+    if (config.type?.name === "Boolean") {
+      parsedArguments[config.name] = false;
+      continue;
+    }
+    missing.push(config);
+  }
+  return missing;
+};
+
+const isSimilar = (string1, string2) => {
+  if (string2.includes(string1)) {
+    return true;
+  }
+  const lengthDiff = Math.abs(string1.length - string2.length);
+  if (lengthDiff > string1.length / 2) {
+    return false;
+  }
+  return distance(string1, string2) <= string1.length / 3;
+};
+const findAlternatives = (string, array) => {
+  const id = string.toLowerCase();
+  return array.filter((nextId) => isSimilar(nextId.toLowerCase(), id));
+};
+
+const validateUnknownOptions = (commandArguments, command) => {
+  const errors = [];
+  if (commandArguments._unknown) {
+    commandArguments._unknown.forEach((unknownOption) => {
+      const isOption = unknownOption.startsWith("--");
+      let error = `Found unknown ${isOption ? "option" : "argument"} "${unknownOption}"`;
+      if (isOption) {
+        const foundAlternatives = findAlternatives(
+          unknownOption.replace("--", ""),
+          (command.options ?? []).map((option) => option.name)
+        );
+        if (foundAlternatives.length > 0) {
+          const [first, ...rest] = foundAlternatives.map((alternative) => `--${alternative}`);
+          error += rest.length > 0 ? `, did you mean ${first ?? ""} or ${rest.join(", ")}?` : `, did you mean ${first ?? ""}?`;
+        }
+      }
+      errors.push(error);
+    });
+  }
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+};
+const validateRequiredOptions = (arguments_, commandArguments, command) => {
+  const requiredOptions = command.__requiredOptions__;
+  const missingOptions = requiredOptions ? listMissingArguments(requiredOptions, commandArguments, true) : listMissingArguments(arguments_, commandArguments, false);
+  if (missingOptions.length > 0) {
+    throw new CommandValidationError(
+      command.name,
+      missingOptions.map((argument) => argument.name)
+    );
+  }
+  if (commandArguments._unknown && commandArguments._unknown.length > 0 && !command.argument) {
+    validateUnknownOptions(commandArguments, command);
+  }
+};
+const validateConflictingOptions = (arguments_, commandArguments, command) => {
+  const conflicts = command.__conflictingOptions__ ?? arguments_.filter((argument) => argument.conflicts !== void 0);
+  if (conflicts.length > 0) {
+    const conflict = conflicts.find((argument) => {
+      if (Array.isArray(argument.conflicts)) {
+        return argument.conflicts.some((c) => commandArguments[c] !== void 0) && commandArguments[argument.name] !== void 0;
+      }
+      return commandArguments[argument.conflicts] !== void 0 && commandArguments[argument.name] !== void 0;
+    });
+    if (conflict) {
+      throw new ConflictingOptionsError(
+        conflict.name,
+        typeof conflict.conflicts === "string" ? conflict.conflicts : conflict.conflicts?.[0] ?? "unknown"
+      );
+    }
+  }
+};
+const validateDuplicateOptions = (command) => {
+  if (!Array.isArray(command.options)) {
+    return;
+  }
+  const byName = /* @__PURE__ */ new Map();
+  const byAlias = /* @__PURE__ */ new Map();
+  for (const opt of command.options) {
+    if (opt.name) {
+      const existing = byName.get(opt.name) ?? [];
+      existing.push(opt);
+      byName.set(opt.name, existing);
+    }
+    if (typeof opt.alias === "string" && opt.alias.length > 0) {
+      const existing = byAlias.get(opt.alias) ?? [];
+      existing.push(opt);
+      byAlias.set(opt.alias, existing);
+    } else if (Array.isArray(opt.alias)) {
+      for (const alias of opt.alias) {
+        if (alias.length > 0) {
+          const existing = byAlias.get(alias) ?? [];
+          existing.push(opt);
+          byAlias.set(alias, existing);
+        }
+      }
+    }
+  }
+  const errors = [];
+  for (const [name, group] of byName) {
+    if (group.length > 1) {
+      errors.push(`Duplicate option name "${name}" in command "${command.name}": ${JSON.stringify(group)}`);
+    }
+  }
+  for (const [alias, group] of byAlias) {
+    if (group.length > 1) {
+      errors.push(`Duplicate option alias "-${alias}" used by options ${group.map((o) => `"${o.name}"`).join(", ")} in command "${command.name}"`);
+    }
+  }
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+};
+
+const parseNestedCommand = (availableCommands, argv) => {
+  if (argv.length === 0) {
+    return { argv: [], commandPath: void 0 };
+  }
+  const pathKeyParts = [];
+  for (let depth = 1; depth <= argv.length; depth += 1) {
+    const argument = argv[depth - 1];
+    if (argument === void 0) {
+      break;
+    }
+    pathKeyParts.push(argument);
+    const pathKey = pathKeyParts.join(" ");
+    if (availableCommands.has(pathKey)) {
+      const remainingArgv = argv.slice(depth);
+      return { argv: remainingArgv, commandPath: [...pathKeyParts] };
+    }
+  }
+  return { argv, commandPath: void 0 };
+};
+const getCommandPathKey = (commandPath) => commandPath.join(" ");
+const getFullCommandPath = (commandName, commandPath) => {
+  if (commandPath && commandPath.length > 0) {
+    return [...commandPath, commandName];
+  }
+  return [commandName];
+};
+
+const r = String.raw;
+const e = r`\p{Emoji}(?:\p{EMod}|[\u{E0020}-\u{E007E}]+\u{E007F}|\uFE0F?\u20E3?)`;
+const emojiRegex = () => new RegExp(r`\p{RI}{2}|(?![#*\d](?!\uFE0F?\u20E3))${e}(?:\u200D${e})*`, "gu");
+Object.freeze(
+  /* @__PURE__ */ new Map([
+    [0, 0],
+    // Reset all
+    [1, 22],
+    // Bold → Not bold
+    [2, 22],
+    // Dim → Not bold
+    [3, 23],
+    // Italic → Not italic
+    [4, 24],
+    // Underline → Not underline
+    [7, 27],
+    // Inverse → Not inverse
+    [8, 28],
+    // Hidden → Not hidden
+    [9, 29],
+    // Strikethrough → Not strikethrough
+    [30, 39],
+    // Foreground colors → Default foreground
+    [31, 39],
+    [32, 39],
+    [33, 39],
+    [34, 39],
+    [35, 39],
+    [36, 39],
+    [37, 39],
+    [40, 49],
+    // Background colors → Default background
+    [41, 49],
+    [42, 49],
+    [43, 49],
+    [44, 49],
+    [45, 49],
+    [46, 49],
+    [47, 49],
+    [90, 39]
+    // Bright foreground → Default foreground
+  ])
+);
+const RE_EMOJI = emojiRegex();
+const RE_SEPARATORS = /[-_./\s]+/g;
+const RE_FAST_ANSI = /(\u001B\[[0-9;]*[a-z])/i;
+const RE_ARABIC = new RegExp("\\p{Script=Arabic}", "u");
+const RE_BENGALI = new RegExp("\\p{Script=Bengali}", "u");
+const RE_CYRILLIC = new RegExp("\\p{Script=Cyrillic}", "u");
+const RE_DEVANAGARI = new RegExp("\\p{Script=Devanagari}", "u");
+const RE_ETHIOPIC = new RegExp("\\p{Script=Ethiopic}", "u");
+const RE_GREEK = new RegExp("\\p{Script=Greek}", "u");
+const RE_GREEK_LATIN_SPLIT = new RegExp("\\p{Script=Greek}+|\\p{Script=Latin}+|[^\\p{Script=Greek}\\p{Script=Latin}]+", "gu");
+const RE_GUJARATI = new RegExp("\\p{Script=Gujarati}", "u");
+const RE_GURMUKHI = new RegExp("\\p{Script=Gurmukhi}", "u");
+const RE_HANGUL = new RegExp("\\p{Script=Hangul}", "u");
+const RE_HEBREW = new RegExp("\\p{Script=Hebrew}", "u");
+const RE_HIRAGANA = new RegExp("\\p{Script=Hiragana}", "u");
+const RE_KANJI = new RegExp("\\p{Script=Han}", "u");
+const RE_KANNADA = new RegExp("\\p{Script=Kannada}", "u");
+const RE_KATAKANA = new RegExp("\\p{Script=Katakana}", "u");
+const RE_KHMER = new RegExp("\\p{Script=Khmer}", "u");
+const RE_LAO = new RegExp("\\p{Script=Lao}", "u");
+const RE_LATIN = new RegExp("\\p{Script=Latin}", "u");
+const RE_MALAYALAM = new RegExp("\\p{Script=Malayalam}", "u");
+const RE_MYANMAR = new RegExp("\\p{Script=Myanmar}", "u");
+const RE_ORIYA = new RegExp("\\p{Script=Oriya}", "u");
+const RE_SINHALA = new RegExp("\\p{Script=Sinhala}", "u");
+const RE_TAMIL = new RegExp("\\p{Script=Tamil}", "u");
+const RE_TELUGU = new RegExp("\\p{Script=Telugu}", "u");
+const RE_THAI = new RegExp("\\p{Script=Thai}", "u");
+const RE_TIBETAN = new RegExp("\\p{Script=Tibetan}", "u");
+const RE_UZBEK_LATIN_MODIFIER = /[\u02BB\u02BC\u0027]/u;
+const stripEmoji = (stringValue) => stringValue.replace(RE_EMOJI, "");
+
+class LRUCache {
+  capacity;
+  cache;
+  keyOrder;
+  constructor(capacity) {
+    this.capacity = capacity;
+    this.cache = /* @__PURE__ */ new Map();
+    this.keyOrder = [];
+  }
+  get(key) {
+    if (!this.cache.has(key)) {
+      return void 0;
+    }
+    this.keyOrder = this.keyOrder.filter((k) => k !== key);
+    this.keyOrder.push(key);
+    return this.cache.get(key);
+  }
+  has(key) {
+    return this.cache.has(key);
+  }
+  set(key, value) {
+    if (this.cache.has(key)) {
+      this.keyOrder = this.keyOrder.filter((k) => k !== key);
+    } else if (this.cache.size >= this.capacity) {
+      const lruKey = this.keyOrder.shift();
+      if (lruKey !== void 0) {
+        this.cache.delete(lruKey);
+      }
+    }
+    this.cache.set(key, value);
+    this.keyOrder.push(key);
+  }
+  delete(key) {
+    this.cache.delete(key);
+    this.keyOrder = this.keyOrder.filter((k) => k !== key);
+  }
+  clear() {
+    this.cache.clear();
+    this.keyOrder = [];
+  }
+  size() {
+    return this.cache.size;
+  }
+}
+
+const lowerFirst = (value, options) => {
+  if (typeof value !== "string" || value === "") {
+    return "";
+  }
+  const firstChar = value[0].toLowerCase();
+  return firstChar + value.slice(1);
+};
+
+const {
+  stripVTControlCharacters
+} = __cjs_getBuiltinModule("node:util");
+const regexCache = new LRUCache(1e3);
+const RE_ESCAPE_SPECIAL = /[.*+?^${}()|[\]\\]/g;
+const getSeparatorsRegex = (separators) => {
+  const key = separators.join("");
+  if (regexCache.has(key)) {
+    return regexCache.get(key);
+  }
+  const pattern = separators.map((s) => s.replaceAll(RE_ESCAPE_SPECIAL, String.raw`\$&`)).join("|");
+  const regex = new RegExp(pattern, "g");
+  regexCache.set(key, regex);
+  return regex;
+};
+const splitByEmoji = (text) => {
+  const segments = [];
+  let lastIndex = 0;
+  let match;
+  RE_EMOJI.lastIndex = 0;
+  while ((match = RE_EMOJI.exec(text)) !== null) {
+    if (match.index > lastIndex) {
+      segments.push(text.slice(lastIndex, match.index));
+    }
+    segments.push(match[0]);
+    lastIndex = RE_EMOJI.lastIndex;
+  }
+  if (lastIndex < text.length) {
+    segments.push(text.slice(lastIndex));
+  }
+  return segments.filter(Boolean);
+};
+const RE_SLOVENIAN_SPECIAL = /[ČŠŽĐ]/i;
+const isUpperCode = new Uint8Array(128);
+const isLowerCode = new Uint8Array(128);
+const isDigitCode = new Uint8Array(128);
+for (let index = 0; index < 128; index++) {
+  isUpperCode[index] = index >= 65 && index <= 90 ? 1 : 0;
+  isLowerCode[index] = index >= 97 && index <= 122 ? 1 : 0;
+  isDigitCode[index] = index >= 48 && index <= 57 ? 1 : 0;
+}
+const isUpper = (code) => isUpperCode[code];
+const isLower = (code) => isLowerCode[code];
+const isDigit = (code) => isDigitCode[code];
+const handleScriptTransitions = (s, scriptDetectors, caseSensitive, locale, customSplitLogic) => {
+  if (s.length === 0) {
+    return [];
+  }
+  let hasDetectedScript = false;
+  const detectorValues = Object.values(scriptDetectors);
+  for (const detectorValue of detectorValues) {
+    if (detectorValue(s[0])) {
+      hasDetectedScript = true;
+      break;
+    }
+  }
+  if (!hasDetectedScript && !caseSensitive) {
+    return [s];
+  }
+  const chars = [...s];
+  const result = [];
+  let currentSegment = chars[0];
+  let previousType = "other";
+  const scriptEntries = Object.entries(scriptDetectors);
+  for (const scriptEntry of scriptEntries) {
+    const [type, detector] = scriptEntry;
+    if (detector(chars[0])) {
+      previousType = type;
+      break;
+    }
+  }
+  let previousIsUpper = caseSensitive && locale ? chars[0] === chars[0].toLocaleUpperCase(locale) : false;
+  for (let index = 1; index < chars.length; index++) {
+    const char = chars[index];
+    let currentType = "other";
+    for (const scriptEntry of scriptEntries) {
+      const [type, detector] = scriptEntry;
+      if (detector(char)) {
+        currentType = type;
+        break;
+      }
+    }
+    const isUpperCaseChar = caseSensitive && locale ? char === char.toLocaleUpperCase(locale) : false;
+    let shouldSplit = false;
+    if (customSplitLogic) {
+      shouldSplit = customSplitLogic(previousType, currentType, previousIsUpper, isUpperCaseChar, char, index, chars);
+    } else {
+      if (previousType !== currentType && previousType !== "other" && currentType !== "other") {
+        shouldSplit = true;
+      }
+      if (caseSensitive && currentType !== "other" && !previousIsUpper && isUpperCaseChar) {
+        shouldSplit = true;
+      }
+    }
+    if (shouldSplit) {
+      result.push(currentSegment);
+      currentSegment = char;
+    } else {
+      currentSegment += char;
+    }
+    previousType = currentType;
+    if (caseSensitive) {
+      previousIsUpper = isUpperCaseChar;
+    }
+  }
+  if (currentSegment && currentSegment.length > 0) {
+    result.push(currentSegment);
+  }
+  return result.length > 0 ? result : [s];
+};
+const detectAndProcessAcronym = (s, start, knownAcronyms, tokens) => {
+  if (knownAcronyms.size === 0) {
+    return start;
+  }
+  for (const acronym of knownAcronyms) {
+    if (s.startsWith(acronym, start)) {
+      tokens.push(acronym);
+      return start + acronym.length;
+    }
+  }
+  return start;
+};
+const splitCamelCaseFast = (s, knownAcronyms = /* @__PURE__ */ new Set()) => {
+  if (s.length === 0) {
+    return [];
+  }
+  if (s.toUpperCase() === s) {
+    return [s];
+  }
+  let start = 0;
+  const tokens = [];
+  const width = s.length;
+  for (let index = 1; index < width; index++) {
+    const newStart = detectAndProcessAcronym(s, start, knownAcronyms, tokens);
+    if (newStart !== start) {
+      start = newStart;
+      index = start - 1;
+      continue;
+    }
+    const previousCode = s.codePointAt(index - 1);
+    const currentCode = s.codePointAt(index);
+    const previousIsUpper = previousCode && previousCode < 128 && isUpper(previousCode);
+    const currentIsUpper = currentCode && currentCode < 128 && isUpper(currentCode);
+    const previousIsLower = previousCode && previousCode < 128 && isLower(previousCode);
+    const previousIsDigit = previousCode && previousCode < 128 && isDigit(previousCode);
+    const currentIsDigit = currentCode && currentCode < 128 && isDigit(currentCode);
+    if (previousIsLower && currentIsUpper) {
+      tokens.push(s.slice(start, index));
+      start = index;
+      continue;
+    }
+    if (previousIsDigit && !currentIsDigit || !previousIsDigit && currentIsDigit) {
+      tokens.push(s.slice(start, index));
+      start = index;
+      continue;
+    }
+    if (currentIsDigit && !previousIsDigit) {
+      let isNextUpper = false;
+      let isNextDigit = false;
+      if (index + 1 < width) {
+        const nextCode = s.codePointAt(index + 1);
+        isNextUpper = nextCode && nextCode < 128 && isUpper(nextCode);
+        isNextDigit = nextCode && nextCode < 128 && isDigit(nextCode);
+      }
+      if (!isNextDigit && isNextUpper) {
+        tokens.push(s.slice(start, index), s.slice(index, index + 1));
+        start = index + 1;
+        continue;
+      }
+    }
+    if (index + 1 < width) {
+      const nextCode = s.codePointAt(index + 1);
+      const nextIsLower = nextCode && nextCode < 128 && isLower(nextCode);
+      if (previousIsUpper && currentIsUpper && nextIsLower) {
+        const candidate = s.slice(start, index + 1);
+        if (!knownAcronyms.has(candidate)) {
+          tokens.push(s.slice(start, index));
+          start = index;
+        }
+      }
+    }
+  }
+  if (start < width) {
+    tokens.push(s.slice(start));
+  }
+  return tokens.filter((token) => token !== "");
+};
+const splitCamelCaseLocale = (s, locale, knownAcronyms) => {
+  if (s.length === 0) {
+    return [];
+  }
+  const isUpperCase = s === s.toLocaleUpperCase(locale);
+  if (locale.startsWith("de")) {
+    if (!isUpperCase && s.replaceAll("ß", "SS") === s.toLocaleUpperCase(locale)) {
+      return [s];
+    }
+    const chars2 = [...s];
+    const width_2 = chars2.length;
+    const result2 = [];
+    let currentSegment2 = chars2[0];
+    let previousIsUpper2 = chars2[0] === chars2[0].toLocaleUpperCase(locale);
+    let isInUpperSequence = previousIsUpper2;
+    let upperSequenceStart = previousIsUpper2 ? 0 : -1;
+    for (let index = 1; index < width_2; index++) {
+      const char = chars2[index];
+      const isUpperCaseChar = char === char.toLocaleUpperCase(locale);
+      if (isUpperCaseChar === previousIsUpper2) {
+        currentSegment2 += char;
+      } else if (isUpperCaseChar) {
+        if (currentSegment2 && currentSegment2.length > 0) {
+          result2.push(currentSegment2);
+          currentSegment2 = char;
+        }
+        isInUpperSequence = true;
+        upperSequenceStart = index;
+      } else {
+        if (isInUpperSequence && index - upperSequenceStart > 1) {
+          const lastUpperChar = chars2[index - 1];
+          const withoutLastUpper = currentSegment2.slice(0, -1);
+          if (withoutLastUpper && withoutLastUpper.length > 0) {
+            result2.push(withoutLastUpper);
+          }
+          currentSegment2 = lastUpperChar + char;
+        } else {
+          currentSegment2 += char;
+        }
+        isInUpperSequence = false;
+        upperSequenceStart = -1;
+      }
+      previousIsUpper2 = isUpperCaseChar;
+    }
+    if (currentSegment2 && currentSegment2.length > 0) {
+      result2.push(currentSegment2);
+    }
+    return result2;
+  }
+  if (locale.startsWith("uk") || locale.startsWith("ru") || locale.startsWith("bg") || locale.startsWith("sr") || locale.startsWith("mk") || locale.startsWith("be")) {
+    if (!RE_CYRILLIC.test(s) && !RE_LATIN.test(s)) {
+      return [s];
+    }
+    const chars2 = [...s];
+    const width_2 = chars2.length;
+    const result2 = [];
+    let currentSegment2 = chars2[0];
+    const firstChar = chars2[0];
+    let previousType;
+    if (RE_CYRILLIC.test(firstChar)) {
+      previousType = 1;
+    } else if (RE_LATIN.test(firstChar)) {
+      previousType = 2;
+    } else {
+      previousType = 0;
+    }
+    let previousIsUpper2 = firstChar === firstChar.toLocaleUpperCase(locale);
+    for (let index = 1; index < width_2; index++) {
+      const char = chars2[index];
+      let currentType;
+      if (RE_CYRILLIC.test(char)) {
+        currentType = 1;
+      } else if (RE_LATIN.test(char)) {
+        currentType = 2;
+      } else {
+        currentType = 0;
+      }
+      const isUpperCaseChar = char === char.toLocaleUpperCase(locale);
+      if (previousType !== currentType && (previousType === 1 || previousType === 2) && (currentType === 1 || currentType === 2) || currentType === previousType && !previousIsUpper2 && isUpperCaseChar) {
+        result2.push(currentSegment2);
+        currentSegment2 = char;
+      } else {
+        currentSegment2 += char;
+      }
+      previousType = currentType;
+      previousIsUpper2 = isUpperCaseChar;
+    }
+    if (currentSegment2 && currentSegment2.length > 0) {
+      result2.push(currentSegment2);
+    }
+    const finalResult = [];
+    for (let index = 0; index < result2.length; index++) {
+      if (index < result2.length - 1 && result2[index].length === 1 && RE_LATIN.test(result2[index]) && RE_CYRILLIC.test(result2[index + 1][0])) {
+        finalResult.push(result2[index] + result2[index + 1]);
+        index += 1;
+      } else {
+        finalResult.push(result2[index]);
+      }
+    }
+    return finalResult;
+  }
+  if (locale.startsWith("el")) {
+    if (!RE_GREEK.test(s) && !RE_LATIN.test(s)) {
+      return [s];
+    }
+    const parts = [];
+    RE_GREEK_LATIN_SPLIT.lastIndex = 0;
+    let greekExecMatch;
+    while ((greekExecMatch = RE_GREEK_LATIN_SPLIT.exec(s)) !== null) {
+      parts.push(greekExecMatch[0]);
+    }
+    if (parts.length === 0) {
+      parts.push(s);
+    }
+    const result2 = [];
+    const width = parts.length;
+    if (width === 1) {
+      const part = parts[0];
+      if (!part || !RE_GREEK.test(part[0]) || part.length === 1) {
+        return [part ?? s];
+      }
+    }
+    for (const greekPart of parts) {
+      if (!greekPart) {
+        continue;
+      }
+      if (!RE_GREEK.test(greekPart[0]) || greekPart.length === 1) {
+        result2.push(greekPart);
+        continue;
+      }
+      const partLength = greekPart.length;
+      let word = greekPart[0];
+      let previousIsUpper2 = greekPart[0] === greekPart[0].toLocaleUpperCase(locale);
+      for (let index = 1; index < partLength; index++) {
+        const char = greekPart[index];
+        const isUpperCaseChar = char === char.toLocaleUpperCase(locale);
+        if (!previousIsUpper2 && isUpperCaseChar) {
+          result2.push(word);
+          word = char;
+        } else {
+          word += char;
+        }
+        previousIsUpper2 = isUpperCaseChar;
+      }
+      if (word) {
+        result2.push(word);
+      }
+    }
+    return result2;
+  }
+  if (locale.startsWith("ja") || locale.startsWith("ko")) {
+    const isJapanese = locale.startsWith("ja");
+    const scriptDetectors = isJapanese ? {
+      hiragana: (char) => RE_HIRAGANA.test(char),
+      kanji: (char) => RE_KANJI.test(char),
+      katakana: (char) => RE_KATAKANA.test(char),
+      latin: (char) => RE_LATIN.test(char)
+    } : {
+      hangul: (char) => RE_HANGUL.test(char),
+      latin: (char) => RE_LATIN.test(char)
+    };
+    const particles = /* @__PURE__ */ new Set(["が", "で", "と", "に", "の", "は", "へ", "も", "や", "を"]);
+    if (isJapanese) {
+      const baseSegments = handleScriptTransitions(
+        s,
+        scriptDetectors,
+        false,
+        locale,
+        (previousType, currentType) => previousType === "hiragana" && currentType === "katakana" || previousType === "katakana" && currentType === "hiragana" || previousType === "hiragana" && currentType === "latin" || previousType === "katakana" && currentType === "latin" || previousType === "kanji" && currentType === "latin" || previousType === "latin" && (currentType === "hiragana" || currentType === "katakana" || currentType === "kanji")
+        // latin -> japanese
+      );
+      const result2 = [];
+      for (const baseSegment of baseSegments) {
+        const segment = baseSegment;
+        if (segment.length === 1 && particles.has(segment) && result2.length > 0) {
+          result2[result2.length - 1] = result2.at(-1) + segment;
+        } else {
+          result2.push(segment);
+        }
+      }
+      return result2.length > 0 ? result2 : [s];
+    }
+    return handleScriptTransitions(
+      s,
+      scriptDetectors,
+      false,
+      locale,
+      (previousType, currentType) => previousType === "hangul" && currentType === "latin" || previousType === "latin" && currentType === "hangul"
+      // latin -> hangul
+    );
+  }
+  if (locale.startsWith("sl")) {
+    const chars2 = [...s];
+    const width_2 = chars2.length;
+    const result2 = [];
+    let currentSegment2 = chars2[0];
+    let previousIsUpper2 = chars2[0] === chars2[0].toLocaleUpperCase(locale);
+    for (let index = 1; index < width_2; index++) {
+      const char = chars2[index];
+      const isUpperCaseChar = char === char.toLocaleUpperCase(locale);
+      const isSpecialChar = RE_SLOVENIAN_SPECIAL.test(char);
+      const nextIsUpper = index < width_2 - 1 && chars2[index + 1] === chars2[index + 1].toLocaleUpperCase(locale);
+      if (!previousIsUpper2 && isUpperCaseChar || isSpecialChar && nextIsUpper) {
+        result2.push(currentSegment2);
+        currentSegment2 = char;
+        if (isSpecialChar && nextIsUpper) {
+          result2.push(currentSegment2);
+          currentSegment2 = "";
+        }
+      } else {
+        currentSegment2 += char;
+      }
+      previousIsUpper2 = isUpperCaseChar;
+    }
+    if (currentSegment2 && currentSegment2.length > 0) {
+      result2.push(currentSegment2);
+    }
+    return result2;
+  }
+  if (locale.startsWith("zh")) {
+    return handleScriptTransitions(
+      s,
+      {
+        han: (char) => RE_KANJI.test(char),
+        latin: (char) => RE_LATIN.test(char)
+      },
+      false,
+      locale
+    );
+  }
+  if (["ar", "fa", "he", "ur"].includes(locale.split("-")[0])) {
+    const isRtlChar = (ch) => RE_HEBREW.test(ch) || RE_ARABIC.test(ch);
+    return handleScriptTransitions(
+      s,
+      {
+        latin: (char) => RE_LATIN.test(char),
+        rtl: (char) => isRtlChar(char)
+      },
+      false,
+      locale
+    );
+  }
+  if ([
+    "am",
+    // Amharic
+    "bn",
+    // Bengali
+    "gu",
+    // Gujarati
+    "hi",
+    // Hindi
+    "km",
+    // Khmer
+    "kn",
+    // Kannada
+    "lo",
+    // Lao
+    "ml",
+    // Malayalam
+    "mr",
+    // Marathi
+    "ne",
+    // Nepali
+    "or",
+    // Oriya
+    "pa",
+    // Punjabi
+    "si",
+    // Sinhala
+    "ta",
+    // Tamil
+    "te",
+    // Telugu
+    "th"
+    // Thai
+  ].includes(locale.split("-")[0])) {
+    const isIndicChar = (ch) => RE_DEVANAGARI.test(ch) || RE_BENGALI.test(ch) || RE_GUJARATI.test(ch) || RE_GURMUKHI.test(ch) || RE_KANNADA.test(ch) || RE_TAMIL.test(ch) || RE_TELUGU.test(ch) || RE_MALAYALAM.test(ch) || RE_SINHALA.test(ch) || RE_THAI.test(ch) || RE_LAO.test(ch) || RE_TIBETAN.test(ch) || RE_MYANMAR.test(ch) || RE_ETHIOPIC.test(ch) || RE_KHMER.test(ch) || RE_ORIYA.test(ch);
+    return handleScriptTransitions(
+      s,
+      {
+        indic: (char) => isIndicChar(char),
+        latin: (char) => RE_LATIN.test(char)
+      },
+      false,
+      locale
+    );
+  }
+  if (["be", "bg", "ru", "sr", "uk"].includes(locale)) {
+    return handleScriptTransitions(
+      s,
+      {
+        cyrillic: (char) => RE_CYRILLIC.test(char),
+        latin: (char) => RE_LATIN.test(char)
+      },
+      true,
+      // Enable case-sensitive splitting
+      locale
+    );
+  }
+  if (["ar", "fa", "he"].includes(locale)) {
+    return handleScriptTransitions(
+      s,
+      {
+        latin: (char) => RE_LATIN.test(char),
+        rtl: (char) => RE_HEBREW.test(char) || RE_ARABIC.test(char)
+      },
+      false,
+      locale
+    );
+  }
+  if (locale.startsWith("ko")) {
+    return handleScriptTransitions(
+      s,
+      {
+        hangul: (char) => RE_HANGUL.test(char),
+        latin: (char) => RE_LATIN.test(char)
+      },
+      false,
+      locale
+    );
+  }
+  if (locale.startsWith("uz")) {
+    if (!RE_CYRILLIC.test(s) && !RE_LATIN.test(s)) {
+      return [s];
+    }
+    const chars2 = [...s];
+    const width_2 = chars2.length;
+    const result2 = [];
+    let currentSegment2 = chars2[0];
+    let previousIsUpper2 = chars2[0] === chars2[0].toLocaleUpperCase(locale);
+    for (let index = 1; index < width_2; index++) {
+      const char = chars2[index];
+      const isUpperCaseChar = char === char.toLocaleUpperCase(locale);
+      if (RE_UZBEK_LATIN_MODIFIER.test(char) || RE_UZBEK_LATIN_MODIFIER.test(chars2[index - 1])) {
+        currentSegment2 += char;
+        continue;
+      }
+      if (!previousIsUpper2 && isUpperCaseChar) {
+        result2.push(currentSegment2);
+        currentSegment2 = char;
+      } else {
+        currentSegment2 += char;
+      }
+      previousIsUpper2 = isUpperCaseChar;
+    }
+    if (currentSegment2 && currentSegment2.length > 0) {
+      result2.push(currentSegment2);
+    }
+    return result2;
+  }
+  const chars = [...s];
+  const width_ = chars.length;
+  const result = [];
+  let currentSegment = chars[0];
+  let previousIsUpper = chars[0] === chars[0].toLocaleUpperCase(locale);
+  for (const acronym of knownAcronyms) {
+    if (s.startsWith(acronym)) {
+      result.push(acronym);
+      currentSegment = chars[acronym.length];
+      previousIsUpper = currentSegment === currentSegment.toLocaleUpperCase(locale);
+      break;
+    }
+  }
+  for (let index = 1; index < width_; index++) {
+    const char = chars[index];
+    const isUpperCaseChar = char === char.toLocaleUpperCase(locale);
+    let acronymLength = 0;
+    for (const acronym of knownAcronyms) {
+      if (s.startsWith(acronym, index)) {
+        result.push(currentSegment, acronym);
+        acronymLength = acronym.length;
+        currentSegment = "";
+        const lastAcronymChar = acronym.at(-1);
+        if (lastAcronymChar) {
+          previousIsUpper = lastAcronymChar === lastAcronymChar.toLocaleUpperCase(locale);
+        }
+        break;
+      }
+    }
+    if (acronymLength > 0) {
+      index += acronymLength - 1;
+      continue;
+    }
+    if (!previousIsUpper && isUpperCaseChar) {
+      result.push(currentSegment);
+      currentSegment = char;
+    } else {
+      currentSegment += char;
+    }
+    previousIsUpper = isUpperCaseChar;
+  }
+  if (currentSegment) {
+    result.push(currentSegment);
+  }
+  return result;
+};
+const processTextWithAnsiEmoji = (text, locale, knownAcronyms) => {
+  const result = [];
+  const segments = RE_FAST_ANSI.test(text) ? text.split(RE_FAST_ANSI).filter(Boolean) : [text];
+  for (const segment of segments) {
+    const seg = segment;
+    if (RE_FAST_ANSI.test(seg)) {
+      result.push(seg);
+    } else {
+      const subs = RE_EMOJI.test(seg) ? splitByEmoji(seg).filter(Boolean) : [seg];
+      for (const emojiSub of subs) {
+        if (RE_EMOJI.test(emojiSub)) {
+          result.push(emojiSub);
+        } else {
+          if (locale) {
+            const normalizedLocale = locale.toLowerCase().split("-")[0];
+            result.push(...splitCamelCaseLocale(emojiSub, normalizedLocale, knownAcronyms));
+          } else {
+            result.push(...splitCamelCaseFast(emojiSub, knownAcronyms));
+          }
+        }
+      }
+    }
+  }
+  return result;
+};
+const splitByCase = (input, options = {}) => {
+  if (!input || typeof input !== "string") {
+    return [];
+  }
+  const {
+    handleAnsi = false,
+    handleEmoji = false,
+    knownAcronyms = [],
+    locale,
+    normalize = false,
+    separators,
+    stripAnsi: stripAnsiOption = false,
+    stripEmoji: stripEmojiOption = false
+  } = options;
+  const acronymSet = new Set([...knownAcronyms].toSorted((a, b) => b.length - a.length));
+  let cleanedInput = input;
+  if (stripAnsiOption) {
+    cleanedInput = stripVTControlCharacters(cleanedInput);
+  }
+  if (stripEmojiOption) {
+    cleanedInput = stripEmoji(cleanedInput);
+  }
+  let separatorRegex;
+  if (Array.isArray(separators)) {
+    separatorRegex = getSeparatorsRegex(separators);
+  } else if (separators instanceof RegExp) {
+    separatorRegex = separators;
+  } else {
+    separatorRegex = RE_SEPARATORS;
+  }
+  const parts = [];
+  let workingInput = cleanedInput;
+  const regex = separatorRegex.flags.includes("g") ? separatorRegex : new RegExp(separatorRegex.source, `${separatorRegex.flags}g`);
+  while (workingInput.length > 0) {
+    const match = regex.exec(workingInput);
+    if (!match) {
+      if (workingInput === "..") {
+        parts.push("..");
+      } else if (workingInput === ".") {
+        parts.push(".");
+      } else if (workingInput.length > 0) {
+        parts.push(workingInput);
+      }
+      break;
+    }
+    const matchIndex = match.index;
+    const matchText = match[0];
+    const matchLength = matchText.length;
+    const beforeMatch = workingInput.slice(0, matchIndex);
+    const afterMatch = workingInput.slice(matchIndex + matchLength);
+    if (matchText.startsWith("../")) {
+      parts.push("..");
+      workingInput = workingInput.slice(matchIndex + 3);
+    } else if (matchText.startsWith("./")) {
+      parts.push(".");
+      workingInput = workingInput.slice(matchIndex + 2);
+    } else if (matchIndex === 0 && matchText === "..") {
+      parts.push("..");
+      workingInput = workingInput.slice(2);
+    } else if (matchIndex === 0 && matchText === ".") {
+      parts.push(".");
+      workingInput = workingInput.slice(1);
+    } else {
+      if (beforeMatch.length > 0) {
+        parts.push(beforeMatch);
+      }
+      let pos = 0;
+      while ((pos = matchText.indexOf("../", pos)) !== -1) {
+        parts.push("..");
+        pos += 3;
+      }
+      pos = 0;
+      while ((pos = matchText.indexOf("./", pos)) !== -1) {
+        if (pos === 0 || matchText[pos - 1] !== ".") {
+          parts.push(".");
+        }
+        pos += 2;
+      }
+      let remainingAfterMatch = afterMatch;
+      while (remainingAfterMatch.startsWith("../")) {
+        parts.push("..");
+        remainingAfterMatch = remainingAfterMatch.slice(3);
+      }
+      while (remainingAfterMatch.startsWith("./")) {
+        parts.push(".");
+        remainingAfterMatch = remainingAfterMatch.slice(2);
+      }
+      if (remainingAfterMatch === "..") {
+        parts.push("..");
+        break;
+      } else if (remainingAfterMatch === ".") {
+        parts.push(".");
+        break;
+      } else {
+        workingInput = remainingAfterMatch;
+      }
+    }
+    regex.lastIndex = 0;
+  }
+  if (parts.length === 0) {
+    const standardParts = cleanedInput.split(separatorRegex).filter(Boolean);
+    parts.push(...standardParts);
+  }
+  let tokens = [];
+  for (const splitPart of parts) {
+    if (handleAnsi || handleEmoji) {
+      tokens.push(...processTextWithAnsiEmoji(splitPart, locale, acronymSet));
+    } else if (locale) {
+      tokens.push(...splitCamelCaseLocale(splitPart, locale, acronymSet));
+    } else {
+      tokens.push(...splitCamelCaseFast(splitPart, acronymSet));
+    }
+  }
+  if (normalize) {
+    tokens = tokens.map((token) => {
+      if (acronymSet.has(token)) {
+        return token;
+      }
+      if (locale && token === token.toLocaleUpperCase(locale)) {
+        return token[0] + token.slice(1).toLocaleLowerCase(locale);
+      }
+      if (token.toUpperCase() === token && !acronymSet.has(token)) {
+        return token.slice(0, 1) + token.slice(1).toLowerCase();
+      }
+      return token;
+    });
+  }
+  return tokens;
+};
+
+const upperFirst = (value, options) => {
+  if (typeof value !== "string" || value === "") {
+    return "";
+  }
+  const firstChar = value[0].toUpperCase();
+  return firstChar + value.slice(1);
+};
+
+const joinSegments = (segments, joiner) => {
+  const { length } = segments;
+  if (length === 0) {
+    return "";
+  }
+  if (length === 1) {
+    return segments[0];
+  }
+  const result = [];
+  let ansiStart = "";
+  let currentContent = "";
+  for (let index = 0; index < length; index++) {
+    const segment = segments[index];
+    if (RE_FAST_ANSI.test(segment)) {
+      if (ansiStart) {
+        result.push(ansiStart + currentContent + segment);
+        ansiStart = "";
+        currentContent = "";
+      } else {
+        if (result.length > 0) {
+          result.push(joiner);
+        }
+        ansiStart = segment;
+      }
+      continue;
+    }
+    if (ansiStart) {
+      if (currentContent) {
+        currentContent += joiner;
+      }
+      currentContent += segment;
+    } else {
+      if (result.length > 0) {
+        result.push(joiner);
+      }
+      result.push(segment);
+    }
+  }
+  return result.join("");
+};
+
+const camelCase = (value, options) => {
+  if (typeof value !== "string" || !value) {
+    return "";
+  }
+  let firstWord = true;
+  const result = joinSegments(
+    splitByCase(value, {
+      handleAnsi: options?.handleAnsi,
+      handleEmoji: options?.handleEmoji,
+      knownAcronyms: options?.knownAcronyms,
+      locale: options?.locale,
+      normalize: options?.normalize,
+      separators: void 0,
+      stripAnsi: options?.stripAnsi,
+      stripEmoji: options?.stripEmoji
+    }).map((word) => {
+      const normalized = word;
+      const lowered = normalized.toLowerCase();
+      if (firstWord) {
+        firstWord = false;
+        return lowerFirst(lowered);
+      }
+      return upperFirst(lowered);
+    }),
+    ""
+  );
+  return result;
+};
+
+const processOptionNames = (command) => {
+  command.options?.forEach((option) => {
+    option.__camelCaseName__ = camelCase(option.name);
+  });
+};
+const addNegatableOptions = (command) => {
+  if (!Array.isArray(command.options) || command.options.length === 0) {
+    return;
+  }
+  const optionNames = /* @__PURE__ */ new Set();
+  for (const option of command.options) {
+    optionNames.add(option.name);
+  }
+  const optionsToAdd = [];
+  for (const option of command.options) {
+    if (option.name.startsWith("no-")) {
+      const nonNegatedName = option.name.replace("no-", "");
+      if (!optionNames.has(nonNegatedName)) {
+        if (option.type !== Boolean) {
+          throw new Error(`Cannot add negated option "${option.name}" to command "${command.name}" because it is not a boolean.`);
+        }
+        const negatedOption = {
+          ...option,
+          defaultValue: option.defaultValue === void 0 ? true : !option.defaultValue,
+          name: nonNegatedName
+        };
+        optionsToAdd.push(negatedOption);
+        optionNames.add(nonNegatedName);
+      }
+    }
+  }
+  if (optionsToAdd.length > 0) {
+    command.options.push(...optionsToAdd);
+  }
+};
+const mapNegatableOptions = (toolbox, command) => {
+  if (!command.options || command.options.length === 0) {
+    return;
+  }
+  const { options } = toolbox;
+  const negatedOptionMap = /* @__PURE__ */ new Map();
+  for (const option of command.options) {
+    if (option.name.startsWith("no-")) {
+      const camelCaseName = camelCase(option.name);
+      negatedOptionMap.set(camelCaseName, option);
+    }
+  }
+  const negatableKeys = Object.keys(options).filter((key) => negatedOptionMap.has(key));
+  if (negatableKeys.length === 0) {
+    return;
+  }
+  for (const negatedKey of negatableKeys) {
+    const thirdChar = negatedKey.charAt(2);
+    if (!thirdChar) {
+      continue;
+    }
+    const nonNegatedKey = thirdChar.toLowerCase() + negatedKey.slice(3);
+    const negatedOption = negatedOptionMap.get(negatedKey);
+    if (negatedOption) {
+      negatedOption.__negated__ = true;
+    }
+    options[nonNegatedKey] = !options[negatedKey];
+    Reflect.deleteProperty(options, negatedKey);
+  }
+};
+const mapImpliedOptions = (toolbox, command) => {
+  if (!command.options || command.options.length === 0) {
+    return;
+  }
+  const optionMapByCamelCase = /* @__PURE__ */ new Map();
+  for (const option of command.options) {
+    if (option.__camelCaseName__ && option.__negated__ === void 0 && option.implies !== void 0) {
+      optionMapByCamelCase.set(option.__camelCaseName__, option);
+    }
+  }
+  if (optionMapByCamelCase.size === 0) {
+    return;
+  }
+  const { options } = toolbox;
+  for (const optionKey of Object.keys(options)) {
+    const option = optionMapByCamelCase.get(optionKey);
+    if (option?.implies) {
+      const { implies } = option;
+      for (const [key, value] of Object.entries(implies)) {
+        if (options[key] === void 0) {
+          options[key] = value;
+        }
+      }
+    }
+  }
+};
+
+const isElectronApp = () => !!process.versions.electron;
+const isBundledElectronApp = () => isElectronApp() && !process.defaultApp;
+const getProcessArgvBinIndex = () => {
+  if (isBundledElectronApp()) {
+    return 0;
+  }
+  return 1;
+};
+const hideBin = (argv) => argv.slice(getProcessArgvBinIndex() + 1);
+
+const COMMAND_DELIMITER = " ";
+const equals = (a, b) => {
+  if (a === b) {
+    return true;
+  }
+  if (a.length !== b.length) {
+    return false;
+  }
+  return a.every((v, index) => v === b[index]);
+};
+const parseRawCommand = (commandArray) => {
+  if (typeof commandArray === "string") {
+    return commandArray.split(COMMAND_DELIMITER);
+  }
+  const argv = getArgv();
+  if (equals(commandArray, argv)) {
+    return hideBin(commandArray);
+  }
+  return commandArray;
+};
+
+const registerExceptionHandler = (logger) => {
+  const uncaughtExceptionHandler = (error) => {
+    logger.error(`Uncaught exception: ${error.message || error}`);
+    if (error.stack) {
+      logger.error(error.stack);
+    }
+    exitProcess(1);
+  };
+  const unhandledRejectionHandler = (reason, _promise) => {
+    if (reason instanceof Error) {
+      logger.error(`Promise rejection: ${reason.message || reason}`);
+      if (reason.stack) {
+        logger.error(reason.stack);
+      }
+    } else {
+      let reasonString;
+      if (typeof reason === "string") {
+        reasonString = reason;
+      } else {
+        try {
+          reasonString = JSON.stringify(reason);
+        } catch {
+          reasonString = String(reason);
+        }
+      }
+      logger.error(`Promise rejection: ${reasonString}`);
+    }
+    exitProcess(1);
+  };
+  const cleanupUncaughtException = onProcessEvent("uncaughtException", uncaughtExceptionHandler);
+  const cleanupUnhandledRejection = onProcessEvent("unhandledRejection", unhandledRejectionHandler);
+  return () => {
+    cleanupUncaughtException();
+    cleanupUnhandledRejection();
+  };
+};
+
+const MAX_NAME_LENGTH = 100;
+const NAME_PATTERN = /^[a-z][\w-]*$/i;
+const validateNonEmptyString = (value, fieldName) => {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new CerebroError(`${fieldName} must be a non-empty string`, "INVALID_INPUT", { fieldName, value });
+  }
+  return value.trim();
+};
+const validateStringArray = (value, fieldName) => {
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+    throw new CerebroError(`${fieldName} must be an array of strings`, "INVALID_INPUT", { fieldName, value });
+  }
+  return value;
+};
+const validateObject = (value, fieldName) => {
+  if (typeof value !== "object" || value === null) {
+    throw new CerebroError(`${fieldName} must be an object`, "INVALID_INPUT", { fieldName, value });
+  }
+  return value;
+};
+const validateCommandName = (name) => {
+  const trimmedName = validateNonEmptyString(name, "Command name");
+  if (trimmedName.length > MAX_NAME_LENGTH) {
+    throw new CerebroError(`Command name is too long (maximum ${String(MAX_NAME_LENGTH)} characters)`, "INVALID_COMMAND_NAME", {
+      commandName: trimmedName,
+      length: trimmedName.length
+    });
+  }
+  if (trimmedName.includes("..") || trimmedName.includes("/") || trimmedName.includes("\\") || trimmedName.includes(";") || trimmedName.includes("|") || trimmedName.includes("&")) {
+    throw new CerebroError(`Command name "${trimmedName}" contains invalid characters`, "INVALID_COMMAND_NAME", { commandName: trimmedName });
+  }
+  if (!NAME_PATTERN.test(trimmedName)) {
+    throw new CerebroError(
+      `Command name "${trimmedName}" must start with a letter and contain only letters, numbers, hyphens, and underscores`,
+      "INVALID_COMMAND_NAME",
+      { commandName: trimmedName }
+    );
+  }
+  return trimmedName;
+};
+
+const MAX_ARGUMENT_LENGTH = 1e4;
+const MAX_ARGS = 100;
+const DANGEROUS_CHARS = /* @__PURE__ */ new Set(["\n", "\r", "	", "\0", '"', "$", "&", "'", "(", ")", ";", "<", ">", "[", "\\", "]", "`", "{", "|", "}"]);
+const sanitizeArgument = (argument) => {
+  if (typeof argument !== "string") {
+    throw new TypeError("Argument must be a string");
+  }
+  if (argument.length > MAX_ARGUMENT_LENGTH) {
+    throw new Error(`Argument is too long (maximum ${String(MAX_ARGUMENT_LENGTH)} characters)`);
+  }
+  for (const char of argument) {
+    if (DANGEROUS_CHARS.has(char)) {
+      throw new Error(`Argument contains dangerous character: ${char}`);
+    }
+  }
+  return argument.trim();
+};
+const sanitizeArguments = (args) => {
+  if (!Array.isArray(args)) {
+    throw new TypeError("Arguments must be an array");
+  }
+  if (args.length > MAX_ARGS) {
+    throw new Error(`Too many arguments (maximum ${String(MAX_ARGS)})`);
+  }
+  return args.map((argument) => sanitizeArgument(argument));
+};
+
+const OPTION_REGEX_SHORT = /^-([^\d-])$/;
+const OPTION_REGEX_LONG = /^--(\S+)/;
+const OPTION_REGEX_COMBINED = /^-([^\d-]{2,})$/;
+const isOption = (argument) => OPTION_REGEX_SHORT.test(argument) || OPTION_REGEX_LONG.test(argument) || OPTION_REGEX_COMBINED.test(argument);
+class Cli {
+  #logger;
+  #options;
+  #argv;
+  #cwd;
+  #cliName;
+  #packageVersion;
+  #packageName;
+  #pluginManager;
+  #commands;
+  /** Map of command path keys to full command paths for nested command lookup */
+  #commandPaths;
+  /**
+   * Map of commands keyed by their full path string (e.g., "deploy staging")
+   * This allows correct resolution when different paths share the same leaf name
+   */
+  #commandsByPath;
+  #defaultCommand;
+  #commandSection;
+  #pluginsInitialized = false;
+  #exceptionHandlerCleanup;
+  #exceptionHandlerRegistered = false;
+  #cachedCommandPathKeys;
+  #cachedCommandNames;
+  #cachedAllCommandPaths;
+  #customGlobalOptions = [];
+  /**
+   * Gets all command path keys (cached for performance).
+   * @returns Array of command path keys
+   */
+  #getCommandPathKeys() {
+    if (this.#cachedCommandPathKeys === void 0) {
+      this.#cachedCommandPathKeys = [...this.#commandPaths.keys()];
+    }
+    return this.#cachedCommandPathKeys;
+  }
+  /**
+   * Gets all command names (cached for performance).
+   * @returns Array of command names
+   */
+  #getCommandNames() {
+    if (this.#cachedCommandNames === void 0) {
+      this.#cachedCommandNames = [...this.#commands.keys()];
+    }
+    return this.#cachedCommandNames;
+  }
+  /**
+   * Gets all command paths combined (cached for performance).
+   * @returns Array of all command paths
+   */
+  #getAllCommandPaths() {
+    if (this.#cachedAllCommandPaths === void 0) {
+      this.#cachedAllCommandPaths = [...this.#getCommandPathKeys(), ...this.#getCommandNames()];
+    }
+    return this.#cachedAllCommandPaths;
+  }
+  /**
+   * Gets all global options (built-in + custom).
+   */
+  #getAllGlobalOptions() {
+    if (this.#customGlobalOptions.length === 0) {
+      return defaultOptions;
+    }
+    return [...defaultOptions, ...this.#customGlobalOptions];
+  }
+  /**
+   * Invalidates cached command arrays (call when commands are added/removed).
+   */
+  #invalidateCommandCache() {
+    this.#cachedCommandPathKeys = void 0;
+    this.#cachedCommandNames = void 0;
+    this.#cachedAllCommandPaths = void 0;
+  }
+  /**
+   * Gets parsed argv.
+   * @returns Parsed and sanitized argv array
+   */
+  #getArgv() {
+    if (this.#argv === void 0) {
+      const rawArgv = parseRawCommand(this.#options.argv);
+      this.#argv = sanitizeArguments(rawArgv);
+      this.#setVerbosityLevel();
+    }
+    return this.#argv;
+  }
+  /**
+   * Sets verbosity level from argv flags.
+   */
+  #setVerbosityLevel() {
+    if (!this.#argv) {
+      return;
+    }
+    const env = getEnv();
+    let verbositySet = false;
+    for (const argument of this.#argv) {
+      if (argument === "--quiet" || argument === "-q") {
+        env.CEREBRO_OUTPUT_LEVEL = String(VERBOSITY_QUIET);
+        verbositySet = true;
+        break;
+      }
+      if (argument === "--verbose" || argument === "-v") {
+        env.CEREBRO_OUTPUT_LEVEL = String(VERBOSITY_VERBOSE);
+        verbositySet = true;
+        break;
+      }
+      if (argument === "--debug" || argument === "-vvv") {
+        env.CEREBRO_OUTPUT_LEVEL = String(VERBOSITY_DEBUG);
+        verbositySet = true;
+        break;
+      }
+    }
+    if (!verbositySet) {
+      env.CEREBRO_OUTPUT_LEVEL = Object.hasOwn(env, "DEBUG") ? String(VERBOSITY_DEBUG) : String(VERBOSITY_NORMAL);
+    }
+  }
+  /**
+   * Registers exception handlers.
+   */
+  #ensureExceptionHandlers() {
+    if (!this.#exceptionHandlerRegistered) {
+      this.#exceptionHandlerCleanup = registerExceptionHandler(this.#logger);
+      this.#exceptionHandlerRegistered = true;
+    }
+  }
+  /**
+   * Common command execution logic shared between run() and runCommand().
+   */
+  #executeCommandInternal(command, commandArguments, extraOptions, pathKey) {
+    this.#logger.debug(`command '${pathKey}' found, parsing command args: ${commandArguments.join(", ")}`);
+    const { arguments_, booleanValues, parsedArgs } = processCommandArgs(command, commandArguments, this.#getAllGlobalOptions());
+    const hasBooleanValues = Object.keys(booleanValues).length > 0;
+    const commandArgs = hasBooleanValues ? { ...parsedArgs, _all: { ...parsedArgs._all, ...booleanValues } } : parsedArgs;
+    validateRequiredOptions(arguments_, commandArgs, command);
+    const toolbox = prepareToolbox(command, parsedArgs, booleanValues, extraOptions);
+    toolbox.runtime = this;
+    toolbox.argv = this.#getArgv();
+    const hasOptions = command.options && command.options.length > 0;
+    if (hasOptions && command.options) {
+      const negatedOptions = command.options.filter((option) => option.name.startsWith("no-"));
+      for (const negatedOption of negatedOptions) {
+        const nonNegatedName = negatedOption.name.replace("no-", "");
+        const negatedFlag = `--${negatedOption.name}`;
+        const nonNegatedFlag = `--${nonNegatedName}`;
+        const hasNegatedFlag = commandArguments.includes(negatedFlag);
+        const hasNonNegatedFlag = commandArguments.includes(nonNegatedFlag);
+        if (hasNegatedFlag && hasNonNegatedFlag) {
+          throw new ConflictingOptionsError(nonNegatedName, negatedOption.name);
+        }
+      }
+    }
+    if (hasOptions) {
+      mapNegatableOptions(toolbox, command);
+      mapImpliedOptions(toolbox, command);
+    }
+    validateConflictingOptions(arguments_, toolbox.options, command);
+    const env = getEnv();
+    if (env.CEREBRO_OUTPUT_LEVEL === String(VERBOSITY_DEBUG)) {
+      this.#logger.debug("command options parsed from options:");
+      this.#logger.debug(JSON.stringify(toolbox.options, null, 2));
+      this.#logger.debug("command argument parsed from argument:");
+      this.#logger.debug(JSON.stringify(toolbox.argument, null, 2));
+    }
+    return { arguments_, booleanValues, commandArgs, parsedArgs, toolbox };
+  }
+  /**
+   * 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
+   */
+  // eslint-disable-next-line sonarjs/cognitive-complexity
+  constructor(cliName, options = {}) {
+    if (typeof cliName !== "string" || cliName.trim().length === 0) {
+      throw new CerebroError("CLI name must be a non-empty string", "INVALID_INPUT", { cliName });
+    }
+    this.#cliName = cliName.trim();
+    const argv = options.argv ?? getArgv();
+    const cwd = options.cwd ?? getCwd();
+    this.#options = { ...options, argv, cwd };
+    if (this.#options.argv && !Array.isArray(this.#options.argv)) {
+      throw new CerebroError("CLI argv option must be an array of strings", "INVALID_INPUT", { argv: this.#options.argv });
+    }
+    if (this.#options.cwd && typeof this.#options.cwd !== "string") {
+      throw new CerebroError("CLI cwd option must be a string", "INVALID_INPUT", { cwd: this.#options.cwd });
+    }
+    if (this.#options.packageName && typeof this.#options.packageName !== "string") {
+      throw new CerebroError("CLI packageName option must be a string", "INVALID_INPUT", { packageName: this.#options.packageName });
+    }
+    if (this.#options.packageVersion && typeof this.#options.packageVersion !== "string") {
+      throw new CerebroError("CLI packageVersion option must be a string", "INVALID_INPUT", { packageVersion: this.#options.packageVersion });
+    }
+    const env = getEnv();
+    env.CEREBRO_OUTPUT_LEVEL = String(VERBOSITY_NORMAL);
+    if (typeof this.#options.logger === "object") {
+      const requiredMethods = ["debug", "error", "info", "log", "warn"];
+      const missingMethods = [];
+      const logger = this.#options.logger;
+      for (const method of requiredMethods) {
+        if (typeof logger[method] !== "function") {
+          missingMethods.push(method);
+        }
+      }
+      if (missingMethods.length > 0) {
+        throw new CerebroError(`Logger object is missing required methods: ${missingMethods.join(", ")}`, "INVALID_INPUT", {
+          logger: this.#options.logger,
+          missingMethods
+        });
+      }
+      this.#logger = this.#options.logger;
+    } else {
+      this.#logger = {
+        ...console,
+        debug: (...args) => {
+          if (env.CEREBRO_OUTPUT_LEVEL === String(VERBOSITY_DEBUG)) {
+            console.debug(...args);
+          }
+        }
+      };
+    }
+    this.#packageVersion = this.#options.packageVersion;
+    this.#packageName = this.#options.packageName;
+    this.#cwd = this.#options.cwd;
+    this.#defaultCommand = "help";
+    this.#commandSection = {};
+    this.#commands = /* @__PURE__ */ new Map();
+    this.#commandPaths = /* @__PURE__ */ new Map();
+    this.#commandsByPath = /* @__PURE__ */ new Map();
+  }
+  /**
+   * 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) {
+    this.#commandSection = commandSection;
+    return this;
+  }
+  /**
+   * Gets the current command section configuration.
+   * @returns The command section configuration
+   */
+  getCommandSection() {
+    if (!this.#commandSection.header) {
+      this.#commandSection.header = `${this.#cliName}${this.#packageVersion ? ` v${this.#packageVersion}` : ""}`;
+    }
+    return this.#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) {
+    this.#defaultCommand = commandName;
+    return this;
+  }
+  /**
+   * Gets the current default command.
+   * @returns The name of the default command
+   */
+  get defaultCommand() {
+    return this.#defaultCommand;
+  }
+  /**
+   * 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'}`);
+   *   }
+   * });
+   * ```
+   */
+  // eslint-disable-next-line sonarjs/cognitive-complexity
+  addCommand(command) {
+    validateObject(command, "Command");
+    validateCommandName(command.name);
+    if (command.alias) {
+      if (typeof command.alias === "string") {
+        validateCommandName(command.alias);
+      } else {
+        validateStringArray(command.alias, "Command alias").forEach((alias) => validateCommandName(alias));
+      }
+    }
+    if (command.argument) {
+      validateObject(command.argument, "Command argument");
+    }
+    if (command.options) {
+      validateObject(command.options, "Command options");
+    }
+    if (command.commandPath) {
+      validateStringArray(command.commandPath, "Command commandPath");
+      command.commandPath.forEach((segment) => {
+        validateCommandName(segment);
+      });
+    }
+    const fullPath = getFullCommandPath(command.name, command.commandPath);
+    const pathKey = getCommandPathKey(fullPath);
+    if (this.#commandPaths.has(pathKey)) {
+      throw new CerebroError(`Command with path "${pathKey}" already exists`, "DUPLICATE_COMMAND", {
+        commandName: command.name,
+        commandPath: command.commandPath
+      });
+    }
+    if (this.#commands.has(command.name) && !command.commandPath) {
+      throw new CerebroError(`Command with name "${command.name}" already exists`, "DUPLICATE_COMMAND", { commandName: command.name });
+    }
+    if (command.options) {
+      for (const option of command.options) {
+        mapOptionTypeLabel(option);
+      }
+    }
+    validateDuplicateOptions(command);
+    addNegatableOptions(command);
+    processOptionNames(command);
+    if (command.options) {
+      command.__conflictingOptions__ = command.options.filter((option) => option.conflicts !== void 0);
+      command.__requiredOptions__ = command.options.filter((option) => option.required === true);
+    }
+    this.#commands.set(command.name, command);
+    this.#commandPaths.set(pathKey, fullPath);
+    this.#commandsByPath.set(pathKey, command);
+    this.#invalidateCommandCache();
+    if (command.alias !== void 0) {
+      const aliases = typeof command.alias === "string" ? [command.alias] : command.alias;
+      for (const alias of aliases) {
+        const env = getEnv();
+        if (env.CEREBRO_OUTPUT_LEVEL === String(VERBOSITY_DEBUG)) {
+          this.#logger.debug("adding alias", alias);
+        }
+        if (this.#commands.has(alias)) {
+          throw new CerebroError(`Command alias "${alias}" conflicts with existing command`, "DUPLICATE_COMMAND", {
+            alias,
+            commandName: command.name
+          });
+        }
+        this.#commands.set(alias, command);
+      }
+    }
+    return 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(option) {
+    const optionDefinition = option;
+    const builtInNames = new Set(defaultOptions.map((o) => o.name));
+    const builtInAliases = new Set(defaultOptions.map((o) => o.alias).filter(Boolean));
+    if (builtInNames.has(optionDefinition.name)) {
+      throw new CerebroError(`Cannot add global option "--${optionDefinition.name}": it conflicts with a built-in global option`, "DUPLICATE_OPTION", {
+        optionName: optionDefinition.name
+      });
+    }
+    if (optionDefinition.alias && builtInAliases.has(optionDefinition.alias)) {
+      throw new CerebroError(
+        `Cannot add global option with alias "-${optionDefinition.alias}": it conflicts with a built-in global option alias`,
+        "DUPLICATE_OPTION",
+        { alias: optionDefinition.alias, optionName: optionDefinition.name }
+      );
+    }
+    const existingNames = new Set(this.#customGlobalOptions.map((o) => o.name));
+    if (existingNames.has(optionDefinition.name)) {
+      throw new CerebroError(`Global option "--${optionDefinition.name}" has already been added`, "DUPLICATE_OPTION", { optionName: optionDefinition.name });
+    }
+    optionDefinition.group = "global";
+    mapOptionTypeLabel(optionDefinition);
+    this.#customGlobalOptions.push(optionDefinition);
+    return this;
+  }
+  /**
+   * Gets all global options (built-in + custom).
+   * @returns Array of all global option definitions
+   */
+  getGlobalOptions() {
+    return this.#getAllGlobalOptions();
+  }
+  /**
+   * 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) {
+    this.getPluginManager().register(plugin);
+    return this;
+  }
+  /**
+   * Gets the plugin manager instance for advanced plugin management.
+   * @returns The plugin manager instance
+   */
+  getPluginManager() {
+    if (this.#pluginManager) {
+      return this.#pluginManager;
+    }
+    this.#pluginManager = new PluginManager(this.#logger);
+    this.#pluginManager.register({
+      description: "Attaches the logger to the toolbox",
+      execute: (toolbox) => {
+        toolbox.logger = this.#logger;
+      },
+      name: "logger"
+    });
+    return this.#pluginManager;
+  }
+  /**
+   * Gets the CLI application name.
+   */
+  getCliName() {
+    return this.#cliName;
+  }
+  /**
+   * Gets the package version if configured.
+   * @returns The package version or undefined
+   */
+  getPackageVersion() {
+    return this.#packageVersion;
+  }
+  /**
+   * Gets the package name if configured.
+   * @returns The package name or undefined
+   */
+  getPackageName() {
+    return this.#packageName;
+  }
+  /**
+   * Gets all registered commands.
+   * @returns A map of command names to command definitions
+   */
+  getCommands() {
+    return this.#commands;
+  }
+  /**
+   * Gets the current working directory.
+   * @returns The current working directory path
+   */
+  getCwd() {
+    return this.#cwd;
+  }
+  /**
+   * 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() {
+    this.#exceptionHandlerCleanup?.();
+  }
+  /**
+   * 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 });
+   * ```
+   */
+  // eslint-disable-next-line sonarjs/cognitive-complexity
+  async run(extraOptions = {}) {
+    const { autoDispose = true, shouldExitProcess = true, ...otherExtraOptions } = extraOptions;
+    if (!this.#commands.has("help")) {
+      this.addCommand(new HelpCommand(this.#commands));
+    }
+    const commandNames = this.#getCommandNames();
+    const commandPathMap = this.#commandPaths;
+    this.#ensureExceptionHandlers();
+    const argv = this.#getArgv();
+    let parsedCommandPath;
+    let remainingArgv = [...argv];
+    const execPath = getExecPath();
+    const execArgv = getExecArgv();
+    const runtimeArgv = getArgv();
+    this.#logger.debug(`process.execPath: ${execPath}`);
+    this.#logger.debug(`process.execArgv: ${execArgv.join(" ")}`);
+    this.#logger.debug(`process.argv: ${runtimeArgv.join(" ")}`);
+    const nestedResult = parseNestedCommand(commandPathMap, [...argv]);
+    if (nestedResult.commandPath) {
+      parsedCommandPath = nestedResult.commandPath;
+      remainingArgv = nestedResult.argv;
+    } else {
+      if (argv.length > 1 && argv[0] && argv[1] && !isOption(argv[0]) && !isOption(argv[1])) {
+        const attemptedPath = [];
+        let i = 0;
+        while (i < argv.length) {
+          const argument = argv[i];
+          if (!argument || isOption(argument)) {
+            break;
+          }
+          attemptedPath.push(argument);
+          i += 1;
+        }
+        const attemptedPathKey = getCommandPathKey(attemptedPath);
+        if (attemptedPath[0] && !commandNames.includes(attemptedPath[0])) {
+          const allCommandPaths = this.#getAllCommandPaths();
+          const alternatives = findAlternatives(attemptedPathKey, allCommandPaths);
+          throw new CommandNotFoundError(attemptedPathKey, alternatives);
+        }
+      }
+      let parsedArguments;
+      try {
+        parsedArguments = commandLineCommands([null, ...commandNames], [...argv]);
+      } catch (error) {
+        if (error instanceof Error && error.name === "INVALID_COMMAND" && "command" in error) {
+          const invalidCommand = error.command;
+          const allCommandPaths = this.#getAllCommandPaths();
+          const alternatives = findAlternatives(invalidCommand, allCommandPaths);
+          throw new CommandNotFoundError(invalidCommand, alternatives);
+        }
+        throw error;
+      }
+      if (parsedArguments.command) {
+        parsedCommandPath = [parsedArguments.command];
+        remainingArgv = parsedArguments.argv;
+      }
+    }
+    if (!parsedCommandPath) {
+      if (this.#defaultCommand) {
+        parsedCommandPath = [this.#defaultCommand];
+      } else {
+        const allCommandPaths = this.#getAllCommandPaths();
+        throw new CommandNotFoundError("", allCommandPaths);
+      }
+    }
+    const pathKey = getCommandPathKey(parsedCommandPath);
+    const storedPath = this.#commandPaths.get(pathKey);
+    let command;
+    if (storedPath) {
+      command = this.#commandsByPath.get(pathKey);
+      if (!command || getCommandPathKey(storedPath) !== pathKey) {
+        const allCommandPaths = this.#getAllCommandPaths();
+        const alternatives = findAlternatives(pathKey, allCommandPaths);
+        throw new CommandNotFoundError(pathKey, alternatives);
+      }
+    } else {
+      const commandName = parsedCommandPath.at(-1);
+      command = commandName ? this.#commands.get(commandName) : void 0;
+      if (!command) {
+        const allCommandPaths = this.#getAllCommandPaths();
+        const alternatives = findAlternatives(pathKey, allCommandPaths);
+        throw new CommandNotFoundError(pathKey, alternatives);
+      }
+    }
+    if (typeof command.execute !== "function") {
+      this.#logger.error(`Command "${command.name}" has no function to execute.`);
+      return shouldExitProcess ? exitProcess(1) : void 0;
+    }
+    const commandArguments = remainingArgv;
+    const { commandArgs, toolbox } = this.#executeCommandInternal(command, commandArguments, otherExtraOptions, pathKey);
+    const pluginManager = this.getPluginManager();
+    try {
+      if (!this.#pluginsInitialized && pluginManager.hasPlugins()) {
+        await pluginManager.init({
+          cli: this,
+          cwd: this.#cwd,
+          logger: this.#logger
+        });
+        this.#pluginsInitialized = true;
+      }
+      await pluginManager.executeLifecycle("execute", toolbox);
+      await pluginManager.executeLifecycle("beforeCommand", toolbox);
+      let result;
+      const globalOptions = commandArgs.global;
+      if (globalOptions?.help) {
+        const helpCommand = this.#commands.get("help");
+        if (!helpCommand) {
+          throw new CerebroError("Help command not found", "COMMAND_NOT_FOUND");
+        }
+        result = await executeCommand(helpCommand, toolbox);
+      } else if (globalOptions?.version ?? globalOptions?.V) {
+        const versionCommand = this.#commands.get("version");
+        if (!versionCommand) {
+          throw new CerebroError("Version command not found", "COMMAND_NOT_FOUND");
+        }
+        result = await executeCommand(versionCommand, toolbox);
+      } else {
+        result = await executeCommand(command, toolbox);
+      }
+      await pluginManager.executeLifecycle("afterCommand", toolbox, result);
+      return shouldExitProcess ? exitProcess(0) : void 0;
+    } catch (error) {
+      await pluginManager.executeErrorHandlers(error, toolbox);
+      throw error;
+    } finally {
+      if (autoDispose) {
+        this.dispose();
+      }
+    }
+  }
+  /**
+   * 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'] });
+   *   }
+   * });
+   * ```
+   */
+  async runCommand(commandName, options = {}) {
+    const { argv: providedArgv = [], ...extraOptions } = options;
+    validateNonEmptyString(commandName, "Command name");
+    const commandPath = commandName.split(" ").filter(Boolean);
+    const pathKey = getCommandPathKey(commandPath);
+    const storedPath = this.#commandPaths.get(pathKey);
+    const command = storedPath ? this.#commandsByPath.get(pathKey) : this.#commands.get(commandName);
+    if (!command) {
+      const allCommandPaths = this.#getAllCommandPaths();
+      const alternatives = findAlternatives(pathKey || commandName, allCommandPaths);
+      throw new CommandNotFoundError(commandName, alternatives);
+    }
+    if (typeof command.execute !== "function") {
+      throw new CerebroError(`Command "${command.name}" has no function to execute`, "INVALID_COMMAND", { commandName: command.name });
+    }
+    const sanitizedArgv = sanitizeArguments(providedArgv);
+    const commandArguments = [...sanitizedArgv];
+    this.#logger.debug(`running command '${commandName}' programmatically with args: ${commandArguments.join(", ")}`);
+    const { commandArgs, toolbox } = this.#executeCommandInternal(command, commandArguments, extraOptions, pathKey || commandName);
+    const pluginManager = this.getPluginManager();
+    try {
+      if (!this.#pluginsInitialized && pluginManager.hasPlugins()) {
+        await pluginManager.init({
+          cli: this,
+          cwd: this.#cwd,
+          logger: this.#logger
+        });
+        this.#pluginsInitialized = true;
+      }
+      await pluginManager.executeLifecycle("execute", toolbox);
+      await pluginManager.executeLifecycle("beforeCommand", toolbox);
+      let result;
+      const runGlobalOptions = commandArgs.global;
+      if (runGlobalOptions?.help) {
+        const helpCommand = this.#commands.get("help");
+        if (!helpCommand) {
+          throw new CerebroError("Help command not found", "COMMAND_NOT_FOUND");
+        }
+        result = await executeCommand(helpCommand, toolbox);
+      } else if (runGlobalOptions?.version ?? runGlobalOptions?.V) {
+        const versionCommand = this.#commands.get("version");
+        if (!versionCommand) {
+          throw new CerebroError("Version command not found", "COMMAND_NOT_FOUND");
+        }
+        result = await executeCommand(versionCommand, toolbox);
+      } else {
+        result = await executeCommand(command, toolbox);
+      }
+      await pluginManager.executeLifecycle("afterCommand", toolbox, result);
+      return result;
+    } catch (error) {
+      await pluginManager.executeErrorHandlers(error, toolbox);
+      throw error;
+    }
+  }
+}
+
+export { Cli };