@bemoje/cli 1.0.3 → 1.0.4

package/{index.js → cjs/index.cjs}

@@ -28,4 +28,4 @@ __reExport(src_exports, require("./lib/renderHelp"), module.exports);
   ...require("./lib/Help"),
   ...require("./lib/renderHelp")
 });
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.cjs.map

package/{lib/Command.js → cjs/lib/Command.cjs}

@@ -450,4 +450,4 @@ class Command {
 0 && (module.exports = {
   Command
 });
-//# sourceMappingURL=Command.js.map
+//# sourceMappingURL=Command.cjs.map

package/{lib/CommandHelpAdapter.js → cjs/lib/CommandHelpAdapter.cjs}

@@ -127,4 +127,4 @@ let CommandHelpAdapter = _CommandHelpAdapter;
 0 && (module.exports = {
   CommandHelpAdapter
 });
-//# sourceMappingURL=CommandHelpAdapter.js.map
+//# sourceMappingURL=CommandHelpAdapter.cjs.map

package/{lib/CommanderHelpAdapter.js → cjs/lib/CommanderHelpAdapter.cjs}

@@ -117,4 +117,4 @@ let CommanderHelpAdapter = _CommanderHelpAdapter;
 0 && (module.exports = {
   CommanderHelpAdapter
 });
-//# sourceMappingURL=CommanderHelpAdapter.js.map
+//# sourceMappingURL=CommanderHelpAdapter.cjs.map

package/{lib/Help.js → cjs/lib/Help.cjs}

@@ -487,4 +487,4 @@ function humanReadableArgName(arg) {
 0 && (module.exports = {
   Help
 });
-//# sourceMappingURL=Help.js.map
+//# sourceMappingURL=Help.cjs.map

package/{lib/internal/lazyProp.js → cjs/lib/internal/lazyProp.cjs}

@@ -38,4 +38,4 @@ function lazyProp(target, key, descriptor) {
   };
   return descriptor;
 }
-//# sourceMappingURL=lazyProp.js.map
+//# sourceMappingURL=lazyProp.cjs.map

package/{lib/renderHelp.js → cjs/lib/renderHelp.cjs}

@@ -30,4 +30,4 @@ function renderHelp(cmd, help = new import_Help.Help()) {
 0 && (module.exports = {
   renderHelp
 });
-//# sourceMappingURL=renderHelp.js.map
+//# sourceMappingURL=renderHelp.cjs.map

package/esm/index.mjs

@@ -0,0 +1,6 @@
+export * from "./lib/Command";
+export * from "./lib/CommandHelpAdapter";
+export * from "./lib/CommanderHelpAdapter";
+export * from "./lib/Help";
+export * from "./lib/renderHelp";
+//# sourceMappingURL=index.mjs.map

package/esm/lib/Command.mjs

@@ -0,0 +1,429 @@
+import { parseArgs } from "node:util";
+import { CommandHelpAdapter } from "./CommandHelpAdapter";
+class Command {
+  /** Command name used for invocation */
+  name;
+  /** Optional version string */
+  version;
+  /** Alternative names for this command */
+  aliases;
+  /** Brief single-line description */
+  summary;
+  /** Full command description */
+  description;
+  /** Whether command should be hidden from help */
+  hidden;
+  /** Group name for organizing commands in help */
+  group;
+  /** Parent command if this is a subcommand */
+  parent;
+  /** Child subcommands */
+  commands;
+  /** Positional arguments */
+  arguments;
+  /** Named options/flags */
+  options;
+  /** Help system configuration */
+  helpConfiguration;
+  constructor(name = "", parent = null) {
+    this.name = name;
+    this.parent = parent;
+    this.aliases = [];
+    this.description = "";
+    this.commands = [];
+    this.arguments = [];
+    this.options = [];
+    this.helpConfiguration = { showGlobalOptions: true, sortOptions: true, sortSubcommands: true };
+    Object.defineProperty(this, "parent", { enumerable: false });
+  }
+  /** Updates multiple command properties at once */
+  setState(state) {
+    Object.assign(this, state);
+    if (state.commands) {
+      state.commands = state.commands.map((cmd) => new Command(cmd.name, this).setState(cmd));
+    }
+    return this;
+  }
+  /** Serializes command to JSON, maintaining compatibility with previous state-based structure */
+  toJSON() {
+    const result = {
+      name: this.name,
+      version: this.version,
+      aliases: this.aliases,
+      summary: this.summary,
+      description: this.description,
+      hidden: this.hidden,
+      group: this.group,
+      commands: this.commands,
+      arguments: this.arguments,
+      options: this.options,
+      helpConfiguration: this.helpConfiguration
+    };
+    Object.defineProperty(result, "parent", {
+      value: this.parent,
+      writable: true,
+      enumerable: false,
+      configurable: true
+    });
+    return result;
+  }
+  /** Sets the command name */
+  setName(name) {
+    this.name = name;
+  }
+  /** Sets command aliases, flattening nested arrays */
+  setAliases(...aliases) {
+    this.aliases = aliases.flat();
+    return this;
+  }
+  /** Adds aliases to existing ones */
+  addAliases(...aliases) {
+    this.aliases.push(...aliases.flat());
+    return this;
+  }
+  /** Sets the command version */
+  setVersion(version) {
+    this.version = version;
+    return this;
+  }
+  /** Sets the command summary */
+  setSummary(summary) {
+    this.summary = summary;
+    return this;
+  }
+  /** Sets command description, joining multiple 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;
+  }
+  /** Sets the parent command */
+  setParent(parent) {
+    this.parent = parent;
+    return this;
+  }
+  /** Extends existing help configuration with new settings */
+  extendHelpConfiguration(config) {
+    this.helpConfiguration = { ...this.helpConfiguration, ...config };
+    return this;
+  }
+  /** Sets help configuration, using defaults if not provided */
+  setHelpConfiguration(config) {
+    this.helpConfiguration = config ? { ...config } : { showGlobalOptions: true, sortOptions: true, sortSubcommands: true };
+    return this;
+  }
+  /** Creates and adds a subcommand */
+  subcommand(name) {
+    const sub = new Command(name, this);
+    this.commands.push(sub);
+    return sub;
+  }
+  /**
+   * Adds positional argument with type inference and CLI ordering validation.
+   */
+  argument(usage, description, options = {}) {
+    const match = usage.match(/^<(.*?)>$|^\[(.*?)\]$/);
+    if (!match) throw new Error(`Invalid argument format: ${usage}`);
+    const nameMatch = match[1] || match[2];
+    const name = nameMatch.replace(/\.\.\.$/, "");
+    this.assertArgumentNameNotInUse(name);
+    if (usage.startsWith("<")) {
+      if (nameMatch.endsWith("...")) {
+        this.assertNoMultipleVariadicArguments();
+        this.arguments.push({
+          name,
+          description,
+          required: true,
+          multiple: true,
+          ...options
+        });
+      } else {
+        this.assertNoOptionalOrVariadicArguments();
+        this.arguments.push({
+          name,
+          description,
+          required: true,
+          multiple: false,
+          ...options
+        });
+      }
+    } else if (usage.startsWith("[")) {
+      if (nameMatch.endsWith("...")) {
+        this.assertNoMultipleVariadicArguments();
+        this.arguments.push({
+          name,
+          description,
+          required: false,
+          multiple: true,
+          defaultValue: options.defaultValue ?? [],
+          ...options
+        });
+      } else {
+        this.assertNoVariadicArgument();
+        this.arguments.push({
+          name,
+          description,
+          required: false,
+          multiple: false,
+          ...options
+        });
+      }
+    }
+    return this;
+  }
+  /**
+   * Adds command-line option with type inference. Parses format: `-s, --long [<value>|[value]|<value...>|[value...]]`
+   */
+  option(usage, description, opts = {}) {
+    const match = usage.match(/^-(.+?), --([a-zA-Z][\w-]*)(?:\s*(<(.+?)>|\[(.+?)\]))?$/);
+    if (!match) throw new Error(`Invalid option format: ${usage}`);
+    const short = match[1];
+    this.assertOptionShortNameIsValid(short);
+    this.assertOptionShortNameNotInUse(short);
+    const name = match[2];
+    const argName = (match[4] || match[5])?.replace(/\.\.\.$/, "");
+    this.assertOptionNameNotInUse(name);
+    if (!argName) {
+      this.options.push({
+        type: "boolean",
+        short,
+        name,
+        description,
+        required: false,
+        multiple: false,
+        ...opts
+      });
+    } else if (usage.endsWith(">")) {
+      if (usage.endsWith("...>")) {
+        this.options.push({
+          type: "string",
+          short,
+          name,
+          argName,
+          description,
+          required: true,
+          multiple: true,
+          ...opts
+        });
+      } else {
+        this.options.push({
+          type: "string",
+          short,
+          name,
+          argName,
+          description,
+          required: true,
+          multiple: false,
+          ...opts
+        });
+      }
+    } else if (usage.endsWith("]")) {
+      if (usage.endsWith("...]")) {
+        this.options.push({
+          type: "string",
+          short,
+          name,
+          argName,
+          description,
+          required: false,
+          multiple: true,
+          defaultValue: opts.defaultValue ?? [],
+          ...opts
+        });
+      } else {
+        this.options.push({
+          type: "string",
+          short,
+          name,
+          argName,
+          description,
+          required: false,
+          multiple: false,
+          ...opts
+        });
+      }
+    }
+    return this;
+  }
+  /**
+   * Parses command-line arguments with subcommand support and type-safe validation.
+   *
+   * @example
+   * ```typescript
+   * const result = cmd.parse(['input.txt', '-v', '--format', 'json'])
+   * // { arguments: ['input.txt'], options: { verbose: true, format: 'json' } }
+   * ```
+   */
+  parse(argv = process.argv.slice(2), globalOptions = []) {
+    const maybeSubArg = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      tokens: false,
+      strict: false,
+      allowNegative: true
+    }).positionals[0];
+    const sub = this.findCommand(maybeSubArg);
+    if (sub) {
+      return sub.parse(
+        argv?.filter((a) => a !== maybeSubArg),
+        [...globalOptions, ...this.options]
+      );
+    }
+    const parsed = parseArgs({
+      args: argv,
+      options: Object.fromEntries(
+        [...globalOptions, ...this.options].map((o) => {
+          return [o.name, o];
+        })
+      ),
+      allowPositionals: true,
+      tokens: true,
+      strict: true,
+      allowNegative: true
+    });
+    for (let i = 0; i < parsed.tokens.length; i++) {
+      const token = parsed.tokens[i];
+      if (token.kind === "option") {
+        const optionDescriptor = this.options.find((o) => o.name === token.name);
+        if (optionDescriptor && optionDescriptor.multiple && optionDescriptor.type === "string") {
+          const values = [token.value];
+          let j = i + 1;
+          while (j < parsed.tokens.length && parsed.tokens[j].kind === "positional") {
+            const positionalToken = parsed.tokens[j];
+            if (positionalToken.kind === "positional") {
+              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)
+          );
+        }
+      }
+    }
+    const parsedArguments = this.arguments.map((arg, index) => {
+      if (arg.multiple) {
+        const remainingArgs = parsed.positionals.slice(index);
+        return remainingArgs.length > 0 ? remainingArgs : arg.defaultValue ?? [];
+      } else {
+        return parsed.positionals[index] ?? arg.defaultValue;
+      }
+    });
+    for (const option of this.options) {
+      if (!(option.name in parsed.values) && "defaultValue" in option) {
+        Reflect.set(parsed.values, option.name, option.defaultValue);
+      }
+    }
+    const self = this;
+    return {
+      get command() {
+        return self;
+      },
+      arguments: parsedArguments,
+      options: { ...parsed.values }
+    };
+  }
+  /** Validates CLI argument ordering */
+  assertNoOptionalOrVariadicArguments() {
+    if (this.arguments.some((arg) => !arg.required)) {
+      throw new Error("Cannot add required argument after optional or variadic arguments");
+    }
+  }
+  /** Validates optional args don't follow variadic args */
+  assertNoVariadicArgument() {
+    if (this.arguments.some((arg) => arg.multiple)) {
+      throw new Error("Cannot add optional argument after variadic argument");
+    }
+  }
+  /** Ensures only one variadic argument per command */
+  assertNoMultipleVariadicArguments() {
+    if (this.arguments.some((arg) => arg.multiple)) {
+      throw new Error("Cannot add more than one variadic argument");
+    }
+  }
+  /** Ensures unique argument names across arguments and options */
+  assertArgumentNameNotInUse(name) {
+    if (this.arguments.some((arg) => arg.name === name)) {
+      throw new Error(`Argument name already in use: ${name}`);
+    }
+    if (this.options.some((opt) => opt.name === name)) {
+      throw new Error(`Argument name already in use: ${name}`);
+    }
+  }
+  /** Validates option short names are single alphanumeric characters */
+  assertOptionShortNameIsValid(short) {
+    const isSingleAlphaNumericChar = /^[a-zA-Z0-9]$/.test(short);
+    if (!isSingleAlphaNumericChar) {
+      throw new Error(`Expected short name to be a single alpha-numeric character. Got: ${short}`);
+    }
+  }
+  /** Validates option short names are unique across command hierarchy */
+  assertOptionShortNameNotInUse(short) {
+    for (const opt of this.options) {
+      if (opt.short === short) {
+        throw new Error(`Option short name already in use: -${short}`);
+      }
+    }
+    this.parent?.assertOptionShortNameNotInUse(short);
+  }
+  /** Validates option names are unique across command hierarchy */
+  assertOptionNameNotInUse(name) {
+    if (this.options.some((opt) => opt.name === name)) {
+      throw new Error(`Option name already in use: --${name}`);
+    }
+    this.parent?.assertOptionNameNotInUse(name);
+  }
+  /** Returns command and all ancestor commands in hierarchy */
+  getCommandAndAncestors() {
+    const result = [];
+    let command = this;
+    for (; command; command = command.parent) {
+      result.push(command);
+    }
+    return result;
+  }
+  /** Returns all ancestor commands excluding this command */
+  getAncestors() {
+    return this.getCommandAndAncestors().slice(1);
+  }
+  /** Returns all options from this command and ancestors */
+  getOptionsInclAncestors() {
+    return this.getCommandAndAncestors().flatMap((cmd) => cmd.options);
+  }
+  /** Finds subcommand by name or alias */
+  findCommand(name) {
+    if (!name) return void 0;
+    return this.commands.find((cmd) => cmd.name === name || cmd.aliases.includes(name));
+  }
+  /** Finds option by short or long name */
+  findOption(arg) {
+    return this.options.find((option) => option.short === arg || option.name === arg);
+  }
+  /** Returns a view that is compliant with the CommandHelp interface */
+  createHelpAdapter() {
+    return new CommandHelpAdapter(this);
+  }
+  /** Renders formatted help text using provided help definition */
+  renderHelp(help) {
+    return this.createHelpAdapter().renderHelp(help);
+  }
+}
+export {
+  Command
+};
+//# sourceMappingURL=Command.mjs.map

package/esm/lib/CommandHelpAdapter.mjs

@@ -0,0 +1,98 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+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;
+};
+import lazyProp from "./internal/lazyProp";
+import { Help } from "./Help";
+import { renderHelp } from "./renderHelp";
+const _CommandHelpAdapter = class _CommandHelpAdapter {
+  constructor(cmd) {
+    this.cmd = cmd;
+  }
+  renderHelp(help = new Help()) {
+    return renderHelp(this, help);
+  }
+  get name() {
+    return this.cmd.name;
+  }
+  get aliases() {
+    return this.cmd.aliases;
+  }
+  get summary() {
+    return this.cmd.summary ?? (this.cmd.description.includes("\n") ? this.cmd.description.split("\n")[0] : void 0);
+  }
+  get description() {
+    return this.cmd.description;
+  }
+  get hidden() {
+    return this.cmd.hidden;
+  }
+  get usage() {
+    return [
+      ...this.cmd.options.length ? ["[options]"] : [],
+      ...this.cmd.commands.length ? ["[command]"] : [],
+      ...this.cmd.arguments.map((arg) => this.renderArgumentFlags(arg))
+    ].join(" ");
+  }
+  get group() {
+    return this.cmd.group;
+  }
+  get commands() {
+    return this.cmd.commands.map((c) => new _CommandHelpAdapter(c));
+  }
+  get options() {
+    return this.cmd.options.map((opt) => ({
+      ...opt,
+      flags: this.renderOptionFlags(opt),
+      long: opt.name,
+      optional: !opt.required,
+      negate: false,
+      variadic: opt.multiple
+    }));
+  }
+  get arguments() {
+    return this.cmd.arguments.map((arg) => ({
+      ...arg,
+      variadic: arg.multiple
+    }));
+  }
+  get parent() {
+    return this.cmd.parent ? new _CommandHelpAdapter(this.cmd.parent) : null;
+  }
+  get helpConfiguration() {
+    return { ...this.cmd.helpConfiguration };
+  }
+  renderArgumentFlags(arg) {
+    return arg.required ? arg.multiple ? `<${arg.name}...>` : `<${arg.name}>` : arg.multiple ? `[${arg.name}...]` : `[${arg.name}]`;
+  }
+  renderOptionFlags(opt) {
+    const flags = `-${opt.short}, --${opt.name}`;
+    return opt.type === "boolean" ? flags : opt.required ? opt.multiple ? flags + ` <${opt.argName}...>` : flags + ` <${opt.argName}>` : opt.multiple ? flags + ` [${opt.argName}...]` : flags + ` [${opt.argName}]`;
+  }
+};
+__decorateClass([
+  lazyProp
+], _CommandHelpAdapter.prototype, "usage", 1);
+__decorateClass([
+  lazyProp
+], _CommandHelpAdapter.prototype, "commands", 1);
+__decorateClass([
+  lazyProp
+], _CommandHelpAdapter.prototype, "arguments", 1);
+__decorateClass([
+  lazyProp
+], _CommandHelpAdapter.prototype, "parent", 1);
+__decorateClass([
+  lazyProp
+], _CommandHelpAdapter.prototype, "helpConfiguration", 1);
+let CommandHelpAdapter = _CommandHelpAdapter;
+export {
+  CommandHelpAdapter
+};
+//# sourceMappingURL=CommandHelpAdapter.mjs.map

package/esm/lib/CommanderHelpAdapter.mjs

@@ -0,0 +1,88 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+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;
+};
+import { Help } from "./Help";
+import lazyProp from "./internal/lazyProp";
+import { renderHelp } from "./renderHelp";
+const _CommanderHelpAdapter = class _CommanderHelpAdapter {
+  constructor(cmd) {
+    this.cmd = cmd;
+  }
+  renderHelp(help = new Help()) {
+    return renderHelp(this, help);
+  }
+  get name() {
+    return this.cmd.name();
+  }
+  get aliases() {
+    return this.cmd.aliases();
+  }
+  get summary() {
+    const cmdSummary = this.cmd.summary();
+    return cmdSummary && cmdSummary.trim() !== "" ? cmdSummary : this.cmd.description().includes("\n") ? this.cmd.description().split("\n")[0] : void 0;
+  }
+  get description() {
+    return this.cmd.description();
+  }
+  get hidden() {
+    return Reflect.get(this.cmd, "_hidden");
+  }
+  get usage() {
+    return this.cmd.usage();
+  }
+  get group() {
+    return this.cmd.helpGroup();
+  }
+  get commands() {
+    return this.cmd.commands.map((c) => new _CommanderHelpAdapter(c));
+  }
+  get options() {
+    return this.cmd.options.map((opt) => ({
+      ...opt,
+      short: opt.short ?? opt.attributeName()[0],
+      long: opt.long ?? opt.attributeName()
+    }));
+  }
+  get arguments() {
+    return this.cmd.registeredArguments.map((arg) => ({
+      ...arg,
+      name: arg.name()
+    }));
+  }
+  get parent() {
+    return this.cmd.parent ? new _CommanderHelpAdapter(this.cmd.parent) : null;
+  }
+  get helpConfiguration() {
+    return { ...this.cmd.configureHelp() };
+  }
+};
+__decorateClass([
+  lazyProp
+], _CommanderHelpAdapter.prototype, "summary", 1);
+__decorateClass([
+  lazyProp
+], _CommanderHelpAdapter.prototype, "commands", 1);
+__decorateClass([
+  lazyProp
+], _CommanderHelpAdapter.prototype, "options", 1);
+__decorateClass([
+  lazyProp
+], _CommanderHelpAdapter.prototype, "arguments", 1);
+__decorateClass([
+  lazyProp
+], _CommanderHelpAdapter.prototype, "parent", 1);
+__decorateClass([
+  lazyProp
+], _CommanderHelpAdapter.prototype, "helpConfiguration", 1);
+let CommanderHelpAdapter = _CommanderHelpAdapter;
+export {
+  CommanderHelpAdapter
+};
+//# sourceMappingURL=CommanderHelpAdapter.mjs.map

package/esm/lib/Help.mjs

@@ -0,0 +1,466 @@
+class Help {
+  /** output helpWidth, long lines are wrapped to fit */
+  helpWidth = process.stdout.isTTY ? process.stdout.columns : 80;
+  minWidthToWrap = 40;
+  sortSubcommands;
+  sortOptions;
+  showGlobalOptions;
+  /**
+   * Get an array of the visible subcommands. Includes a placeholder for the implicit help command, if there is one.
+   */
+  visibleCommands(cmd) {
+    const visibleCommands = cmd.commands.filter((cmd2) => !cmd2.hidden);
+    if (this.sortSubcommands) {
+      visibleCommands.sort((a, b) => {
+        return a.name.localeCompare(b.name);
+      });
+    }
+    return visibleCommands;
+  }
+  /**
+   * Compare options for sort.
+   */
+  compareOptions(a, b) {
+    const getSortKey = (option) => {
+      return option.short ? option.short.replace(/^-/, "") : option.long.replace(/^--/, "");
+    };
+    return getSortKey(a).localeCompare(getSortKey(b));
+  }
+  /**
+   * Get an array of the visible options. Includes a placeholder for the implicit help option, if there is one.
+   */
+  visibleOptions(cmd) {
+    const visibleOptions = cmd.options.filter((option) => !option.hidden);
+    if (this.sortOptions) {
+      visibleOptions.sort(this.compareOptions);
+    }
+    return visibleOptions;
+  }
+  /**
+   * Get an array of the visible global options. (Not including help.)
+   */
+  visibleGlobalOptions(cmd) {
+    if (!this.showGlobalOptions) return [];
+    const globalOptions = [];
+    for (let ancestorCmd = cmd.parent; ancestorCmd; ancestorCmd = ancestorCmd.parent) {
+      const visibleOptions = ancestorCmd.options.filter((option) => !option.hidden);
+      globalOptions.push(...visibleOptions);
+    }
+    if (this.sortOptions) {
+      globalOptions.sort(this.compareOptions);
+    }
+    return globalOptions;
+  }
+  /**
+   * Get an array of the arguments if any have a description.
+   */
+  visibleArguments(cmd) {
+    if (cmd.arguments.find((argument) => argument.description)) {
+      return [...cmd.arguments];
+    }
+    return [];
+  }
+  /**
+   * Get the command term to show in the list of subcommands.
+   */
+  subcommandTerm(cmd) {
+    const args = cmd.arguments.map((arg) => humanReadableArgName(arg)).join(" ");
+    return cmd.name + (cmd.aliases[0] ? "|" + cmd.aliases[0] : "") + (cmd.options.length ? " [options]" : "") + // 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;
+  }
+  /**
+   * Get the longest command term length.
+   */
+  longestSubcommandTermLength(cmd, helper) {
+    return helper.visibleCommands(cmd).reduce((max, command) => {
+      return Math.max(max, this.displayWidth(helper.styleSubcommandTerm(helper.subcommandTerm(command))));
+    }, 0);
+  }
+  /**
+   * Get the longest option term length.
+   */
+  longestOptionTermLength(cmd, helper) {
+    return helper.visibleOptions(cmd).reduce((max, option) => {
+      return Math.max(max, this.displayWidth(helper.styleOptionTerm(helper.optionTerm(option))));
+    }, 0);
+  }
+  /**
+   * Get the longest global option term length.
+   */
+  longestGlobalOptionTermLength(cmd, helper) {
+    return helper.visibleGlobalOptions(cmd).reduce((max, option) => {
+      return Math.max(max, this.displayWidth(helper.styleOptionTerm(helper.optionTerm(option))));
+    }, 0);
+  }
+  /**
+   * Get the longest argument term length.
+   */
+  longestArgumentTermLength(cmd, helper) {
+    return helper.visibleArguments(cmd).reduce((max, argument) => {
+      return Math.max(max, this.displayWidth(helper.styleArgumentTerm(helper.argumentTerm(argument))));
+    }, 0);
+  }
+  /**
+   * Get the command usage to be displayed at the top of the built-in help.
+   */
+  commandUsage(cmd) {
+    let cmdName = cmd.name;
+    if (cmd.aliases[0]) {
+      cmdName = cmdName + "|" + cmd.aliases[0];
+    }
+    let ancestorCmdNames = "";
+    for (let ancestorCmd = cmd.parent; ancestorCmd; ancestorCmd = ancestorCmd.parent) {
+      ancestorCmdNames = ancestorCmd.name + " " + ancestorCmdNames;
+    }
+    return ancestorCmdNames + cmdName + " " + cmd.usage;
+  }
+  /**
+   * Get the description for the command.
+   */
+  commandDescription(cmd) {
+    return cmd.description;
+  }
+  /**
+   * Get the subcommand summary to show in the list of subcommands.
+   * (Fallback to description for backwards compatibility.)
+   */
+  subcommandDescription(cmd) {
+    return cmd.summary || cmd.description;
+  }
+  /**
+   * 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 !== void 0) {
+      const boolean = !option.required && !option.optional && !option.negate;
+      const showDefault = option.required || option.optional || boolean && typeof option.defaultValue === "boolean";
+      if (showDefault) {
+        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, helper) {
+    if (items.length === 0) return [];
+    return [helper.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;
+  }
+  /**
+   * Generate the built-in help text.
+   */
+  formatHelp(cmd, helper) {
+    const termWidth = helper.padWidth(cmd, helper);
+    const helpWidth = helper.helpWidth;
+    function callFormatItem(term, description) {
+      return helper.formatItem(term, termWidth, description, helper);
+    }
+    let output = [`${helper.styleTitle("Usage:")} ${helper.styleUsage(helper.commandUsage(cmd))}`, ""];
+    const commandDescription = helper.commandDescription(cmd);
+    if (commandDescription.length > 0) {
+      output = output.concat([helper.boxWrap(helper.styleCommandDescription(commandDescription), helpWidth), ""]);
+    }
+    const argumentList = helper.visibleArguments(cmd).map((argument) => {
+      return callFormatItem(
+        helper.styleArgumentTerm(helper.argumentTerm(argument)),
+        helper.styleArgumentDescription(helper.argumentDescription(argument))
+      );
+    });
+    output = output.concat(this.formatItemList("Arguments:", argumentList, helper));
+    const optionGroups = this.groupItems(
+      cmd.options,
+      helper.visibleOptions(cmd),
+      (option) => option.group ?? "Options:"
+    );
+    optionGroups.forEach((options, group) => {
+      const optionList = options.map((option) => {
+        return callFormatItem(
+          helper.styleOptionTerm(helper.optionTerm(option)),
+          helper.styleOptionDescription(helper.optionDescription(option))
+        );
+      });
+      output = output.concat(this.formatItemList(group, optionList, helper));
+    });
+    if (helper.showGlobalOptions) {
+      const globalOptionList = helper.visibleGlobalOptions(cmd).map((option) => {
+        return callFormatItem(
+          helper.styleOptionTerm(helper.optionTerm(option)),
+          helper.styleOptionDescription(helper.optionDescription(option))
+        );
+      });
+      output = output.concat(this.formatItemList("Global Options:", globalOptionList, helper));
+    }
+    const commandGroups = this.groupItems(
+      cmd.commands,
+      helper.visibleCommands(cmd),
+      (sub) => sub.group || "Commands:"
+    );
+    commandGroups.forEach((commands, group) => {
+      const commandList = commands.map((sub) => {
+        return callFormatItem(
+          helper.styleSubcommandTerm(helper.subcommandTerm(sub)),
+          helper.styleSubcommandDescription(helper.subcommandDescription(sub))
+        );
+      });
+      output = output.concat(this.formatItemList(group, commandList, helper));
+    });
+    return output.join("\n");
+  }
+  /**
+   * Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations.
+   */
+  displayWidth(str) {
+    return stripColor(str).length;
+  }
+  /**
+   * Style the title for displaying in the help. Called with 'Usage:', 'Options:', etc.
+   */
+  styleTitle(str) {
+    return 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) => {
+      if (word === "[options]") return this.styleOptionText(word);
+      if (word === "[command]") return this.styleSubcommandText(word);
+      if (word[0] === "[" || word[0] === "<") return this.styleArgumentText(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 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 this.styleDescriptionText(str);
+  }
+  /**
+   * Base style used by descriptions. Override in subclass to apply custom formatting.
+   */
+  styleDescriptionText(str) {
+    return 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) {
+    return str.split(" ").map((word) => {
+      if (word === "[options]") return this.styleOptionText(word);
+      if (word[0] === "[" || word[0] === "<") return this.styleArgumentText(word);
+      return this.styleSubcommandText(word);
+    }).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;
+  }
+  /**
+   * Calculate the pad width from the maximum term length.
+   */
+  padWidth(cmd, helper) {
+    return Math.max(
+      helper.longestOptionTermLength(cmd, helper),
+      helper.longestGlobalOptionTermLength(cmd, helper),
+      helper.longestSubcommandTermLength(cmd, helper),
+      helper.longestArgumentTermLength(cmd, helper)
+    );
+  }
+  /**
+   * 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, helper) {
+    const itemIndent = 2;
+    const itemIndentStr = " ".repeat(itemIndent);
+    if (!description) return itemIndentStr + term;
+    const paddedTerm = term.padEnd(termWidth + term.length - helper.displayWidth(term));
+    const spacerWidth = 2;
+    const helpWidth = this.helpWidth;
+    const remainingWidth = helpWidth - termWidth - spacerWidth - itemIndent;
+    let formattedDescription;
+    if (remainingWidth < this.minWidthToWrap || helper.preformatted(description)) {
+      formattedDescription = description;
+    } else {
+      const wrappedDescription = helper.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");
+  }
+}
+function stripColor(str) {
+  const sgrPattern = /\x1b\[\d*(;\d*)*m/g;
+  return str.replace(sgrPattern, "");
+}
+function humanReadableArgName(arg) {
+  const nameOutput = arg.name + (arg.variadic === true ? "..." : "");
+  return arg.required ? "<" + nameOutput + ">" : "[" + nameOutput + "]";
+}
+export {
+  Help
+};
+//# sourceMappingURL=Help.mjs.map

package/esm/lib/internal/lazyProp.mjs

@@ -0,0 +1,21 @@
+function lazyProp(target, key, descriptor) {
+  const orig = descriptor.get;
+  if (typeof orig !== "function") {
+    throw new Error('"get" not a function');
+  }
+  descriptor.get = function() {
+    const value = orig.call(this);
+    Object.defineProperty(this, key, {
+      enumerable: false,
+      writable: false,
+      configurable: true,
+      value
+    });
+    return value;
+  };
+  return descriptor;
+}
+export {
+  lazyProp as default
+};
+//# sourceMappingURL=lazyProp.mjs.map

package/esm/lib/renderHelp.mjs

@@ -0,0 +1,9 @@
+import { Help } from "./Help";
+function renderHelp(cmd, help = new Help()) {
+  const helper = Object.assign(help, cmd.helpConfiguration);
+  return helper.formatHelp(cmd, helper);
+}
+export {
+  renderHelp
+};
+//# sourceMappingURL=renderHelp.mjs.map

package/package.json

@@ -1,19 +1,13 @@
 {
   "name": "@bemoje/cli",
   "description": "A type-safe CLI builder focused on command composition and help generation without execution coupling. Parse arguments, generate help, and integrate with existing CLI frameworks through a clean, fluent API.",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "private": false,
   "sideEffects": false,
-  "type": "commonjs",
-  "module": "./index.js",
-  "main": "./index.js",
-  "exports": {
-    ".": "./index.js",
-    "./*": "./lib/*.js",
-    "./package.json": "./package.json",
-    "./index.d.ts": "./index.d.ts"
-  },
-  "typings": "./index.d.ts",
+  "type": "module",
+  "module": "./esm/index.mjs",
+  "main": "./cjs/index.cjs",
+  "typings": "./typings/index.d.ts",
   "dependencies": {},
   "devDependencies": {
     "commander": "^14.0.0"