@bemoje/cli 1.0.5 → 1.1.0

package/lib/Command.js

@@ -1,7 +1,6 @@
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 import { parseArgs } from "node:util";
-import { CommandHelpAdapter } from "./CommandHelpAdapter";
 class Command {
   static {
     __name(this, "Command");
@@ -41,37 +40,6 @@ class Command {
     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;
@@ -96,7 +64,7 @@ class Command {
     this.summary = summary;
     return this;
   }
-  /** Sets command description, joining multiple lines */
+  /** Sets command description, joining variadic lines */
   setDescription(...lines) {
     this.description = lines.join("\n");
     return this;
@@ -127,59 +95,56 @@ class Command {
     return this;
   }
   /** Creates and adds a subcommand */
-  subcommand(name) {
-    const sub = new Command(name, this);
+  addSubcommand(name) {
+    const sub = this.createCommand(name, this);
     this.commands.push(sub);
     return sub;
   }
   /**
    * Adds positional argument with type inference and CLI ordering validation.
    */
-  argument(usage, description, options = {}) {
+  addArgument(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);
+    const props = { name, description };
     if (usage.startsWith("<")) {
       if (nameMatch.endsWith("...")) {
         this.assertNoMultipleVariadicArguments();
         this.arguments.push({
-          name,
-          description,
+          ...options,
+          ...props,
           required: true,
-          multiple: true,
-          ...options
+          variadic: true
         });
       } else {
         this.assertNoOptionalOrVariadicArguments();
         this.arguments.push({
-          name,
-          description,
+          ...options,
+          ...props,
           required: true,
-          multiple: false,
-          ...options
+          variadic: false
         });
       }
     } else if (usage.startsWith("[")) {
       if (nameMatch.endsWith("...")) {
         this.assertNoMultipleVariadicArguments();
         this.arguments.push({
-          name,
-          description,
+          ...options,
+          ...props,
           required: false,
-          multiple: true,
-          defaultValue: options.defaultValue ?? [],
-          ...options
+          variadic: true,
+          defaultValue: options.defaultValue ?? []
         });
       } else {
         this.assertNoVariadicArgument();
         this.arguments.push({
-          name,
-          description,
+          ...options,
+          ...props,
           required: false,
-          multiple: false,
-          ...options
+          variadic: false
         });
       }
     }
@@ -188,77 +153,97 @@ class Command {
   /**
    * 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}`);
+  addOption(flags, description, opts = {}) {
+    const match = flags.match(/^-(.+?), --([a-zA-Z][\w-]*)(?:\s*(<(.+?)>|\[(.+?)\]))?$/);
+    if (!match) throw new Error(`Invalid option format: ${flags}`);
     const short = match[1];
     this.assertOptionShortNameIsValid(short);
     this.assertOptionShortNameNotInUse(short);
     const name = match[2];
     const argName = (match[4] || match[5])?.replace(/\.\.\.$/, "");
     this.assertOptionNameNotInUse(name);
+    const props = {
+      flags,
+      short,
+      long: name,
+      name,
+      description
+    };
     if (!argName) {
-      this.options.push({
+      this._addOption({
         type: "boolean",
-        short,
-        name,
-        description,
-        required: false,
-        multiple: false,
-        ...opts
+        ...opts,
+        ...props,
+        negate: false,
+        optional: true,
+        variadic: false,
+        get multiple() {
+          return this.variadic;
+        }
       });
-    } else if (usage.endsWith(">")) {
-      if (usage.endsWith("...>")) {
-        this.options.push({
+    } else if (flags.endsWith(">")) {
+      if (flags.endsWith("...>")) {
+        this._addOption({
           type: "string",
-          short,
-          name,
+          ...opts,
+          ...props,
           argName,
-          description,
           required: true,
-          multiple: true,
-          ...opts
+          optional: false,
+          variadic: true,
+          get multiple() {
+            return this.variadic;
+          }
         });
       } else {
-        this.options.push({
+        this._addOption({
           type: "string",
-          short,
-          name,
+          ...opts,
+          ...props,
           argName,
-          description,
           required: true,
-          multiple: false,
-          ...opts
+          optional: false,
+          variadic: false,
+          get multiple() {
+            return this.variadic;
+          }
         });
       }
-    } else if (usage.endsWith("]")) {
-      if (usage.endsWith("...]")) {
-        this.options.push({
+    } else if (flags.endsWith("]")) {
+      if (flags.endsWith("...]")) {
+        this._addOption({
           type: "string",
-          short,
-          name,
+          ...opts,
+          ...props,
           argName,
-          description,
           required: false,
-          multiple: true,
-          defaultValue: opts.defaultValue ?? [],
-          ...opts
+          optional: true,
+          variadic: true,
+          get multiple() {
+            return this.variadic;
+          },
+          defaultValue: opts.defaultValue ?? []
         });
       } else {
-        this.options.push({
+        this._addOption({
           type: "string",
-          short,
-          name,
+          ...opts,
+          ...props,
           argName,
-          description,
           required: false,
-          multiple: false,
-          ...opts
+          optional: true,
+          variadic: false,
+          get multiple() {
+            return this.variadic;
+          }
         });
       }
     }
     return this;
   }
+  _addOption(opt) {
+    this.options.push(opt);
+  }
   /**
    * Parses command-line arguments with subcommand support and type-safe validation.
    *
@@ -268,7 +253,7 @@ class Command {
    * // { arguments: ['input.txt'], options: { verbose: true, format: 'json' } }
    * ```
    */
-  parse(argv = process.argv.slice(2), globalOptions = []) {
+  parseArgv(argv = process.argv.slice(2), globalOptions = []) {
     const maybeSubArg = parseArgs({
       args: argv,
       allowPositionals: true,
@@ -278,7 +263,7 @@ class Command {
     }).positionals[0];
     const sub = this.findCommand(maybeSubArg);
     if (sub) {
-      return sub.parse(
+      return sub.parseArgv(
         argv?.filter((a) => a !== maybeSubArg),
         [...globalOptions, ...this.options]
       );
@@ -299,7 +284,7 @@ class Command {
       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") {
+        if (optionDescriptor && optionDescriptor.variadic && optionDescriptor.type === "string") {
           const values = [token.value];
           let j = i + 1;
           while (j < parsed.tokens.length && parsed.tokens[j].kind === "positional") {
@@ -322,13 +307,13 @@ class Command {
       }
     }
     const parsedArguments = this.arguments.map((arg, index) => {
-      if (arg.multiple) {
+      if (arg.variadic) {
         const remainingArgs = parsed.positionals.slice(index);
         return remainingArgs.length > 0 ? remainingArgs : arg.defaultValue ?? [];
       } else {
         return parsed.positionals[index] ?? arg.defaultValue;
       }
-    });
+    }).filter((arg) => arg !== void 0);
     for (const option of this.options) {
       if (!(option.name in parsed.values) && "defaultValue" in option) {
         Reflect.set(parsed.values, option.name, option.defaultValue);
@@ -343,6 +328,11 @@ class Command {
       options: { ...parsed.values }
     };
   }
+  /** Renders formatted help text using provided help definition */
+  renderHelp(help) {
+    const helper = Object.assign(help, this.helpConfiguration);
+    return helper.formatHelp(this, helper);
+  }
   /** Validates CLI argument ordering */
   assertNoOptionalOrVariadicArguments() {
     if (this.arguments.some((arg) => !arg.required)) {
@@ -351,13 +341,13 @@ class Command {
   }
   /** Validates optional args don't follow variadic args */
   assertNoVariadicArgument() {
-    if (this.arguments.some((arg) => arg.multiple)) {
+    if (this.arguments.some((arg) => arg.variadic)) {
       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)) {
+    if (this.arguments.some((arg) => arg.variadic)) {
       throw new Error("Cannot add more than one variadic argument");
     }
   }
@@ -419,13 +409,9 @@ class Command {
   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);
+  /** Returns a new Command instance. Override this method in subclasses. */
+  createCommand(name = "", parent = null) {
+    return new Command(name, parent);
   }
 }
 export {

package/lib/Help.d.ts

@@ -1,3 +1,4 @@
+import { ArgumentDescriptorBase, CommandDescriptor, OptionDescriptorBase } from './Command';
 /**
  * Although this is a class, methods are static in style to allow override using subclass or just functions.
  */
@@ -11,72 +12,72 @@ export declare class Help implements IHelp {
     /**
      * Get an array of the visible subcommands. Includes a placeholder for the implicit help command, if there is one.
      */
-    visibleCommands(cmd: ICommandHelp): ICommandHelp[];
+    visibleCommands(cmd: CommandDescriptor): CommandDescriptor[];
     /**
      * Compare options for sort.
      */
-    compareOptions(a: IOptionHelp, b: IOptionHelp): number;
+    compareOptions(a: OptionDescriptorBase, b: OptionDescriptorBase): number;
     /**
      * Get an array of the visible options. Includes a placeholder for the implicit help option, if there is one.
      */
-    visibleOptions(cmd: ICommandHelp): IOptionHelp[];
+    visibleOptions(cmd: CommandDescriptor): OptionDescriptorBase[];
     /**
      * Get an array of the visible global options. (Not including help.)
      */
-    visibleGlobalOptions(cmd: ICommandHelp): IOptionHelp[];
+    visibleGlobalOptions(cmd: CommandDescriptor): OptionDescriptorBase[];
     /**
      * Get an array of the arguments if any have a description.
      */
-    visibleArguments(cmd: ICommandHelp): IArgumentHelp[];
+    visibleArguments(cmd: CommandDescriptor): ArgumentDescriptorBase[];
     /**
      * Get the command term to show in the list of subcommands.
      */
-    subcommandTerm(cmd: ICommandHelp): string;
+    subcommandTerm(cmd: CommandDescriptor): string;
     /**
      * Get the option term to show in the list of options.
      */
-    optionTerm(option: IOptionHelp): string;
+    optionTerm(option: OptionDescriptorBase): string;
     /**
      * Get the argument term to show in the list of arguments.
      */
-    argumentTerm(argument: IArgumentHelp): string;
+    argumentTerm(argument: ArgumentDescriptorBase): string;
     /**
      * Get the longest command term length.
      */
-    longestSubcommandTermLength(cmd: ICommandHelp, helper: Help): number;
+    longestSubcommandTermLength(cmd: CommandDescriptor, helper: Help): number;
     /**
      * Get the longest option term length.
      */
-    longestOptionTermLength(cmd: ICommandHelp, helper: Help): number;
+    longestOptionTermLength(cmd: CommandDescriptor, helper: Help): number;
     /**
      * Get the longest global option term length.
      */
-    longestGlobalOptionTermLength(cmd: ICommandHelp, helper: Help): number;
+    longestGlobalOptionTermLength(cmd: CommandDescriptor, helper: Help): number;
     /**
      * Get the longest argument term length.
      */
-    longestArgumentTermLength(cmd: ICommandHelp, helper: Help): number;
+    longestArgumentTermLength(cmd: CommandDescriptor, helper: Help): number;
     /**
      * Get the command usage to be displayed at the top of the built-in help.
      */
-    commandUsage(cmd: ICommandHelp): string;
+    commandUsage(cmd: CommandDescriptor): string;
     /**
      * Get the description for the command.
      */
-    commandDescription(cmd: ICommandHelp): string;
+    commandDescription(cmd: CommandDescriptor): string;
     /**
      * Get the subcommand summary to show in the list of subcommands.
      * (Fallback to description for backwards compatibility.)
      */
-    subcommandDescription(cmd: ICommandHelp): string;
+    subcommandDescription(cmd: CommandDescriptor): string;
     /**
      * Get the option description to show in the list of options.
      */
-    optionDescription(option: IOptionHelp): string;
+    optionDescription(option: OptionDescriptorBase): string;
     /**
      * Get the argument description to show in the list of arguments.
      */
-    argumentDescription(argument: IArgumentHelp): string;
+    argumentDescription(argument: ArgumentDescriptorBase): string;
     /**
      * Format a list of items, given a heading and an array of formatted items.
      */
@@ -84,11 +85,11 @@ export declare class Help implements IHelp {
     /**
      * Group items by their help group heading.
      */
-    groupItems<T extends ICommandHelp | IOptionHelp>(unsortedItems: T[], visibleItems: T[], getGroup: (item: T) => string): Map<string, T[]>;
+    groupItems<T extends CommandDescriptor | OptionDescriptorBase>(unsortedItems: T[], visibleItems: T[], getGroup: (item: T) => string): Map<string, T[]>;
     /**
      * Generate the built-in help text.
      */
-    formatHelp(cmd: ICommandHelp, helper: IHelp): string;
+    formatHelp(cmd: CommandDescriptor, helper: IHelp): string;
     /**
      * Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations.
      */
@@ -152,7 +153,7 @@ export declare class Help implements IHelp {
     /**
      * Calculate the pad width from the maximum term length.
      */
-    padWidth(cmd: ICommandHelp, helper: Help): number;
+    padWidth(cmd: CommandDescriptor, helper: Help): number;
     /**
      * Detect manually wrapped and indented strings by checking for line break followed by whitespace.
      */
@@ -171,71 +172,28 @@ export declare class Help implements IHelp {
      */
     boxWrap(str: string, width: number): string;
 }
-/**
- * Interface for a command object used to generate help.
- */
-export interface ICommandHelp {
-    name: string;
-    aliases: string[];
-    summary?: string;
-    description: string;
-    hidden?: boolean;
-    usage: string;
-    group?: string;
-    commands: ICommandHelp[];
-    options: IOptionHelp[];
-    arguments: IArgumentHelp[];
-    parent: ICommandHelp | null;
-    helpConfiguration?: Partial<IHelp>;
-}
-export interface IArgumentHelp {
-    name: string;
-    description: string;
-    required: boolean;
-    variadic: boolean;
-    defaultValue?: string | string[];
-    defaultValueDescription?: string;
-    choices?: string[];
-}
-export interface IOptionHelp {
-    group?: string;
-    flags: string;
-    description: string;
-    short: string;
-    long: string;
-    required?: boolean;
-    optional?: boolean;
-    variadic?: boolean;
-    negate?: boolean;
-    defaultValue?: boolean | string | string[];
-    defaultValueDescription?: string;
-    env?: string;
-    choices?: string[];
-    hidden?: boolean;
-    global?: boolean;
-}
 export interface IHelp {
     helpWidth: number;
     minWidthToWrap: number;
     sortSubcommands?: boolean;
     sortOptions?: boolean;
     showGlobalOptions?: boolean;
-    subcommandTerm(cmd: ICommandHelp): string;
-    subcommandDescription(cmd: ICommandHelp): string;
-    optionTerm(option: IOptionHelp): string;
-    optionDescription(option: IOptionHelp): string;
-    argumentTerm(argument: IArgumentHelp): string;
-    argumentDescription(argument: IArgumentHelp): string;
-    commandUsage(cmd: ICommandHelp): string;
-    commandDescription(cmd: ICommandHelp): string;
-    visibleCommands(cmd: ICommandHelp): ICommandHelp[];
-    visibleOptions(cmd: ICommandHelp): IOptionHelp[];
-    visibleGlobalOptions(cmd: ICommandHelp): IOptionHelp[];
-    visibleArguments(cmd: ICommandHelp): IArgumentHelp[];
-    longestSubcommandTermLength(cmd: ICommandHelp, helper: IHelp): number;
-    longestOptionTermLength(cmd: ICommandHelp, helper: IHelp): number;
-    longestGlobalOptionTermLength(cmd: ICommandHelp, helper: IHelp): number;
-    longestArgumentTermLength(cmd: ICommandHelp, helper: IHelp): number;
+    subcommandTerm(cmd: CommandDescriptor): string;
+    subcommandDescription(cmd: CommandDescriptor): string;
+    optionTerm(option: OptionDescriptorBase): string;
+    optionDescription(option: OptionDescriptorBase): string;
+    argumentTerm(argument: ArgumentDescriptorBase): string;
+    argumentDescription(argument: ArgumentDescriptorBase): string;
+    commandUsage(cmd: CommandDescriptor): string;
+    commandDescription(cmd: CommandDescriptor): string;
+    visibleCommands(cmd: CommandDescriptor): CommandDescriptor[];
+    visibleOptions(cmd: CommandDescriptor): OptionDescriptorBase[];
+    visibleGlobalOptions(cmd: CommandDescriptor): OptionDescriptorBase[];
+    visibleArguments(cmd: CommandDescriptor): ArgumentDescriptorBase[];
+    longestSubcommandTermLength(cmd: CommandDescriptor, helper: IHelp): number;
+    longestOptionTermLength(cmd: CommandDescriptor, helper: IHelp): number;
+    longestGlobalOptionTermLength(cmd: CommandDescriptor, helper: IHelp): number;
+    longestArgumentTermLength(cmd: CommandDescriptor, helper: IHelp): number;
     displayWidth(str: string): number;
     styleTitle(title: string): string;
     styleUsage(str: string): string;
@@ -251,13 +209,13 @@ export interface IHelp {
     styleOptionText(str: string): string;
     styleSubcommandText(str: string): string;
     styleArgumentText(str: string): string;
-    compareOptions(a: IOptionHelp, b: IOptionHelp): number;
-    padWidth(cmd: ICommandHelp, helper: IHelp): number;
+    compareOptions(a: OptionDescriptorBase, b: OptionDescriptorBase): number;
+    padWidth(cmd: CommandDescriptor, helper: IHelp): number;
     boxWrap(str: string, width: number): string;
     preformatted(str: string): boolean;
     formatItem(term: string, termWidth: number, description: string, helper: IHelp): string;
     formatItemList(heading: string, items: string[], helper: IHelp): string[];
-    groupItems<T extends ICommandHelp | IOptionHelp>(unsortedItems: T[], visibleItems: T[], getGroup: (item: T) => string): Map<string, T[]>;
-    formatHelp(cmd: ICommandHelp, helper: IHelp): string;
+    groupItems<T extends CommandDescriptor | OptionDescriptorBase>(unsortedItems: T[], visibleItems: T[], getGroup: (item: T) => string): Map<string, T[]>;
+    formatHelp(cmd: CommandDescriptor, helper: IHelp): string;
 }
 //# sourceMappingURL=Help.d.ts.map

package/lib/Help.js

@@ -69,7 +69,10 @@ class Help {
    * Get the command term to show in the list of subcommands.
    */
   subcommandTerm(cmd) {
-    const args = cmd.arguments.map((arg) => humanReadableArgName(arg)).join(" ");
+    const args = cmd.arguments.map((arg) => {
+      const nameOutput = arg.name + (arg.variadic === true ? "..." : "");
+      return arg.required ? "<" + nameOutput + ">" : "[" + nameOutput + "]";
+    }).join(" ");
     return cmd.name + (cmd.aliases[0] ? "|" + cmd.aliases[0] : "") + (cmd.options.length ? " [options]" : "") + // simplistic check for non-help option
     (args ? " " + args : "");
   }
@@ -129,7 +132,13 @@ class Help {
     for (let ancestorCmd = cmd.parent; ancestorCmd; ancestorCmd = ancestorCmd.parent) {
       ancestorCmdNames = ancestorCmd.name + " " + ancestorCmdNames;
     }
-    return ancestorCmdNames + cmdName + " " + cmd.usage;
+    return ancestorCmdNames + cmdName + " " + [
+      ...cmd.options.length ? ["[options]"] : [],
+      ...cmd.commands.length ? ["[command]"] : [],
+      ...cmd.arguments.map((arg) => {
+        return arg.required ? arg.variadic ? `<${arg.name}...>` : `<${arg.name}>` : arg.variadic ? `[${arg.name}...]` : `[${arg.name}]`;
+      })
+    ].join(" ");
   }
   /**
    * Get the description for the command.
@@ -142,7 +151,7 @@ class Help {
    * (Fallback to description for backwards compatibility.)
    */
   subcommandDescription(cmd) {
-    return cmd.summary || cmd.description;
+    return cmd.summary || (cmd.description.includes("\n") ? cmd.description.split("\n")[0] : "");
   }
   /**
    * Get the option description to show in the list of options.
@@ -287,7 +296,8 @@ class Help {
    * Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations.
    */
   displayWidth(str) {
-    return stripColor(str).length;
+    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.
@@ -458,16 +468,6 @@ ${itemIndentStr}`);
     return wrappedLines.join("\n");
   }
 }
-function stripColor(str) {
-  const sgrPattern = /\x1b\[\d*(;\d*)*m/g;
-  return str.replace(sgrPattern, "");
-}
-__name(stripColor, "stripColor");
-function humanReadableArgName(arg) {
-  const nameOutput = arg.name + (arg.variadic === true ? "..." : "");
-  return arg.required ? "<" + nameOutput + ">" : "[" + nameOutput + "]";
-}
-__name(humanReadableArgName, "humanReadableArgName");
 export {
   Help
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.5",
+  "description": "A type-safe CLI composer that can parse argv and generate help without execution coupling.",
+  "version": "1.1.0",
   "private": false,
   "sideEffects": false,
   "type": "module",
@@ -16,7 +16,8 @@
   "typings": "./index.d.ts",
   "dependencies": {},
   "devDependencies": {
-    "commander": "^14.0.0"
+    "commander": "^14.0.0",
+    "type-fest": "4.41.0"
   },
   "license": "MIT",
   "repository": {
@@ -26,11 +27,8 @@
   "keywords": [
     "cli",
     "command-line",
-    "argument-parser",
-    "options-parser",
     "typescript",
     "type-safe",
-    "fluent-api",
     "help-generation",
     "commander",
     "commander.js",
@@ -38,7 +36,6 @@
     "validation",
     "parsing",
     "composition",
-    "adapter",
     "terminal",
     "console",
     "args",