bob-core 2.0.0-beta.21 → 2.0.0-beta.24

package/dist/index.js

@@ -0,0 +1,1349 @@
+import prompts from "prompts";
+import chalk from "chalk";
+import minimist from "minimist";
+import fs from "node:fs";
+import path from "node:path";
+class CommandIO {
+  logger;
+  constructor(opts) {
+    this.logger = opts.logger;
+  }
+  /**
+   * Logger methods
+   */
+  log(...args) {
+    this.logger.log(...args);
+  }
+  info(...args) {
+    this.logger.info(...args);
+  }
+  warn(...args) {
+    this.logger.warn(...args);
+  }
+  error(...args) {
+    this.logger.error(...args);
+  }
+  debug(...args) {
+    this.logger.debug(...args);
+  }
+  /**
+   * Prompt utils
+   */
+  async askForConfirmation(message = "Do you want to continue?", defaultValue) {
+    return (await prompts({
+      type: "confirm",
+      name: "value",
+      message,
+      initial: defaultValue ?? false
+    })).value;
+  }
+  async askForInput(message, defaultValue, opts) {
+    return (await prompts({
+      type: "text",
+      name: "value",
+      message,
+      initial: defaultValue,
+      ...opts
+    }))?.value ?? null;
+  }
+  async askForDate(message, defaultValue, opts) {
+    return (await prompts({
+      type: "date",
+      name: "value",
+      message,
+      initial: defaultValue,
+      ...opts
+    }))?.value ?? null;
+  }
+  async askForList(message, defaultValue, opts) {
+    return (await prompts({
+      type: "list",
+      name: "value",
+      message,
+      initial: defaultValue,
+      ...opts
+    }))?.value ?? null;
+  }
+  async askForToggle(message, defaultValue, opts) {
+    return (await prompts({
+      type: "toggle",
+      name: "value",
+      message,
+      initial: defaultValue,
+      ...opts
+    }))?.value ?? null;
+  }
+  async askForSelect(message, options, opts) {
+    if (options.length === 0) {
+      throw new Error("No options provided");
+    }
+    const choices = [];
+    for (const option of options) {
+      if (typeof option === "string") {
+        choices.push({ title: option, value: option });
+      } else {
+        choices.push(option);
+      }
+    }
+    const result = await prompts({
+      type: "select",
+      name: "value",
+      message,
+      choices,
+      ...opts
+    });
+    return result?.value ?? null;
+  }
+  newLoader(text = "", chars = ["⠙", "⠘", "⠰", "⠴", "⠤", "⠦", "⠆", "⠃", "⠋", "⠉"], delay = 100) {
+    let loaderText = text;
+    let previousText = null;
+    let x = 0;
+    const interval = setInterval(function() {
+      if (previousText) {
+        process.stdout.write(new TextEncoder().encode("\r" + " ".repeat(previousText.length + 5) + "\r"));
+        previousText = null;
+      }
+      process.stdout.write(new TextEncoder().encode("\r" + chars[x++] + " " + loaderText));
+      x = x % chars.length;
+    }, delay);
+    const stop = () => {
+      clearInterval(interval);
+      process.stdout.write(new TextEncoder().encode("\r" + " ".repeat(loaderText.length + 5) + "\r"));
+    };
+    return {
+      [Symbol.dispose]: stop,
+      [Symbol.asyncDispose]: stop,
+      updateText: (newText) => {
+        previousText = loaderText;
+        loaderText = newText;
+      },
+      stop
+    };
+  }
+}
+class BobError extends Error {
+}
+function getOptionPrimitiveDefaultValue(type) {
+  if (type === "string") return null;
+  if (type === "number") return null;
+  if (type === "boolean") return false;
+  if (Array.isArray(type) && type.length === 1) {
+    if (type[0] === "string") return [];
+    if (type[0] === "number") return [];
+  }
+  throw new Error("Invalid option type: " + type);
+}
+function getOptionDefaultValue(option) {
+  if (typeof option === "string" || Array.isArray(option)) {
+    return getOptionPrimitiveDefaultValue(option);
+  }
+  if (option.default !== void 0) {
+    return option.default;
+  }
+  return getOptionPrimitiveDefaultValue(option.type);
+}
+function getOptionDetails(option) {
+  if (typeof option === "string" || Array.isArray(option)) {
+    return {
+      alias: [],
+      default: getOptionDefaultValue(option),
+      description: "",
+      required: false,
+      secret: false,
+      type: option,
+      variadic: false
+    };
+  }
+  return {
+    alias: option.alias ? Array.isArray(option.alias) ? option.alias : [option.alias] : [],
+    default: option.default ?? getOptionDefaultValue(option.type),
+    description: option.description ?? "",
+    required: option.required ?? false,
+    secret: option.secret ?? false,
+    type: option.type,
+    variadic: option.variadic ?? false
+  };
+}
+class InvalidOption extends BobError {
+  constructor(option, optionsSchema = {}) {
+    super(`Invalid option ${option} in not recognized`);
+    this.option = option;
+    this.optionsSchema = optionsSchema;
+  }
+  pretty(logger) {
+    const options = Object.entries(this.optionsSchema);
+    if (options.length > 0) {
+      logger.log(`
+${chalk.yellow("Available options")}:`);
+      for (const [name, definition] of options) {
+        const details = getOptionDetails(definition);
+        const alias = details.alias ? typeof details.alias === "string" ? [details.alias] : details.alias : [];
+        const typeDisplay = Array.isArray(details.type) ? `[${details.type[0]}]` : details.type;
+        const nameWithAlias = `--${name}${alias.length > 0 ? alias.map((a) => `, -${a}`).join("") : ""}`;
+        const spaces = " ".repeat(30 - nameWithAlias.length);
+        logger.log(`  ${chalk.green(nameWithAlias)} ${spaces} ${details.description || "\b"} ${chalk.white(`(${typeDisplay})`)}`);
+      }
+      logger.log("");
+    }
+    logger.log(`${chalk.white.bgRed(" ERROR ")} Option ${chalk.bold.yellow(this.option)} is not recognized.`);
+  }
+}
+class MissingRequiredArgumentValue extends BobError {
+  constructor(argument) {
+    super(`Argument "${argument}" is required.`);
+    this.argument = argument;
+  }
+  pretty(logger) {
+    logger.log(`${chalk.white.bgRed(" ERROR ")} Argument ${chalk.bold.yellow(this.argument)} is required.`);
+  }
+}
+class MissingRequiredOptionValue extends BobError {
+  constructor(option) {
+    super(`Argument "${option}" is required.`);
+    this.option = option;
+  }
+  pretty(logger) {
+    logger.log(`${chalk.white.bgRed(" ERROR ")} Option ${chalk.bold.yellow(this.option)} is required.`);
+  }
+}
+class BadCommandParameter extends BobError {
+  constructor(param) {
+    let message = `Argument "${param.param}" value is invalid.`;
+    if (param.reason) {
+      message += ` Reason: ${param.reason}`;
+    } else {
+      message += ` Value: "${param.value}"`;
+    }
+    super(message);
+    this.param = param;
+  }
+  pretty(logger) {
+    logger.log(`  ${chalk.white.bgRed(" ERROR ")} Argument ${chalk.bold.yellow(this.param.param)} value is invalid. `);
+    if (this.param.value || this.param.reason) {
+      logger.log("");
+    }
+    if (this.param.value) {
+      logger.log(`  ${chalk.blue("Value")}: ${this.param.value}`);
+    }
+    if (this.param.reason) {
+      logger.log(`  ${chalk.yellow("Reason")}: ${this.param.reason}`);
+    }
+  }
+}
+class BadCommandOption extends BobError {
+  constructor(param) {
+    let message = `Option "${param.option}" value is invalid.`;
+    if (param.reason) {
+      message += ` Reason: ${param.reason}`;
+    } else {
+      message += ` Value: "${param.value}"`;
+    }
+    super(message);
+    this.param = param;
+  }
+  pretty(logger) {
+    logger.log(`  ${chalk.white.bgRed(" ERROR ")} Option ${chalk.bold.yellow(this.param.option)} value is invalid. `);
+    if (this.param.value || this.param.reason) {
+      logger.log("");
+    }
+    if (this.param.value) {
+      logger.log(`  ${chalk.blue("Value")}: ${this.param.value}`);
+    }
+    if (this.param.reason) {
+      logger.log(`  ${chalk.yellow("Reason")}: ${this.param.reason}`);
+    }
+  }
+}
+class CommandNotFoundError extends BobError {
+  constructor(command) {
+    super(`Command "${command}" not found.`);
+    this.command = command;
+  }
+  pretty(logger) {
+    logger.log(`${chalk.bgRed(" ERROR ")} Command ${chalk.yellow(this.command)} not found.`);
+  }
+}
+function convertValue(value, type, name, defaultValue) {
+  if (value === null || value === void 0) {
+    return defaultValue ?? null;
+  }
+  if (type === "string") {
+    return String(value);
+  }
+  if (type === "number") {
+    const num = Number(value);
+    if (isNaN(num)) {
+      throw new BadCommandOption({
+        option: name,
+        reason: `Expected a number, got "${value}"`
+      });
+    }
+    return num;
+  }
+  if (type === "boolean") {
+    if (typeof value === "boolean") return value;
+    if (value === "true" || value === "1") return true;
+    if (value === "false" || value === "0") return false;
+    return Boolean(value);
+  }
+  if (Array.isArray(type)) {
+    const elementType = type[0];
+    const arrayValue = Array.isArray(value) ? value : [value];
+    if (elementType === "string") {
+      return arrayValue.map((v) => String(v));
+    }
+    if (elementType === "number") {
+      return arrayValue.map((v) => {
+        const num = Number(v);
+        if (isNaN(num)) {
+          throw new BadCommandOption({
+            option: name,
+            reason: `Expected array of numbers, got "${v}" in array`
+          });
+        }
+        return num;
+      });
+    }
+  }
+  return value;
+}
+class CommandParser {
+  options;
+  parsedOptions = null;
+  arguments;
+  parsedArguments = null;
+  io;
+  shouldPromptForMissingOptions = true;
+  constructor(opts) {
+    this.options = opts.options;
+    this.arguments = opts.arguments;
+    this.io = opts.io;
+  }
+  // === PUBLIC METHODS ===
+  /**
+   * Parses raw command-line arguments into structured options and arguments
+   * @param args - Raw command line arguments (typically from process.argv.slice(2))
+   * @returns Object containing parsed options and arguments
+   * @throws {InvalidOption} If an naan option is provided
+   * @throws {BadCommandOption} If a value cannot be converted to the expected type
+   */
+  init(args) {
+    const { _: positionalArgs, ...optionValues } = minimist(args);
+    this.validateUnknownOptions(optionValues);
+    this.parsedOptions = this.handleOptions(optionValues);
+    this.parsedArguments = this.handleArguments(positionalArgs);
+    return {
+      options: this.parsedOptions,
+      arguments: this.parsedArguments
+    };
+  }
+  /**
+   * Validates the parsed options and arguments
+   * @throws {Error} If validation fails
+   */
+  async validate() {
+    for (const key in this.options) {
+      const optionDetails = getOptionDetails(this.options[key]);
+      if (optionDetails.required && (this.parsedOptions?.[key] === void 0 || this.parsedOptions?.[key] === null)) {
+        throw new MissingRequiredOptionValue(key);
+      }
+    }
+    for (const key in this.arguments) {
+      const argDetails = getOptionDetails(this.arguments[key]);
+      const value = this.parsedArguments?.[key];
+      if (argDetails.required && (value === void 0 || value === null)) {
+        if (this.shouldPromptForMissingOptions) {
+          const newValue = await this.promptForArgument(key, argDetails);
+          if (newValue && this.parsedArguments) {
+            this.parsedArguments[key] = convertValue(newValue, argDetails.type, key);
+            continue;
+          }
+        }
+        throw new MissingRequiredArgumentValue(key);
+      }
+      if (argDetails.required && argDetails.variadic && Array.isArray(value) && value.length === 0) {
+        if (this.shouldPromptForMissingOptions) {
+          const newValue = await this.promptForArgument(key, argDetails);
+          if (newValue && this.parsedArguments) {
+            this.parsedArguments[key] = convertValue(newValue, argDetails.type, key);
+            continue;
+          }
+        }
+        throw new MissingRequiredArgumentValue(key);
+      }
+    }
+  }
+  /**
+   * Retrieves a parsed option value by name
+   * @param name - The option name
+   * @param defaultValue - Optional default value if option is not set
+   * @returns The typed option value
+   * @throws {Error} If init() has not been called yet
+   */
+  option(name, defaultValue) {
+    if (!this.parsedOptions) {
+      throw new Error("Options have not been parsed yet. Call init() first.");
+    }
+    if (this.isEmptyValue(this.parsedOptions[name]) && defaultValue !== void 0) {
+      return defaultValue;
+    }
+    return this.parsedOptions[name];
+  }
+  setOption(name, value) {
+    if (!this.parsedOptions) {
+      throw new Error("Options have not been parsed yet. Call init() first.");
+    }
+    if (!(name in this.options)) {
+      throw new InvalidOption(name, this.options);
+    }
+    this.parsedOptions[name] = value;
+  }
+  /**
+   * Retrieves a parsed argument value by name
+   * @param name - The argument name
+   * @param defaultValue - Optional default value if argument is not set
+   * @returns The typed argument value
+   * @throws {Error} If init() has not been called yet
+   */
+  argument(name, defaultValue) {
+    if (!this.parsedArguments) {
+      throw new Error("Arguments have not been parsed yet. Call init() first.");
+    }
+    if (this.isEmptyValue(this.parsedArguments[name]) && defaultValue !== void 0) {
+      return defaultValue;
+    }
+    return this.parsedArguments[name];
+  }
+  setArgument(name, value) {
+    if (!this.parsedArguments) {
+      throw new Error("Arguments have not been parsed yet. Call init() first.");
+    }
+    if (!(name in this.arguments)) {
+      throw new InvalidOption(name, this.arguments);
+    }
+    this.parsedArguments[name] = value;
+  }
+  // === PRIVATE HELPERS ===
+  /**
+   * Checks if a value should be considered "empty" for default value purposes
+   * @param value - The value to check
+   * @returns true if the value is null, undefined, or an empty array
+   */
+  isEmptyValue(value) {
+    return value === null || value === void 0 || Array.isArray(value) && value.length === 0;
+  }
+  /**
+   * Validates that all provided options are recognized
+   * @throws {InvalidOption} If an unknown option is found
+   */
+  validateUnknownOptions(optionValues) {
+    const validOptionNames = /* @__PURE__ */ new Set();
+    for (const key in this.options) {
+      validOptionNames.add(key);
+      const optionDetails = getOptionDetails(this.options[key]);
+      for (const alias of optionDetails.alias) {
+        validOptionNames.add(alias);
+      }
+    }
+    for (const optionName in optionValues) {
+      if (!validOptionNames.has(optionName)) {
+        throw new InvalidOption(optionName, this.options);
+      }
+    }
+  }
+  /**
+   * Processes named options from minimist output
+   */
+  handleOptions(optionValues) {
+    const parsedOptions = {};
+    for (const key in this.options) {
+      const optionDetails = getOptionDetails(this.options[key]);
+      parsedOptions[key] = this.resolveOptionValue(key, optionDetails, optionValues);
+    }
+    return parsedOptions;
+  }
+  /**
+   * Processes positional arguments from minimist output
+   */
+  handleArguments(positionalArgs) {
+    const parsedArgs = {};
+    const remainingArgs = [...positionalArgs];
+    for (const key in this.arguments) {
+      const argDefinition = getOptionDetails(this.arguments[key]);
+      if (argDefinition.variadic) {
+        parsedArgs[key] = this.handleVariadicArgument(key, argDefinition, remainingArgs);
+        continue;
+      }
+      parsedArgs[key] = this.resolveArgumentValue(key, argDefinition, remainingArgs.shift());
+    }
+    return parsedArgs;
+  }
+  /**
+   * Handles variadic arguments that consume all remaining positional values
+   */
+  handleVariadicArgument(key, definition, remainingArgs) {
+    return remainingArgs.length ? convertValue(remainingArgs, definition.type, key, definition.default) : definition.default;
+  }
+  /**
+   * Resolves a single positional argument value with defaults and type conversion
+   * Note: Does not validate required arguments - validation happens in subclass validate() methods
+   */
+  resolveArgumentValue(key, definition, argValue) {
+    if (argValue === void 0) {
+      return definition.default;
+    }
+    return convertValue(argValue, definition.type, key, definition.default);
+  }
+  /**
+   * Resolves an option value from the parsed option values object
+   * Handles alias resolution, defaults, and type conversion
+   */
+  resolveOptionValue(key, definition, optionValues) {
+    let rawValue = void 0;
+    const allNames = [key, ...definition.alias];
+    for (const name of allNames) {
+      if (name in optionValues) {
+        rawValue = optionValues[name];
+        break;
+      }
+    }
+    if (rawValue === void 0) {
+      if (definition.required) {
+        throw new BadCommandOption({
+          option: key,
+          reason: `Required option is missing`
+        });
+      }
+      return definition.default;
+    }
+    return convertValue(rawValue, definition.type, key, definition.default);
+  }
+  optionDefinitions() {
+    const defs = {};
+    for (const key in this.options) {
+      defs[key] = getOptionDetails(this.options[key]);
+    }
+    return defs;
+  }
+  argumentDefinitions() {
+    const defs = {};
+    for (const key in this.arguments) {
+      defs[key] = getOptionDetails(this.arguments[key]);
+    }
+    return defs;
+  }
+  availableOptions() {
+    return Object.keys(this.options);
+  }
+  availableArguments() {
+    return Object.keys(this.arguments);
+  }
+  /**
+   * Disables prompting for missing argument values
+   * Useful for non-interactive environments
+   */
+  disablePrompting() {
+    this.shouldPromptForMissingOptions = false;
+    return this;
+  }
+  /**
+   * Prompts the user to provide a missing argument value via CommandIO
+   * Used by validate() when shouldPromptForMissingArgs is enabled
+   * @param argumentName - The name of the missing argument
+   * @param argDef - The argument's definition for type and description
+   * @returns The user-provided value, or null if none given
+   */
+  async promptForArgument(argumentName, argDef) {
+    if (!Array.isArray(argDef.type) && !["string", "number", "secret"].includes(argDef.type)) {
+      return null;
+    }
+    let promptText = `${chalk.yellow.bold(argumentName)} is required`;
+    if (argDef.description) {
+      promptText += `: ${chalk.gray(`(${argDef.description})`)}`;
+    }
+    promptText += ` ${chalk.green(`(${argDef.type}${argDef.variadic == true ? "[]" : ""})`)}
+`;
+    if (Array.isArray(argDef.type)) {
+      promptText += "Please provide one or more values, separated by commas:\n";
+      return await this.io.askForList(promptText, void 0, {
+        separator: ",",
+        validate: (value) => {
+          if (!value.length) {
+            return "Please enter at least one value";
+          }
+          if (argDef.type[0] === "number") {
+            for (const val of value.split(",")) {
+              if (isNaN(Number(val))) {
+                return `Please enter only valid numbers`;
+              }
+            }
+          }
+          return true;
+        }
+      });
+    }
+    return await this.io.askForInput(promptText, void 0, {
+      type: argDef.type === "number" ? "number" : argDef.secret ? "password" : "text",
+      validate: (value) => {
+        if (value === null || value === void 0 || typeof value === "string" && !value.length) {
+          return "This value is required";
+        }
+        if (argDef.type === "number") {
+          const num = Number(value);
+          if (isNaN(num)) {
+            return "Please enter a valid number";
+          }
+        } else if (argDef.type === "string") {
+          if (typeof value !== "string" || !value.length) {
+            return "Please enter a valid text";
+          }
+        }
+        return true;
+      }
+    });
+  }
+}
+function generateSpace(nb) {
+  return new Array(nb + 5).join(" ");
+}
+class HelpOption {
+  type = "boolean";
+  option = "help";
+  alias = ["h"];
+  default = false;
+  description = `Display help for the given command. When no command is given display help for the ${chalk.green("list")} command`;
+  async handler() {
+    const argumentDefinitions = this.parser.argumentDefinitions();
+    const optionDefinitions = this.parser.optionDefinitions();
+    const availableArguments = Object.entries(argumentDefinitions);
+    const availableOptions = Object.entries(optionDefinitions);
+    const optionsWithAlias = availableOptions.map(([name, signature]) => {
+      const aliases = Array.isArray(signature.alias) ? signature.alias : signature.alias ? [signature.alias] : [];
+      return {
+        name,
+        ...signature,
+        optionWithAlias: `--${name}${aliases.map((a) => `, -${a}`).join("")}`
+      };
+    });
+    const requiredArguments = availableArguments.filter(([, signature]) => signature.required);
+    this.io.log(chalk.yellow("Description:"));
+    this.io.log(`  ${this.description}
+`);
+    this.io.log(chalk.yellow("Usage:"));
+    this.io.log(`  ${this.command} ${requiredArguments.length > 0 ? requiredArguments.map(([name]) => `<${name}>`).join(" ") : "\b"} [options]`);
+    const maxOptionLength = Math.max(...optionsWithAlias.map((opt) => opt.optionWithAlias.length), 0);
+    const maxArgumentLength = Math.max(...availableArguments.map(([name]) => name.length), 0);
+    const maxLength = maxArgumentLength > maxOptionLength ? maxArgumentLength : maxOptionLength;
+    if (availableArguments.length > 0) {
+      this.io.log(`
+${chalk.yellow("Arguments")}:`);
+      for (const [name, signature] of availableArguments) {
+        const spaces = generateSpace(maxLength - name.length);
+        let message = `  ${chalk.green(name)} ${spaces} ${signature.description ?? "\b"}`;
+        if (signature.default !== void 0 && !signature.required) {
+          const typeDisplay = Array.isArray(signature.type) ? `[${signature.type[0]}]` : signature.type;
+          const defaultValue = typeDisplay === "array" || Array.isArray(signature.type) ? JSON.stringify(signature.default) : signature.default;
+          message += ` ${chalk.yellow(`[default: ${defaultValue}]`)}`;
+        }
+        if (signature.variadic) {
+          message += ` ${chalk.white("(variadic)")}`;
+        }
+        this.io.log(message);
+      }
+    }
+    if (availableOptions.length > 0) {
+      this.io.log(`
+${chalk.yellow("Options")}:`);
+      for (const signature of optionsWithAlias) {
+        const spaces = generateSpace(maxLength - signature.optionWithAlias.length);
+        let message = `${chalk.green(signature.optionWithAlias)} ${spaces} ${signature.description ?? "\b"}`;
+        if (signature.type) {
+          const typeDisplay = Array.isArray(signature.type) ? `[${signature.type[0]}]` : signature.type;
+          message += ` ${chalk.white(`(${typeDisplay})`)}`;
+        }
+        if (signature.default !== void 0 && !signature.required) {
+          const typeDisplay = Array.isArray(signature.type) ? `[${signature.type[0]}]` : signature.type;
+          const defaultValue = typeDisplay === "array" || Array.isArray(signature.type) ? JSON.stringify(signature.default) : signature.default;
+          message += ` ${chalk.yellow(`[default: ${defaultValue}]`)}`;
+        }
+        this.io.log(message);
+      }
+    }
+    if (this.commandsExamples.length > 0) {
+      this.io.log(`
+${chalk.yellow("Examples")}:`);
+      let binaryName = process.argv[0].split("/").pop();
+      if (binaryName === "node") {
+        binaryName += " " + process.argv[1].split("/").pop();
+      }
+      for (const [index, example] of this.commandsExamples.entries()) {
+        if (index > 0) {
+          this.io.log("");
+        }
+        this.io.log(`  ${example.description}
+`);
+        this.io.log(`    ${chalk.green(`${binaryName} ${example.command}`)}`);
+      }
+    }
+    return -1;
+  }
+}
+class Command {
+  _command;
+  description;
+  group;
+  commandsExamples = [];
+  get command() {
+    return this._command;
+  }
+  ctx;
+  io;
+  parser;
+  disablePromptingFlag = false;
+  _preHandler;
+  _handler;
+  tmp;
+  defaultOptions() {
+    return [new HelpOption()];
+  }
+  newCommandParser(opts) {
+    return new CommandParser({
+      io: opts.io,
+      options: opts.options,
+      arguments: opts.arguments
+    });
+  }
+  newCommandIO(opts) {
+    return new CommandIO(opts);
+  }
+  constructor(command, opts) {
+    this._command = command;
+    this.description = opts?.description ?? "";
+    this.group = opts?.group;
+    this.tmp = {
+      options: opts?.options ?? {},
+      arguments: opts?.arguments ?? {}
+    };
+    const defaultOptions = this.defaultOptions();
+    if (defaultOptions.length > 0) {
+      for (const option of defaultOptions) {
+        this.tmp.options[option.option] = option;
+      }
+    }
+  }
+  disablePrompting() {
+    this.disablePromptingFlag = true;
+    return this;
+  }
+  preHandler(handler) {
+    this._preHandler = handler;
+    return this;
+  }
+  handler(handler) {
+    this._handler = handler;
+    return this;
+  }
+  options(opts) {
+    this.tmp = {
+      options: {
+        ...this.tmp?.options ?? {},
+        ...opts
+      },
+      arguments: this.tmp?.arguments ?? {}
+    };
+    return this;
+  }
+  arguments(args) {
+    this.tmp = {
+      options: this.tmp?.options ?? {},
+      arguments: {
+        ...this.tmp?.arguments ?? {},
+        ...args
+      }
+    };
+    return this;
+  }
+  async run(opts) {
+    if (!this._handler && !this.handle) {
+      throw new Error(`No handler defined for command ${this.command || "(unknown)"}`);
+    }
+    let handlerOptions;
+    this.ctx = opts.ctx;
+    this.io = this.newCommandIO({
+      logger: opts.logger
+    });
+    if (opts && "args" in opts) {
+      const options = this.tmp?.options ?? {};
+      for (const option of this.defaultOptions()) {
+        if (!(option.option in options)) {
+          options[option.option] = option;
+        }
+      }
+      this.parser = this.newCommandParser({
+        io: this.io,
+        options,
+        arguments: this.tmp?.arguments ?? {}
+      });
+      handlerOptions = this.parser.init(opts.args);
+      for (const option of this.defaultOptions()) {
+        if (handlerOptions.options[option.option] === true) {
+          const code = await option.handler.call(this);
+          if (code && code !== 0) {
+            return code;
+          }
+        }
+      }
+      if (this.disablePromptingFlag) {
+        this.parser.disablePrompting();
+      }
+      await this.parser.validate();
+    } else {
+      handlerOptions = {
+        options: opts.options,
+        arguments: opts.arguments
+      };
+    }
+    if (!this._preHandler && this.preHandle) {
+      this._preHandler = this.preHandle.bind(this);
+    }
+    if (this._preHandler) {
+      const preHandlerResult = await this._preHandler(opts.ctx, handlerOptions);
+      if (preHandlerResult && preHandlerResult !== 0) {
+        return preHandlerResult;
+      }
+    }
+    if (!this._handler && this.handle) {
+      this._handler = this.handle.bind(this);
+    } else if (!this._handler) {
+      throw new Error(`No handler defined for command ${this.command || "(unknown)"}`);
+    }
+    const res = await this._handler(opts.ctx, handlerOptions);
+    return res ?? 0;
+  }
+}
+class CommandSignatureParser extends CommandParser {
+  command;
+  constructor(opts) {
+    const parseResult = CommandSignatureParser.parseSignature(opts.signature, opts.helperDefinitions, opts.defaultOptions);
+    super({
+      io: opts.io,
+      options: parseResult.options,
+      arguments: parseResult.arguments
+    });
+    this.command = parseResult.command;
+  }
+  /**
+   * Parses command signature string into command name and parameter schemas
+   * Example: "migrate {name} {--force}" -> { command: "migrate", arguments: {name: ...}, options: {force: ...} }
+   */
+  static parseSignature(signature, helperDefinitions, defaultCommandOptions) {
+    const [command, ...signatureParams] = signature.split(/\{(.*?)\}/g).map((param) => param.trim()).filter(Boolean);
+    const optionsSchema = {};
+    const argumentsSchema = {};
+    for (const paramSignature of signatureParams) {
+      const { name, isOption, definition } = CommandSignatureParser.parseParamSignature(paramSignature, helperDefinitions);
+      if (isOption) {
+        optionsSchema[name] = definition;
+      } else {
+        argumentsSchema[name] = definition;
+      }
+    }
+    for (const option of defaultCommandOptions) {
+      optionsSchema[option.option] = {
+        type: option.type,
+        required: option.required,
+        alias: option.alias,
+        variadic: option.variadic ?? false,
+        description: option.description,
+        default: option.default ?? null
+      };
+    }
+    return {
+      command,
+      options: optionsSchema,
+      arguments: argumentsSchema
+    };
+  }
+  /**
+   * Parses a single parameter signature like "{name}" or "{--force}" or "{files*}"
+   * Extracts name, type, default value, aliases, description, etc.
+   *
+   * Signature syntax:
+   * - {arg}          -> required string argument
+   * - {arg?}         -> optional argument
+   * - {arg=default}  -> argument with default value
+   * - {arg*}         -> variadic argument (array)
+   * - {arg:desc}     -> argument with description
+   * - {--opt}        -> boolean option
+   * - {--opt=}       -> string option
+   * - {--opt|o}      -> option with alias
+   */
+  static parseParamSignature(paramSignature, helperDefinitions) {
+    let name = paramSignature;
+    let isOption = false;
+    const definition = {
+      required: true,
+      type: "string",
+      description: void 0,
+      default: null,
+      variadic: false
+    };
+    if (name.includes(":")) {
+      const [paramName, description] = name.split(":");
+      name = paramName.trim();
+      definition.description = description.trim();
+    }
+    if (name.includes("=")) {
+      const [paramName, defaultValue] = name.split("=");
+      name = paramName.trim();
+      definition.default = defaultValue.trim();
+      definition.required = false;
+      if (typeof definition.default === "string" && !definition.default.length) {
+        definition.default = null;
+      } else if (definition.default === "true") {
+        definition.default = true;
+        definition.type = "boolean";
+      } else if (definition.default === "false") {
+        definition.default = false;
+        definition.type = "boolean";
+      }
+    } else if (name.startsWith("--")) {
+      definition.required = false;
+      definition.default = false;
+      definition.type = "boolean";
+    }
+    if (name.includes("|")) {
+      const [paramName, ...aliases] = name.split("|");
+      name = paramName.trim();
+      definition.alias = aliases.map((a) => a.trim());
+    }
+    if (name.startsWith("--")) {
+      isOption = true;
+      name = name.slice(2);
+    }
+    if (definition.default === "*") {
+      definition.default = [];
+      definition.type = ["string"];
+    }
+    if (name.endsWith("?")) {
+      definition.required = false;
+      name = name.slice(0, -1);
+    }
+    if (name.endsWith("*")) {
+      definition.type = ["string"];
+      definition.variadic = true;
+      definition.default = [];
+      name = name.slice(0, -1);
+    }
+    definition.description = definition.description ?? helperDefinitions[name] ?? helperDefinitions[`--${name}`];
+    return { name, isOption, definition };
+  }
+}
+class CommandWithSignature extends Command {
+  helperDefinitions = {};
+  get command() {
+    if (this.parser) {
+      return this.parser.command;
+    }
+    return this.signature.split(" ")[0];
+  }
+  newCommandParser(opts) {
+    return new CommandSignatureParser({
+      io: opts.io,
+      signature: this.signature,
+      helperDefinitions: this.helperDefinitions,
+      defaultOptions: this.defaultOptions()
+    });
+  }
+  constructor() {
+    super("");
+  }
+  option(key, defaultValue = null) {
+    return this.parser.option(key, defaultValue);
+  }
+  argument(key, defaultValue = null) {
+    return this.parser.argument(key, defaultValue);
+  }
+  // Prompt utils
+  async askForConfirmation(...opts) {
+    return this.io.askForConfirmation(...opts);
+  }
+  async askForInput(...opts) {
+    return this.io.askForInput(...opts);
+  }
+  async askForSelect(...opts) {
+    return this.io.askForSelect(...opts);
+  }
+  newLoader(...opts) {
+    return this.io.newLoader(...opts);
+  }
+}
+class Logger {
+  level;
+  constructor(opts = {}) {
+    this.level = opts.level ?? "info";
+  }
+  shouldLog(level) {
+    const levels = ["debug", "info", "warn", "error"];
+    const currentLevelIndex = levels.indexOf(this.level);
+    const messageLevelIndex = levels.indexOf(level);
+    return messageLevelIndex >= currentLevelIndex;
+  }
+  setLevel(level) {
+    this.level = level;
+  }
+  getLevel() {
+    return this.level;
+  }
+  log(...args) {
+    console.log(...args);
+  }
+  info(...args) {
+    if (this.shouldLog("info")) {
+      console.log(...args);
+    }
+  }
+  warn(...args) {
+    if (this.shouldLog("warn")) {
+      console.warn(...args);
+    }
+  }
+  error(...args) {
+    if (this.shouldLog("error")) {
+      console.error(...args);
+    }
+  }
+  debug(...args) {
+    if (this.shouldLog("debug")) {
+      console.log(...args);
+    }
+  }
+}
+class StringSimilarity {
+  /**
+   * Generate bigrams (character pairs) from a string
+   */
+  getBigrams(str) {
+    const bigrams = [];
+    const normalized = str.toLowerCase();
+    for (let i = 0; i < normalized.length - 1; i++) {
+      bigrams.push(normalized.slice(i, i + 2));
+    }
+    return bigrams;
+  }
+  /**
+   * Calculate Dice's Coefficient similarity between two strings (0-1 scale)
+   */
+  calculateSimilarity(str1, str2) {
+    if (str1 === str2) return 1;
+    if (str1.length < 2 || str2.length < 2) return 0;
+    const bigrams1 = this.getBigrams(str1);
+    const bigrams2 = this.getBigrams(str2);
+    const bigrams2Set = new Set(bigrams2);
+    let matches = 0;
+    for (const bigram of bigrams1) {
+      if (bigrams2Set.has(bigram)) {
+        matches++;
+        bigrams2Set.delete(bigram);
+      }
+    }
+    return 2 * matches / (bigrams1.length + bigrams2.length);
+  }
+  /**
+   * Find best matching string and ratings for all candidates
+   */
+  findBestMatch(target, candidates) {
+    const ratings = candidates.map((candidate) => ({
+      target: candidate,
+      rating: this.calculateSimilarity(target, candidate)
+    }));
+    let bestMatchIndex = 0;
+    let bestRating = ratings[0]?.rating ?? 0;
+    for (let i = 1; i < ratings.length; i++) {
+      if (ratings[i].rating > bestRating) {
+        bestRating = ratings[i].rating;
+        bestMatchIndex = i;
+      }
+    }
+    return {
+      ratings,
+      bestMatch: ratings[bestMatchIndex],
+      bestMatchIndex
+    };
+  }
+}
+class CommandRegistry {
+  commands = {};
+  io;
+  logger;
+  stringSimilarity;
+  newCommandIO(opts) {
+    return new CommandIO(opts);
+  }
+  constructor(opts) {
+    this.logger = opts?.logger ?? new Logger();
+    this.io = this.newCommandIO({
+      logger: this.logger
+    });
+    this.stringSimilarity = opts?.stringSimilarity ?? new StringSimilarity();
+  }
+  getAvailableCommands() {
+    return Object.keys(this.commands);
+  }
+  getCommands() {
+    return Object.values(this.commands);
+  }
+  importFile = async (filePath) => {
+    return (await import(filePath)).default;
+  };
+  commandResolver = async (path2) => {
+    let defaultImport = await this.importFile(path2);
+    if (!defaultImport) {
+      return null;
+    }
+    if (defaultImport && typeof defaultImport === "object" && "default" in defaultImport) {
+      defaultImport = defaultImport.default;
+    }
+    if (typeof defaultImport === "function") {
+      return new defaultImport();
+    } else if (defaultImport instanceof Command) {
+      return defaultImport;
+    }
+    return null;
+  };
+  withCommandResolver(resolver) {
+    this.commandResolver = resolver;
+    return this;
+  }
+  withFileImporter(importer) {
+    this.importFile = importer;
+    return this;
+  }
+  registerCommand(command, force = false) {
+    const commandName = command.command;
+    if (!commandName) {
+      throw new Error("Command signature is invalid, it must have a command name.");
+    }
+    if (!force && this.commands[commandName]) {
+      throw new Error(`Command ${commandName} already registered.`);
+    }
+    this.commands[commandName] = command;
+  }
+  async loadCommandsPath(commandsPath) {
+    const commandsStream = this.listCommandsFiles(commandsPath);
+    for await (const file of commandsStream) {
+      try {
+        const command = await this.commandResolver(file);
+        if (command instanceof Command) {
+          this.registerCommand(command);
+        }
+      } catch (e) {
+        throw new Error(`Command ${file} failed to load. ${e}`, {
+          cause: e
+        });
+      }
+    }
+  }
+  async runCommand(ctx, command, ...args) {
+    const commandToRun = typeof command === "string" ? this.commands[command] : command;
+    const commandSignature = typeof command === "string" ? command : commandToRun.command;
+    if (!commandToRun) {
+      const suggestedCommand = await this.suggestCommand(commandSignature);
+      if (suggestedCommand) {
+        return await this.runCommand(ctx, suggestedCommand, ...args);
+      }
+      return 1;
+    }
+    return await commandToRun.run({
+      ctx,
+      logger: this.logger,
+      args
+    }) ?? 0;
+  }
+  async suggestCommand(command) {
+    const availableCommands = this.getAvailableCommands();
+    const { bestMatch, bestMatchIndex, ratings } = this.stringSimilarity.findBestMatch(command, availableCommands);
+    const similarCommands = ratings.filter((r) => r.rating > 0.3).map((r) => r.target);
+    if (bestMatch.rating > 0 && similarCommands.length <= 1 || bestMatch.rating > 0.7 && similarCommands.length > 1) {
+      const commandToAsk = availableCommands[bestMatchIndex];
+      const runCommand = await this.askRunSimilarCommand(command, commandToAsk);
+      if (runCommand) {
+        return commandToAsk;
+      } else {
+        return null;
+      }
+    }
+    if (similarCommands.length) {
+      this.io.error(`${chalk.bgRed(" ERROR ")} Command ${chalk.yellow(command)} not found.
+`);
+      const commandToRun = await this.io.askForSelect(chalk.green("Did you mean to run one of these commands instead?"), similarCommands);
+      if (commandToRun) {
+        return commandToRun;
+      }
+    }
+    throw new CommandNotFoundError(command);
+  }
+  async askRunSimilarCommand(command, commandToAsk) {
+    this.io.error(`${chalk.bgRed(" ERROR ")} Command ${chalk.yellow(command)} not found.
+`);
+    return this.io.askForConfirmation(`${chalk.green(`Do you want to run ${chalk.yellow(commandToAsk)} instead?`)} `);
+  }
+  async *listCommandsFiles(basePath) {
+    console.log(fs);
+    const dirEntry = fs.readdirSync(basePath, { withFileTypes: true });
+    console.log(dirEntry);
+    for (const dirent of dirEntry) {
+      const direntPath = path.resolve(basePath, dirent.name);
+      if (dirent.isDirectory()) {
+        yield* this.listCommandsFiles(path.resolve(basePath, dirent.name));
+      } else {
+        if (!direntPath.endsWith(`.ts`) && !direntPath.endsWith(`.js`) && !direntPath.endsWith(`.mjs`) && !direntPath.endsWith(`.cjs`)) {
+          continue;
+        }
+        yield direntPath;
+      }
+    }
+  }
+}
+class ExceptionHandler {
+  logger;
+  constructor(logger) {
+    this.logger = logger;
+  }
+  handle(err) {
+    if (err instanceof BobError) {
+      err.pretty(this.logger);
+      return -1;
+    }
+    throw err;
+  }
+}
+class HelpCommand extends Command {
+  constructor(opts) {
+    super("help", {
+      description: chalk.bold("Show help information about the CLI and its commands")
+    });
+    this.opts = opts;
+  }
+  async handle() {
+    const commands = this.opts.commandRegistry.getCommands();
+    const cliName = this.opts.cliName ?? "Bob CLI";
+    const version = this.opts.cliVersion ?? "0.0.0";
+    const coreVersion = (await import("./package-CnNxf727.js"))?.default?.version ?? "0.0.0";
+    this.io.log(`${cliName} ${chalk.green(version)} (core: ${chalk.yellow(coreVersion)})
+
+${chalk.yellow("Usage")}:
+  command [options] [arguments]
+
+${chalk.yellow("Available commands")}:
+`);
+    const maxCommandLength = Math.max(...commands.map((command) => command.command.length)) ?? 0;
+    const commandByGroups = {};
+    for (const command of commands) {
+      const commandGroup = command.group ?? command.command.split(":")[0];
+      if (!commandByGroups[commandGroup]) {
+        commandByGroups[commandGroup] = [];
+      }
+      commandByGroups[commandGroup].push(command);
+    }
+    const sortedCommandsByGroups = Object.entries(commandByGroups).sort(([groupA], [groupB]) => groupA.toLowerCase().localeCompare(groupB.toLowerCase())).sort(([, commandsA], [, commandsB]) => commandsA.length - commandsB.length);
+    for (const [group, groupCommands] of sortedCommandsByGroups) {
+      const isGrouped = groupCommands.length > 1;
+      if (isGrouped) {
+        this.io.log(chalk.yellow(`${group}:`));
+      }
+      const sortedGroupCommands = groupCommands.sort((a, b) => a.command.toLowerCase().localeCompare(b.command.toLowerCase()));
+      for (const command of sortedGroupCommands) {
+        let spaces = generateSpace(maxCommandLength - command.command.length);
+        if (isGrouped) {
+          spaces = spaces.slice(2);
+        }
+        this.io.log(`${isGrouped ? "  " : ""}${chalk.green(command.command)} ${spaces} ${command.description}`);
+      }
+    }
+  }
+}
+class Cli {
+  ctx;
+  logger;
+  commandRegistry;
+  exceptionHandler;
+  helpCommand;
+  newCommandRegistry(opts) {
+    return new CommandRegistry(opts);
+  }
+  newHelpCommand(opts) {
+    return new HelpCommand(opts);
+  }
+  newExceptionHandler(opts) {
+    return new ExceptionHandler(opts.logger);
+  }
+  constructor(opts = {}) {
+    this.ctx = opts.ctx;
+    this.logger = opts.logger ?? new Logger();
+    this.commandRegistry = this.newCommandRegistry({
+      logger: this.logger
+    });
+    this.exceptionHandler = this.newExceptionHandler({
+      logger: this.logger
+    });
+    this.helpCommand = this.newHelpCommand({
+      cliName: opts.name,
+      cliVersion: opts.version,
+      commandRegistry: this.commandRegistry
+    });
+  }
+  withCommandResolver(resolver) {
+    this.commandRegistry.withCommandResolver(resolver);
+    return this;
+  }
+  withFileImporter(importer) {
+    this.commandRegistry.withFileImporter(importer);
+    return this;
+  }
+  async withCommands(...commands) {
+    for (const command of commands) {
+      if (typeof command === "string") {
+        await this.commandRegistry.loadCommandsPath(command);
+      } else {
+        if (typeof command === "function") {
+          this.registerCommand(new command());
+        } else {
+          this.registerCommand(command);
+        }
+      }
+    }
+  }
+  async runCommand(command, ...args) {
+    if (!command) {
+      return await this.runHelpCommand();
+    }
+    return await this.commandRegistry.runCommand(this.ctx ?? {}, command, ...args).catch(this.exceptionHandler.handle.bind(this.exceptionHandler));
+  }
+  async runHelpCommand() {
+    return await this.runCommand(this.helpCommand);
+  }
+  registerCommand(command) {
+    this.commandRegistry.registerCommand(command);
+  }
+}
+export {
+  BadCommandOption,
+  BadCommandParameter,
+  BobError,
+  Cli,
+  Command,
+  CommandIO,
+  CommandNotFoundError,
+  CommandParser,
+  CommandRegistry,
+  CommandSignatureParser,
+  CommandWithSignature,
+  ExceptionHandler,
+  HelpOption,
+  InvalidOption,
+  Logger,
+  MissingRequiredArgumentValue,
+  MissingRequiredOptionValue,
+  StringSimilarity
+};