@bemoje/cli 1.1.0 → 2.0.0

package/index.mjs

@@ -0,0 +1,1352 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/lib/Command.ts
+var Command_exports = {};
+__export(Command_exports, {
+  Command: () => Command
+});
+
+// ../array/src/arrLast.ts
+function arrLast(array) {
+  if (!array.length) throw new Error("Cannot get last element of empty array.");
+  return array[array.length - 1];
+}
+__name(arrLast, "arrLast");
+
+// ../array/src/arrRemoveDuplicates.ts
+function arrRemoveDuplicates(array) {
+  return Array.from(new Set(array));
+}
+__name(arrRemoveDuplicates, "arrRemoveDuplicates");
+
+// ../object/src/entriesOf.ts
+function entriesOf(obj) {
+  return Object.entries(obj);
+}
+__name(entriesOf, "entriesOf");
+
+// ../object/src/keysOf.ts
+function keysOf(obj) {
+  return Object.keys(obj);
+}
+__name(keysOf, "keysOf");
+
+// ../object/src/defineValue.ts
+function defineValue(obj, key, value, des = {}) {
+  return Object.defineProperty(obj, key, {
+    configurable: true,
+    value,
+    enumerable: true,
+    ...des
+  });
+}
+__name(defineValue, "defineValue");
+
+// ../object/src/filterObject.ts
+function filterObject(obj, predicate) {
+  const accum = {};
+  for (const key of keysOf(obj)) {
+    if (predicate(obj[key], key, obj)) {
+      accum[key] = obj[key];
+    }
+  }
+  return accum;
+}
+__name(filterObject, "filterObject");
+
+// ../map/src/mapGetOrDefault.ts
+function mapGetOrDefault(map, key, factory) {
+  let value = map.get(key);
+  if (value !== void 0 || map.has(key)) return value;
+  value = factory(key, map);
+  map.set(key, value);
+  return value;
+}
+__name(mapGetOrDefault, "mapGetOrDefault");
+
+// ../map/src/TimeoutWeakMap.ts
+var TimeoutWeakMap = class {
+  /**
+   * @param timeoutMs Default timeout in milliseconds for entries
+   */
+  constructor(timeoutMs) {
+    this.timeoutMs = timeoutMs;
+  }
+  static {
+    __name(this, "TimeoutWeakMap");
+  }
+  wmap = /* @__PURE__ */ new WeakMap();
+  /**
+   * Retrieves the value for the given key and refreshes its timeout.
+   *
+   * @param key The key to retrieve
+   * @returns The value if found, undefined otherwise
+   */
+  get(key) {
+    const vt = this.wmap.get(key);
+    if (!vt) return void 0;
+    const [value, timeout] = vt;
+    timeout.refresh();
+    return value;
+  }
+  /**
+   * Sets a key-value pair with an optional custom timeout.
+   *
+   * @param key The key to set
+   * @param value The value to associate with the key
+   * @param timeoutMs Optional timeout override for this entry
+   * @returns This instance for chaining
+   */
+  set(key, value, timeoutMs) {
+    this.wmap.set(key, [
+      value,
+      setTimeout(() => {
+        this.delete(key);
+      }, timeoutMs ?? this.timeoutMs).unref()
+    ]);
+    return this;
+  }
+  /**
+   * Removes a key-value pair and clears its timeout.
+   *
+   * @param key The key to delete
+   * @returns True if the key existed and was deleted, false otherwise
+   */
+  delete(key) {
+    const vt = this.wmap.get(key);
+    if (!vt) return false;
+    const timeout = vt[1];
+    clearTimeout(timeout);
+    return this.wmap.delete(key);
+  }
+  /**
+   * Checks if a key exists in the map.
+   * Does not refresh the timeout.
+   *
+   * @param key The key to check
+   * @returns True if the key exists, false otherwise
+   */
+  has(key) {
+    return this.wmap.has(key);
+  }
+  /**
+   * Loads multiple key-value pairs into the map.
+   *
+   * @param entries Iterable of key-value pairs to load
+   * @param timeoutMs Optional timeout override for all entries
+   * @returns This instance for chaining
+   */
+  load(entries, timeoutMs) {
+    for (const [key, value] of entries) {
+      this.set(key, value, timeoutMs);
+    }
+    return this;
+  }
+  /**
+   * Updates an existing value or creates a new one using an update function.
+   *
+   * @param key The key to update
+   * @param update Function that receives the current value and returns the new value
+   * @returns This instance for chaining
+   */
+  update(key, update) {
+    return this.set(key, update(this.get(key), key, this));
+  }
+  /**
+   * Gets a value or creates it using a factory function if it doesn't exist.
+   * Refreshes timeout if the value exists.
+   *
+   * @param key The key to get or create
+   * @param factory Function to create the value if it doesn't exist
+   * @param timeoutMs Optional timeout override for new entries
+   * @returns The existing or newly created value
+   */
+  getOrDefault(key, factory, timeoutMs) {
+    const vt = this.wmap.get(key);
+    if (vt) {
+      const [value, timeout] = vt;
+      timeout.refresh();
+      return value;
+    } else {
+      const value = factory(key, this);
+      this.set(key, value, timeoutMs);
+      return value;
+    }
+  }
+};
+
+// ../object/src/objSortKeys.ts
+function objSortKeys(o, compare) {
+  const entries = Object.entries(o);
+  if (compare) entries.sort(compare);
+  else entries.sort((a, b) => a[0].localeCompare(b[0]));
+  return Object.fromEntries(entries);
+}
+__name(objSortKeys, "objSortKeys");
+
+// ../object/src/valuesOf.ts
+function valuesOf(obj) {
+  return Object.values(obj);
+}
+__name(valuesOf, "valuesOf");
+
+// ../fn/src/setName.ts
+function setName(name, target) {
+  return defineValue(target, "name", typeof name === "string" ? name : name.name, { enumerable: false });
+}
+__name(setName, "setName");
+
+// src/lib/internal/collectVariadicOptionValues.ts
+function collectVariadicOptionValues(parsed, options) {
+  for (let i = 0; i < parsed.tokens.length; i++) {
+    const token = parsed.tokens[i];
+    if (token.kind !== "option") continue;
+    const def = options.find((o) => o.name === token.name);
+    if (!def?.variadic || def.type !== "string") continue;
+    const values = [token.value];
+    let j = i + 1;
+    while (j < parsed.tokens.length && parsed.tokens[j].kind === "positional") {
+      const positionalToken = parsed.tokens[j];
+      values.push(positionalToken.value);
+      const posIndex = parsed.positionals.indexOf(positionalToken.value);
+      if (posIndex !== -1) parsed.positionals.splice(posIndex, 1);
+      j++;
+    }
+    Reflect.set(
+      parsed.values,
+      token.name,
+      values.filter((v) => v !== void 0)
+    );
+  }
+}
+__name(collectVariadicOptionValues, "collectVariadicOptionValues");
+
+// src/lib/internal/mergeOptionDefaults.ts
+function mergeOptionDefaults(values, options) {
+  for (const option of options) {
+    if (option.defaultValue !== void 0 && option.name in values) {
+      values[option.name] ??= option.defaultValue;
+    }
+  }
+}
+__name(mergeOptionDefaults, "mergeOptionDefaults");
+
+// src/lib/internal/normalizeArgv.ts
+function normalizeArgv(argv, options) {
+  for (const o of options) {
+    if (o.long === o.name) continue;
+    argv = argv.map((a) => {
+      if (a === `--${o.long}`) return `--${o.name}`;
+      if (a === `--no-${o.long}`) return `--no-${o.name}`;
+      return a;
+    });
+  }
+  return argv;
+}
+__name(normalizeArgv, "normalizeArgv");
+
+// src/lib/internal/resolveArguments.ts
+function resolveArguments(positionals, args) {
+  const result = args.map((arg, index) => {
+    if (arg.variadic) {
+      const remaining = positionals.slice(index);
+      return remaining.length > 0 ? remaining : arg.defaultValue;
+    }
+    return positionals[index] ?? arg.defaultValue;
+  });
+  while (result.length && arrLast(result) === void 0) result.pop();
+  return result;
+}
+__name(resolveArguments, "resolveArguments");
+
+// src/lib/internal/validateParsed.ts
+function validateParsed(args, optionValues, argDefs, optionDefs) {
+  return argDefs.map((def, index) => {
+    const value = args[index];
+    if (def.required) {
+      if (def.variadic ? Array.isArray(value) && value.length === 0 : value === void 0) {
+        return `Missing argument [${index}] ${def.usage}`;
+      }
+    }
+    if (def.choices && value !== void 0) {
+      if (![value].flat().every((v) => def.choices.includes(v))) {
+        return `Invalid argument [${index}] ${def.usage}: Got \`${value}\`. Accepted values: [${def.choices.map((c) => `\`${c}\``).join(",")}]`;
+      }
+    }
+  }).concat(
+    entriesOf(optionValues).map(([key, value]) => {
+      const def = optionDefs.find((o) => o.name === key);
+      if (!def) return `Unknown option --${key}`;
+      if (def.choices && value !== void 0) {
+        if (!(def.variadic ? value : [value]).every((v) => def.choices.includes(v))) {
+          return `Invalid option value ${def.flags}: Got \`${value}\`. Accepted values: [${def.choices.map((c) => `\`${c}\``).join(",")}]`;
+        }
+      }
+    })
+  ).filter((s) => s !== void 0).reduce(
+    (acc, curr) => {
+      return (acc ?? []).concat(curr);
+    },
+    void 0
+  );
+}
+__name(validateParsed, "validateParsed");
+
+// ../string/src/lib/strFirstCharToUpperCase.ts
+function strFirstCharToUpperCase(string) {
+  return string.charAt(0).toUpperCase() + string.substring(1);
+}
+__name(strFirstCharToUpperCase, "strFirstCharToUpperCase");
+
+// src/lib/Command.ts
+import colors3 from "ansi-colors";
+import { inspect, parseArgs } from "node:util";
+
+// src/lib/Help.ts
+var Help_exports = {};
+__export(Help_exports, {
+  Help: () => Help
+});
+
+// ../decorators/src/assertDescriptorValueIsFunction.ts
+function assertDescriptorValueIsFunction(key, descriptor) {
+  if (!(typeof descriptor.value === "function" && descriptor.value !== Function.prototype)) {
+    throw new TypeError(`"value" not a function for ${key} with descriptor: ${JSON.stringify(descriptor)}.`);
+  }
+}
+__name(assertDescriptorValueIsFunction, "assertDescriptorValueIsFunction");
+
+// ../decorators/src/lazyProp.ts
+import { isFunction } from "es-toolkit/predicate";
+import { ms as ms2 } from "enhanced-ms";
+
+// ../decorators/src/memoizeSync.ts
+import memoizee from "memoizee";
+import { ms } from "enhanced-ms";
+function memoizeSync(arg = {}) {
+  const opts = typeof arg === "object" ? arg : { maxAge: typeof arg === "number" ? arg : ms(arg) };
+  return /* @__PURE__ */ __name(function decorator(target, key, descriptor) {
+    if (!descriptor) throw new TypeError("descriptor is undefined");
+    const orig = descriptor.value;
+    assertDescriptorValueIsFunction(key, descriptor);
+    const options = { length: false, ...opts };
+    if (opts.instancesShareCache) {
+      Reflect.deleteProperty(options, "instancesShareCache");
+      descriptor.value = memoizee(orig, options);
+    } else {
+      const wmap = /* @__PURE__ */ new WeakMap();
+      descriptor.value = function(...args) {
+        const memoized = mapGetOrDefault(wmap, this, () => memoizee(orig, options));
+        return memoized.apply(this, args);
+      };
+    }
+    return descriptor;
+  }, "decorator");
+}
+__name(memoizeSync, "memoizeSync");
+
+// ../decorators/src/lazyProp.ts
+function lazyProp(targetOrTimeout, key, descriptor) {
+  if (typeof targetOrTimeout === "number" || typeof targetOrTimeout === "string") {
+    const maxAge = typeof targetOrTimeout === "number" ? targetOrTimeout : ms2(targetOrTimeout);
+    return createLazyPropDecorator(new TimeoutWeakMap(maxAge));
+  } else {
+    const decorator = createLazyPropDecorator(/* @__PURE__ */ new WeakMap());
+    return decorator(targetOrTimeout, key, descriptor);
+  }
+}
+__name(lazyProp, "lazyProp");
+function createLazyPropDecorator(map) {
+  return function(target, key, descriptor) {
+    const { get, value } = descriptor;
+    if (isFunction(get)) {
+      descriptor.get = function() {
+        return mapGetOrDefault(map, this, () => get.call(this));
+      };
+      return descriptor;
+    }
+    if (isFunction(value)) {
+      return memoizeSync()(target, key, descriptor);
+    }
+    throw new TypeError('neither "get" nor "value" are functions');
+  };
+}
+__name(createLazyPropDecorator, "createLazyPropDecorator");
+
+// src/lib/Help.ts
+import C from "ansi-colors";
+var Help = class {
+  static {
+    __name(this, "Help");
+  }
+  cmd;
+  /** output helpWidth, long lines are wrapped to fit */
+  helpWidth = process.stdout.isTTY ? process.stdout.columns : 80;
+  minWidthToWrap = 40;
+  sortSubcommands = true;
+  sortOptions = true;
+  usageDisplayOptionsAs = "[opts]";
+  usageDisplaySubcommandAs = "[cmd]";
+  constructor(cmd) {
+    this.cmd = cmd;
+    Object.defineProperty(this, "cmd", { enumerable: false });
+  }
+  visibleCommands() {
+    const res = Object.values(this.cmd.commands).filter((c) => !c.hidden);
+    if (this.sortSubcommands) {
+      res.sort((a, b) => {
+        return a.name.localeCompare(b.name);
+      });
+    }
+    return res;
+  }
+  /**
+   * Compare options for sort.
+   */
+  compareOptions(a, b) {
+    const getSortKey = /* @__PURE__ */ __name((option) => {
+      return option.short ? option.short.replace(/^-/, "") : option.long.replace(/^--/, "");
+    }, "getSortKey");
+    return getSortKey(a).localeCompare(getSortKey(b));
+  }
+  visibleOptions() {
+    const res = this.cmd.options.filter((option) => !option.hidden);
+    if (this.sortOptions) res.sort(this.compareOptions);
+    return res;
+  }
+  visibleArguments() {
+    if (this.cmd.arguments.find((argument) => !!argument.description)) {
+      return [...this.cmd.arguments];
+    }
+    return [];
+  }
+  /**
+   * Get the command term to show in the list of subcommands.
+   */
+  subcommandTerm(sub) {
+    const args = sub.arguments.map((arg) => arg.usage).join(" ");
+    return (sub.aliases[0] ? sub.aliases[0].padEnd(this.longestSubcommandAliasLength(), " ") + " | " : "") + sub.name + (sub.options.length ? " " + this.usageDisplayOptionsAs : "") + // simplistic check for non-help option
+    (args ? " " + args : "");
+  }
+  /**
+   * Get the option term to show in the list of options.
+   */
+  optionTerm(option) {
+    return option.flags;
+  }
+  /**
+   * Get the argument term to show in the list of arguments.
+   */
+  argumentTerm(argument) {
+    return argument.name;
+  }
+  longestSubcommandAliasLength() {
+    return Math.max(0, ...this.visibleCommands().map((c) => c.aliases[0]?.length || 0));
+  }
+  longestSubcommandTermLength() {
+    return this.visibleCommands().reduce((max, command) => {
+      return Math.max(max, this.displayWidth(this.styleSubcommandTerm(this.subcommandTerm(command))));
+    }, 0);
+  }
+  longestOptionTermLength() {
+    return this.visibleOptions().reduce((max, option) => {
+      return Math.max(max, this.displayWidth(this.styleOptionTerm(this.optionTerm(option))));
+    }, 0);
+  }
+  longestArgumentTermLength() {
+    return this.visibleArguments().reduce((max, argument) => {
+      return Math.max(max, this.displayWidth(this.styleArgumentTerm(this.argumentTerm(argument))));
+    }, 0);
+  }
+  /**
+   * Get the command usage to be displayed at the top of the built-in help.
+   */
+  commandUsage() {
+    let path = "";
+    for (let ancestor = this.cmd.parent; ancestor; ancestor = ancestor.parent) {
+      path = ancestor.name + " " + path;
+    }
+    return (path + this.cmd.name + " " + [
+      ...Object.keys(this.cmd.commands).length ? [this.usageDisplaySubcommandAs] : [],
+      ...this.cmd.options.length ? [this.usageDisplayOptionsAs] : [],
+      ...this.cmd.arguments.map((arg) => {
+        return arg.required ? arg.variadic ? `<${arg.name}...>` : `<${arg.name}>` : arg.variadic ? `[${arg.name}...]` : `[${arg.name}]`;
+      })
+    ].join(" ")).trim();
+  }
+  /**
+   * Get the description for the command.
+   */
+  commandDescription() {
+    let res = "";
+    if (this.cmd.aliases.length) {
+      res += `Aliases: ${this.cmd.aliases.join(", ")}`;
+      res += "\n\n";
+    }
+    res += this.cmd.description;
+    return res;
+  }
+  /**
+   * Get the subcommand summary to show in the list of subcommands.
+   * (Fallback to description for backwards compatibility.)
+   */
+  subcommandDescription(sub) {
+    return sub.summary || (sub.description?.includes("\n") ? sub.description.trim().split("\n")[0] : sub.description.trim());
+  }
+  /**
+   * Get the option description to show in the list of options.
+   */
+  optionDescription(option) {
+    const extraInfo = [];
+    if (option.choices) {
+      extraInfo.push(
+        // use stringify to match the display of the default value
+        `choices: ${option.choices.map((choice) => String(choice)).join(", ")}`
+      );
+    }
+    if (option.defaultValue && !(Array.isArray(option.defaultValue) && option.defaultValue.length === 0)) {
+      extraInfo.push(`default: ${option.defaultValueDescription || String(option.defaultValue)}`);
+    }
+    if (option.env !== void 0) {
+      extraInfo.push(`env: ${option.env}`);
+    }
+    if (extraInfo.length > 0) {
+      const extraDescription = `(${extraInfo.join(", ")})`;
+      if (option.description) {
+        return `${option.description} ${extraDescription}`;
+      }
+      return extraDescription;
+    }
+    return option.description ?? "";
+  }
+  /**
+   * Get the argument description to show in the list of arguments.
+   */
+  argumentDescription(argument) {
+    const extraInfo = [];
+    if (argument.choices) {
+      extraInfo.push(
+        // use stringify to match the display of the default value
+        `choices: ${argument.choices.map((choice) => String(choice)).join(", ")}`
+      );
+    }
+    if (argument.defaultValue !== void 0) {
+      extraInfo.push(`default: ${argument.defaultValueDescription || String(argument.defaultValue)}`);
+    }
+    if (extraInfo.length > 0) {
+      const extraDescription = `(${extraInfo.join(", ")})`;
+      if (argument.description) {
+        return `${argument.description} ${extraDescription}`;
+      }
+      return extraDescription;
+    }
+    return argument.description ?? "";
+  }
+  /**
+   * Format a list of items, given a heading and an array of formatted items.
+   */
+  formatItemList(heading, items) {
+    if (items.length === 0) return [];
+    return [this.styleTitle(heading), ...items, ""];
+  }
+  /**
+   * Group items by their help group heading.
+   */
+  groupItems(unsortedItems, visibleItems, getGroup) {
+    const result = /* @__PURE__ */ new Map();
+    unsortedItems.forEach((item) => {
+      const group = getGroup(item);
+      if (!result.has(group)) result.set(group, []);
+    });
+    visibleItems.forEach((item) => {
+      const group = getGroup(item);
+      if (!result.has(group)) {
+        result.set(group, []);
+      }
+      result.get(group).push(item);
+    });
+    return result;
+  }
+  /**
+   * Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations.
+   */
+  displayWidth(str) {
+    const sgrPattern = /\x1b\[\d*(;\d*)*m/g;
+    return str.replace(sgrPattern, "").length;
+  }
+  /**
+   * Style the title for displaying in the help. Called with 'Usage:', 'Options:', etc.
+   */
+  styleTitle(str) {
+    return C.yellow(str);
+  }
+  /**
+   * Style the usage line for displaying in the help. Applies specific styling to different parts like options, commands, and arguments.
+   */
+  styleUsage(str) {
+    return str.split(" ").map((word, index, arr) => {
+      if (word === this.usageDisplaySubcommandAs) return C.green(word);
+      if (word === this.usageDisplayOptionsAs) return C.blue(word);
+      if (word[0] === "<") return C.red(word);
+      if (word[0] === "[") return C.cyan(word);
+      if (arr[index + 1]?.startsWith("[")) return C.magenta(word);
+      return this.styleCommandText(word);
+    }).join(" ");
+  }
+  /**
+   * Style command descriptions for display in help output.
+   */
+  styleCommandDescription(str) {
+    return this.styleDescriptionText(str);
+  }
+  /**
+   * Style option descriptions for display in help output.
+   */
+  styleOptionDescription(str) {
+    return C.gray(this.styleDescriptionText(str));
+  }
+  /**
+   * Style subcommand descriptions for display in help output.
+   */
+  styleSubcommandDescription(str) {
+    return this.styleDescriptionText(str);
+  }
+  /**
+   * Style argument descriptions for display in help output.
+   */
+  styleArgumentDescription(str) {
+    return C.gray(this.styleDescriptionText(str));
+  }
+  /**
+   * Base style used by descriptions. Override in subclass to apply custom formatting.
+   */
+  styleDescriptionText(str) {
+    return C.gray(str);
+  }
+  /**
+   * Style option terms (flags) for display in help output.
+   */
+  styleOptionTerm(str) {
+    return this.styleOptionText(str);
+  }
+  /**
+   * Style subcommand terms for display in help output. Applies specific styling to different parts like options and arguments.
+   */
+  styleSubcommandTerm(str) {
+    const res = str.split(" ").map((word) => {
+      if (word === this.usageDisplayOptionsAs) return C.dim(word);
+      if (word[0] === "[" || word[0] === "<") return C.dim(word);
+      return this.styleSubcommandText(word);
+    }).join(" ");
+    const split = res.split("|");
+    if (split.length === 1) {
+      return res;
+    }
+    split[0] = C.green(split[0]);
+    return split.join("|");
+  }
+  /**
+   * Style argument terms for display in help output.
+   */
+  styleArgumentTerm(str) {
+    return this.styleArgumentText(str);
+  }
+  /**
+   * Base style used in terms and usage for options. Override in subclass to apply custom formatting.
+   */
+  styleOptionText(str) {
+    return str;
+  }
+  /**
+   * Base style used in terms and usage for arguments. Override in subclass to apply custom formatting.
+   */
+  styleArgumentText(str) {
+    return str;
+  }
+  /**
+   * Base style used in terms and usage for subcommands. Override in subclass to apply custom formatting.
+   */
+  styleSubcommandText(str) {
+    return str;
+  }
+  /**
+   * Base style used in terms and usage for commands. Override in subclass to apply custom formatting.
+   */
+  styleCommandText(str) {
+    return str;
+  }
+  padWidth() {
+    return Math.max(
+      this.longestOptionTermLength(),
+      this.longestSubcommandTermLength(),
+      this.longestArgumentTermLength()
+    );
+  }
+  /**
+   * Detect manually wrapped and indented strings by checking for line break followed by whitespace.
+   */
+  preformatted(str) {
+    return /\n[^\S\r\n]/.test(str);
+  }
+  /**
+   * Format the "item", which consists of a term and description. Pad the term and wrap the description, indenting the following lines.
+   *
+   * So "TTT", 5, "DDD DDDD DD DDD" might be formatted for this.helpWidth=17 like so:
+   *   TTT  DDD DDDD
+   *        DD DDD
+   */
+  formatItem(term, termWidth, description) {
+    const itemIndent = 2;
+    const itemIndentStr = " ".repeat(itemIndent);
+    if (!description) return itemIndentStr + term;
+    const paddedTerm = term.padEnd(termWidth + term.length - this.displayWidth(term));
+    const spacerWidth = 2;
+    const helpWidth = this.helpWidth;
+    const remainingWidth = helpWidth - termWidth - spacerWidth - itemIndent;
+    let formattedDescription;
+    if (remainingWidth < this.minWidthToWrap || this.preformatted(description)) {
+      formattedDescription = description;
+    } else {
+      const wrappedDescription = this.boxWrap(description, remainingWidth);
+      formattedDescription = wrappedDescription.replace(/\n/g, "\n" + " ".repeat(termWidth + spacerWidth));
+    }
+    return itemIndentStr + paddedTerm + " ".repeat(spacerWidth) + formattedDescription.replace(/\n/g, `
+${itemIndentStr}`);
+  }
+  /**
+   * Wrap a string at whitespace, preserving existing line breaks.
+   * Wrapping is skipped if the width is less than `minWidthToWrap`.
+   */
+  boxWrap(str, width) {
+    if (width < this.minWidthToWrap) return str;
+    const rawLines = str.split(/\r\n|\n/);
+    const chunkPattern = /[\s]*[^\s]+/g;
+    const wrappedLines = [];
+    rawLines.forEach((line) => {
+      const chunks = line.match(chunkPattern);
+      if (chunks === null) {
+        wrappedLines.push("");
+        return;
+      }
+      let sumChunks = [chunks.shift()];
+      let sumWidth = this.displayWidth(sumChunks[0]);
+      chunks.forEach((chunk) => {
+        const visibleWidth = this.displayWidth(chunk);
+        if (sumWidth + visibleWidth <= width) {
+          sumChunks.push(chunk);
+          sumWidth += visibleWidth;
+          return;
+        }
+        wrappedLines.push(sumChunks.join(""));
+        const nextChunk = chunk.trimStart();
+        sumChunks = [nextChunk];
+        sumWidth = this.displayWidth(nextChunk);
+      });
+      wrappedLines.push(sumChunks.join(""));
+    });
+    return wrappedLines.join("\n");
+  }
+  /**
+   * Generate the built-in help text.
+   */
+  render() {
+    let output = [`${this.styleTitle("Usage:")} ${this.styleUsage(this.commandUsage())}`, ""];
+    const des = this.commandDescription();
+    if (des.length > 0) {
+      output = output.concat([this.boxWrap(this.styleCommandDescription(des), this.helpWidth), ""]);
+    }
+    const argumentList = this.visibleArguments().map((argument) => {
+      return this.formatItem(
+        this.styleArgumentTerm(this.argumentTerm(argument)),
+        this.padWidth(),
+        this.styleArgumentDescription(this.argumentDescription(argument))
+      );
+    });
+    output = output.concat(this.formatItemList("Arguments:", argumentList));
+    const optionGroups = this.groupItems(
+      this.cmd.options,
+      this.visibleOptions(),
+      (option) => option.group ?? "Options:"
+    );
+    optionGroups.forEach((options, group) => {
+      const optionList = options.map((option) => {
+        return this.formatItem(
+          this.styleOptionTerm(this.optionTerm(option)),
+          this.padWidth(),
+          this.styleOptionDescription(this.optionDescription(option))
+        );
+      });
+      output = output.concat(this.formatItemList(group, optionList));
+    });
+    const commandGroups = this.groupItems(
+      Object.values(this.cmd.commands),
+      this.visibleCommands(),
+      (sub) => sub.group || "Commands:"
+    );
+    commandGroups.forEach((commands, group) => {
+      const commandList = commands.map((sub) => {
+        return this.formatItem(
+          this.styleSubcommandTerm(this.subcommandTerm(sub)),
+          this.padWidth(),
+          this.styleSubcommandDescription(this.subcommandDescription(sub))
+        );
+      });
+      output = output.concat(this.formatItemList(group, commandList));
+    });
+    return output.join("\n");
+  }
+};
+__decorateClass([
+  lazyProp
+], Help.prototype, "visibleCommands", 1);
+__decorateClass([
+  lazyProp
+], Help.prototype, "visibleOptions", 1);
+__decorateClass([
+  lazyProp
+], Help.prototype, "visibleArguments", 1);
+__decorateClass([
+  lazyProp
+], Help.prototype, "longestSubcommandAliasLength", 1);
+__decorateClass([
+  lazyProp
+], Help.prototype, "longestSubcommandTermLength", 1);
+__decorateClass([
+  lazyProp
+], Help.prototype, "longestOptionTermLength", 1);
+__decorateClass([
+  lazyProp
+], Help.prototype, "longestArgumentTermLength", 1);
+__decorateClass([
+  lazyProp
+], Help.prototype, "padWidth", 1);
+
+// src/lib/helpers/findCommand.ts
+var findCommand_exports = {};
+__export(findCommand_exports, {
+  findCommand: () => findCommand
+});
+function findCommand(cmd, nameOrAlias) {
+  return cmd.commands[nameOrAlias] ?? valuesOf(cmd.commands).find((c) => c.aliases.includes(nameOrAlias));
+}
+__name(findCommand, "findCommand");
+
+// src/lib/helpers/getCommandAncestors.ts
+var getCommandAncestors_exports = {};
+__export(getCommandAncestors_exports, {
+  getCommandAncestors: () => getCommandAncestors
+});
+
+// src/lib/helpers/getCommandAndAncestors.ts
+var getCommandAndAncestors_exports = {};
+__export(getCommandAndAncestors_exports, {
+  getCommandAndAncestors: () => getCommandAndAncestors
+});
+function getCommandAndAncestors(cmd) {
+  const result = [];
+  let command = cmd;
+  for (; command; command = command.parent) {
+    result.push(command);
+  }
+  return result;
+}
+__name(getCommandAndAncestors, "getCommandAndAncestors");
+
+// src/lib/helpers/getCommandAncestors.ts
+function getCommandAncestors(cmd) {
+  return getCommandAndAncestors(cmd).slice(1);
+}
+__name(getCommandAncestors, "getCommandAncestors");
+
+// ../node/src/createLogger.ts
+import colors from "ansi-colors";
+import { isPrimitive, isString } from "es-toolkit/predicate";
+function createLogger(name) {
+  const NAME = name ? colors.dim.cyan(name) : name;
+  const START = [NAME, colors.dim.gray("[START]")].filter(Boolean);
+  const DEBUG = [NAME, colors.dim.magenta("[DEBUG]")].filter(Boolean);
+  const INFO = [NAME, colors.dim.gray("[INFO]")].filter(Boolean);
+  const DONE = [NAME, colors.dim.green("[DONE] ")].filter(Boolean);
+  const WARN = [NAME, colors.dim.yellow("[WARN] ")].filter(Boolean);
+  const ERROR = [NAME, colors.dim.red("[ERROR]")].filter(Boolean);
+  const grayArgs = createColoredArgs(colors.gray);
+  const cyanArgs = createColoredArgs(colors.cyan);
+  const yellowArgs = createColoredArgs(colors.yellow);
+  return {
+    start: /* @__PURE__ */ __name((...args) => console.info(...START, ...args), "start"),
+    done: /* @__PURE__ */ __name((...args) => console.info(...DONE, ...args), "done"),
+    info: /* @__PURE__ */ __name((...args) => console.info(...INFO, ...grayArgs(args)), "info"),
+    log: /* @__PURE__ */ __name((...args) => console.log(...NAME ? [NAME, ...args] : args), "log"),
+    warn: /* @__PURE__ */ __name((...args) => console.warn(...WARN, ...yellowArgs(args)), "warn"),
+    debug: /* @__PURE__ */ __name((...args) => console.debug(...DEBUG, ...cyanArgs(args)), "debug"),
+    error: /* @__PURE__ */ __name((...args) => args.forEach((arg) => console.error(...ERROR, arg)), "error")
+  };
+}
+__name(createLogger, "createLogger");
+function createColoredArgs(colorFn) {
+  return (args) => {
+    return args.map((arg) => {
+      if (isString(arg)) {
+        if (arg === colors.stripColor(arg)) {
+          return colorFn(arg);
+        } else {
+          return arg;
+        }
+      } else if (isPrimitive(arg)) {
+        return colorFn(String(arg));
+      } else {
+        return arg;
+      }
+    });
+  };
+}
+__name(createColoredArgs, "createColoredArgs");
+
+// ../node/src/timer.ts
+import { isPromise } from "node:util/types";
+import colors2 from "ansi-colors";
+import humanizeDuration from "humanize-duration";
+function timer(arg, task) {
+  const t0 = process.hrtime.bigint();
+  const [name, description] = Array.isArray(arg) ? arg : [arg, ""];
+  const log = createLogger(name);
+  if (name && description) {
+    log.start(description);
+  }
+  const retval = task(log, name);
+  if (!isPromise(retval)) {
+    return done(retval);
+  }
+  return retval.then((result) => {
+    return done(result);
+  });
+  function done(retval2) {
+    if (process.exitCode) return retval2;
+    const ns = process.hrtime.bigint() - t0;
+    const ms3 = Math.floor(Number(ns) / 1e6);
+    log.done(colors2.dim(humanizeDuration(ms3)));
+    return retval2;
+  }
+  __name(done, "done");
+}
+__name(timer, "timer");
+
+// src/lib/helpers/findOption.ts
+var findOption_exports = {};
+__export(findOption_exports, {
+  findOption: () => findOption
+});
+function findOption(cmd, nameOrShortOrLong) {
+  return nameOrShortOrLong.startsWith("--") ? cmd.options.find((o) => o.long === nameOrShortOrLong.slice(2)) : nameOrShortOrLong.startsWith("-") ? cmd.options.find((o) => o.short === nameOrShortOrLong.slice(1)) : cmd.options.find((o) => o.name === nameOrShortOrLong);
+}
+__name(findOption, "findOption");
+
+// src/lib/helpers/parseOptionFlags.ts
+var parseOptionFlags_exports = {};
+__export(parseOptionFlags_exports, {
+  parseOptionFlags: () => parseOptionFlags
+});
+function parseOptionFlags(flags) {
+  const match = flags.match(/^-(.+?), --([a-zA-Z][\w-]*)(?:\s*(<(.+?)>|\[(.+?)\]))?$/);
+  if (!match) throw new Error(`Invalid option format: ${flags}`);
+  const short = match[1];
+  if (short.length !== 1) {
+    throw new Error(`Expected short name to be a single character. Got: -${short}`);
+  }
+  const long = match[2];
+  const argName = (match[4] || match[5])?.replace(/\.\.\.$/, "") || void 0;
+  const name = long.split("-").reduce((str, word) => {
+    return str + word[0].toUpperCase() + word.slice(1);
+  });
+  return { short, long, name, argName };
+}
+__name(parseOptionFlags, "parseOptionFlags");
+
+// src/lib/Command.ts
+import { kebabCase } from "es-toolkit/string";
+var _Command = class _Command {
+  static {
+    __name(this, "Command");
+  }
+  /** Parent command in the hierarchy, undefined for root command */
+  parent;
+  /** The command name used to invoke it */
+  name;
+  /** Semantic version string displayed by --version flag */
+  version;
+  /** Alternative names for invoking this command */
+  aliases;
+  /** Brief one-line description shown in command lists */
+  summary;
+  /** Full description displayed in help text */
+  description;
+  /** Whether to exclude from help listings */
+  hidden;
+  /** Category for organizing related commands in help output */
+  group;
+  /** Positional arguments this command accepts */
+  arguments;
+  /** CLI options (flags) this command recognizes */
+  options;
+  /** Subcommands registered with this command */
+  commands;
+  /** Main action handler executed when command is invoked */
+  action;
+  /** Option-driven actions (e.g., --help, --version) executed when their conditions match */
+  hooks;
+  constructor(name, parent) {
+    this.name = name;
+    this.aliases = [];
+    this.description = "";
+    this.arguments = [];
+    this.options = [];
+    this.commands = {};
+    this.hooks = [];
+    Object.defineProperty(this, "parent", { value: parent, enumerable: false });
+    if (!parent) {
+      this.addOption("-D, --debug", { description: "Display debug information" }).addOptionHook("debug", ({ cmd, ...data }) => {
+        console.debug(inspect(cmd, { depth: 1, colors: true }));
+        console.debug(inspect(data, { depth: 3, colors: true }));
+      });
+      this.addOption("-h, --help", { description: "Display help information" }).addOptionHook("help", ({ cmd }) => {
+        console.log(cmd.renderHelp());
+        process.exitCode = 0;
+      });
+    }
+  }
+  get help() {
+    return new Help(this);
+  }
+  /** Configure how the help is rendered */
+  helpConfiguration(cb) {
+    const help = this.help;
+    cb?.(help);
+    return this;
+  }
+  /** Renders formatted help text using provided help definition */
+  renderHelp(config = {}) {
+    const result = this.help.render();
+    return config.noColor ? colors3.stripColor(result) : result;
+  }
+  /** Sets the command name */
+  setName(name) {
+    this.name = name;
+  }
+  /** Sets command aliases, flattening nested arrays */
+  setAliases(...aliases) {
+    this.aliases = [];
+    this.addAliases(...aliases);
+    return this;
+  }
+  /** Adds aliases to existing ones */
+  addAliases(...aliases) {
+    const taken = this.parent ? valuesOf(this.parent.commands).flatMap((c) => [c.name, ...c.aliases]) : [];
+    arrRemoveDuplicates(aliases.flat()).filter((a) => !this.aliases.includes(a) && a !== this.name).forEach((a) => {
+      if (taken.includes(a)) {
+        throw new Error(
+          `Alias "${a}" is already used by a sibling command: ${findCommand(this.parent, a)?.name}`
+        );
+      }
+      this.aliases.push(a);
+    });
+    this.aliases.sort((a, b) => a.length - b.length);
+    return this;
+  }
+  /** Sets the command version */
+  setVersion(version) {
+    this.version = version;
+    if (findOption(this, "version")) return this;
+    return this.addOption("-V, --version", { description: "Display semver version" }).addOptionHook("version", ({ cmd }) => {
+      console.log(getCommandAndAncestors(cmd).find((c) => c.version)?.version);
+      process.exitCode = 0;
+    });
+  }
+  /** Sets the command summary */
+  setSummary(summary) {
+    this.summary = summary;
+    return this;
+  }
+  /** Sets command description, joining variadic lines */
+  setDescription(...lines) {
+    this.description = lines.join("\n");
+    return this;
+  }
+  /** Sets whether command is hidden from help */
+  setHidden(hidden = true) {
+    this.hidden = hidden;
+    return this;
+  }
+  /** Sets the command group for help organization */
+  setGroup(group) {
+    this.group = group;
+    return this;
+  }
+  /** Add a subcommand and return the subcommand. All options are inherited by the subcommand. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  command(name, cb) {
+    if (this.arguments.length) {
+      throw new Error(
+        `Cannot add subcommand "${name}" to "${this.name}" because it already has arguments defined.`
+      );
+    }
+    const sub = this.createSubcommand(name);
+    const inherit = this.options;
+    sub.options.push(...inherit);
+    const inheritHooks = this.hooks.filter((t) => inherit.some((i) => i.name === t.name));
+    sub.hooks.push(...inheritHooks);
+    const taken = valuesOf(this.commands).flatMap((c) => [c.name, ...c.aliases]);
+    if (taken.includes(name)) {
+      throw new Error(
+        `Command name "${getCommandAndAncestors(sub).map((c) => c.name)}" is already used by this command or its aliases: ${taken.join(", ")}`
+      );
+    }
+    const kebab = kebabCase(name);
+    const words = kebab.split("-");
+    const initials = words.map((s) => s[0]).join("");
+    if (!taken.includes(initials)) {
+      sub.addAliases(initials);
+    } else {
+      const initials2 = words.map((s) => s[0] + s[1]).join("");
+      if (!taken.includes(initials2)) {
+        sub.addAliases(initials2);
+      }
+    }
+    this.commands[name] = sub;
+    return cb ? cb(sub, this) : sub;
+  }
+  /** Add a subcommand and return the subcommand. All options are inherited by the subcommand. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  addCommand(name, cb) {
+    this.command(name, cb);
+    return this;
+  }
+  // Implementation
+  addArgument(usage, options = {}) {
+    if (!/^<(.*?)>$|^\[(.*?)\]$/.test(usage)) {
+      throw new Error(`Invalid argument format: ${usage}`);
+    }
+    const name = usage.slice(1, -1).replace(/\.\.\.$/, "");
+    const required = usage.startsWith("<");
+    const variadic = usage.slice(0, -1).endsWith("...");
+    const prevArg = this.arguments[this.arguments.length - 1];
+    if (prevArg?.variadic) {
+      throw new Error(`Cannot add argument ${usage} after variadic argument ${prevArg.usage}`);
+    }
+    if (required && prevArg && !prevArg?.required) {
+      throw new Error(`Cannot add required argument ${usage} after optional argument ${prevArg?.usage}`);
+    }
+    if (required && prevArg?.defaultValue) {
+      throw new Error(
+        `Cannot add required argument ${usage} after optional argument with default value ${prevArg.usage}`
+      );
+    }
+    const arg = {
+      usage,
+      name,
+      required,
+      variadic,
+      ...options
+    };
+    if (variadic && !arg.defaultValue) {
+      arg.defaultValue = [];
+    }
+    this.arguments.push(arg);
+    return this;
+  }
+  /**
+   * Adds command-line option with type inference. Parses format: `-s, --long [<value>|[value]|<value...>|[value...]]`
+   */
+  addOption(flags, opts = {}) {
+    const ins = {};
+    const { short, long, name, argName } = parseOptionFlags(flags);
+    for (const opt of this.options) {
+      if (opt.long === long) {
+        throw new Error(`Option long name, --${long} already in use by: ${opt.flags}`);
+      }
+      if (opt.short === short) {
+        throw new Error(`Option short name, -${short} already in use by: ${opt.flags}`);
+      }
+    }
+    ins.flags = flags;
+    ins.short = short;
+    ins.long = long;
+    ins.name = name;
+    ins.description = "";
+    if (!argName) {
+      ins.type = "boolean";
+    } else {
+      ins.type = "string";
+      ins.argName = argName;
+      if (flags.endsWith(">")) {
+        if (flags.endsWith("...>")) {
+          ins.required = true;
+          ins.variadic = true;
+        } else {
+          ins.required = true;
+        }
+      } else if (flags.endsWith("]")) {
+        if (flags.endsWith("...]")) {
+          ins.variadic = true;
+          ins.defaultValue = opts.defaultValue ?? [];
+        }
+      }
+    }
+    for (const [key, value] of Object.entries(opts)) {
+      if (value !== void 0) Reflect.set(ins, key, value);
+    }
+    if (ins.env && ins.defaultValue === void 0 && typeof process.env[ins.env] === "string") {
+      ins.required = false;
+      ins.flags = ins.flags.replace("<", "[").replace(">", "]");
+      if (ins.type === "boolean") {
+        ins.defaultValue = /^(t(rue)?|y(es)?|1)$/i.test(process.env[ins.env]);
+      } else if (ins.variadic) {
+        ins.defaultValue = process.env[ins.env].replace(/\]|\[/, "").split(",").map((v) => v.trim());
+      } else {
+        ins.defaultValue = process.env[ins.env];
+      }
+    }
+    this.options.push(ins);
+    return this;
+  }
+  /**
+   * Register an action to be invoked when an option is set to true or string value.
+   *
+   * Hooks execute in addition to or instead of the main action handler,
+   * allowing for option-driven behavior. For example, `--help` and `--version`
+   * are implemented as hooks.
+   */
+  addOptionHook(optionName, action) {
+    const def = findOption(this, optionName);
+    if (!def.group && /process\.exitCode ?= ?.+;?\s*\}$/.test(action.toString())) {
+      def.group = "Command Options";
+    }
+    this.hooks.push({
+      name: optionName,
+      predicate: setName("has" + strFirstCharToUpperCase(optionName), ({ opts }) => {
+        return opts[optionName] !== void 0 && opts[optionName] !== false && !(Array.isArray(opts[optionName]) && opts[optionName].length === 0);
+      }),
+      action: setName(optionName, action)
+    });
+    return this;
+  }
+  /** Parses command-line arguments with subcommand support and type-safe validation. */
+  parseArgv(argv = process.argv.slice(2)) {
+    const sub = findCommand(this, argv[0]);
+    if (sub) return sub.parseArgv(argv.slice(1));
+    argv = normalizeArgv(argv, this.options);
+    const parsed = parseArgs({
+      args: argv,
+      options: Object.fromEntries(
+        this.options.map((o) => [
+          o.name,
+          { type: o.type, short: o.short, default: o.defaultValue, multiple: !!o.variadic }
+        ])
+      ),
+      allowPositionals: true,
+      tokens: true,
+      strict: false,
+      allowNegative: true
+    });
+    collectVariadicOptionValues(parsed, this.options);
+    mergeOptionDefaults(parsed.values, this.options);
+    parsed.values = objSortKeys(parsed.values, (a, b) => {
+      return a[1] === false ? 1 : b[1] === false ? -1 : a[1] === true ? 1 : b[1] === true ? -1 : 0;
+    });
+    const args = resolveArguments(parsed.positionals, this.arguments);
+    const opts = filterObject(parsed.values, (value) => value !== void 0);
+    const errors = validateParsed(args, parsed.values, this.arguments, this.options);
+    const path = getCommandAncestors(this).map((c) => c.name);
+    const data = {
+      path,
+      name: this.name,
+      argv,
+      args,
+      opts,
+      errors,
+      cmd: this
+    };
+    const hooks = this.hooks.filter((t) => t.predicate(data));
+    const execute = /* @__PURE__ */ __name(async () => {
+      for (const hook of hooks) {
+        await hook.action(data);
+        if (process.exitCode) {
+          return;
+        }
+      }
+      await timer([[...path, this.name].join(" "), this.description], async (logger) => {
+        if (errors) {
+          errors.forEach((msg) => logger.error(colors3.red(msg)));
+          process.exitCode = 1;
+        }
+        if (this.action) {
+          return await this.action(...args, opts, {
+            ...data,
+            args,
+            opts,
+            cmd: this,
+            logger
+          });
+        }
+        console.log(this.renderHelp());
+      });
+    }, "execute");
+    return { ...data, hooks, execute };
+  }
+  /**
+   * Sets the main action handler for this command, which is executed after any matching option hooks when the command is invoked.
+   * The handler receives parsed arguments and options with correct typings.
+   */
+  setAction(fn) {
+    this.action = setName(this.name, fn);
+    return this;
+  }
+  /** Returns a new Command instance. Override this method in subclasses. */
+  createSubcommand(name) {
+    return new _Command(name, this);
+  }
+};
+__decorateClass([
+  lazyProp
+], _Command.prototype, "help", 1);
+var Command = _Command;
+
+// src/lib/types.ts
+var types_exports = {};
+
+// src/index.ts
+var src_default = {
+  ...Command_exports,
+  //
+  ...Help_exports,
+  ...findCommand_exports,
+  ...findOption_exports,
+  ...getCommandAncestors_exports,
+  ...getCommandAndAncestors_exports,
+  ...parseOptionFlags_exports,
+  ...types_exports
+};
+export {
+  Command,
+  Help,
+  src_default as default,
+  findCommand,
+  findOption,
+  getCommandAncestors,
+  getCommandAndAncestors,
+  parseOptionFlags
+};
+//# sourceMappingURL=index.mjs.map