@bemoje/cli 1.1.1 → 2.0.0

package/README.md

@@ -1,246 +0,0 @@
-# @bemoje/cli
-
-A type-safe CLI composer that can parse argv and generate help without execution coupling.
-
-## Key Features
-
-- **🎯 Composition-Focused**: Build command structures without execution logic.
-- **🔒 Type-Safe**: Full TypeScript support with type inference for arguments and options
-- **🎨 Flexible Help**: Fork of commander.js Help class with enhanced API and adapter support
-- **✅ Validation**: Built-in CLI argument ordering validation and name conflict detection
-
-## Quick Start
-
-```ts
-import { Command } from '@bemoje/cli'
-
-const cmd = new Command('myapp')
-  .setVersion('1.0.0')
-  .setDescription('My awesome CLI application')
-  .addArgument('<input>', 'Input file path')
-  .addArgument('[output]', 'Output file path', { defaultValue: 'out.txt' })
-  .addOption('-v, --verbose', 'Enable verbose output')
-  .addOption('-f, --format <type>', 'Output format', { choices: ['json', 'xml', 'yaml'] })
-
-console.log(cmd.parseArgv(['input.txt', '-v', '-f', 'json']))
-// {
-//   command: [Getter],
-//   arguments: [ 'input.txt', 'out.txt' ],
-//   options: { verbose: true, format: 'json' }
-// }
-```
-
-## Command Definition
-
-### Basic Setup
-
-```ts
-const cmd = new Command('myapp')
-  .setVersion('1.0.0')
-  .setDescription('Application description')
-  .setSummary('Short summary for help')
-  .setAliases(['app', 'my-app'])
-```
-
-### Arguments (Positional)
-
-Arguments follow strict ordering rules: required → optional → variadic
-
-```ts
-// Required argument
-cmd.addArgument('<input>', 'Input file path')
-
-// Optional argument with default
-cmd.addArgument('[output]', 'Output file path', { defaultValue: 'dist/output.txt' })
-
-// Required variadic (multiple values)
-cmd.addArgument('<files...>', 'Multiple input files')
-
-// Optional variadic with defaults
-cmd.addArgument('[patterns...]', 'Glob patterns', { defaultValue: ['**/*.js'] })
-```
-
-### Options (Named Parameters)
-
-```ts
-// Boolean flag
-cmd.addOption('-v, --verbose', 'Enable verbose output')
-
-// Required string option
-cmd.addOption('-f, --format <type>', 'Output format')
-
-// Optional string option with default
-cmd.addOption('-o, --output [path]', 'Output directory', { defaultValue: 'dist' })
-
-// Required variadic option
-cmd.addOption('-i, --include <patterns...>', 'Include patterns')
-
-// Optional variadic option with defaults
-cmd.addOption('-e, --exclude [patterns...]', 'Exclude patterns', {
-  defaultValue: ['node_modules', '.git'],
-})
-
-// Option with choices and environment variable
-cmd.addOption('-l, --log-level [level]', 'Log level', {
-  choices: ['error', 'warn', 'info', 'debug'],
-  defaultValue: 'info',
-  env: 'LOG_LEVEL',
-})
-```
-
-### Global Options
-
-Options defined on parent commands are available to subcommands:
-
-```ts
-const app = new Command('myapp').addOption('-c, --config <file>', 'Config file')
-
-app.addSubcommand('build').addOption('-w, --watch', 'Watch mode')
-
-// Both --config and --watch are available to 'build' subcommand
-const result = app.parseArgv(['build', '--config', 'myconfig.json', '--watch'])
-```
-
-### Subcommands
-
-```ts
-const cmd = new Command('git')
-
-// Create subcommand
-const add = cmd
-  .addSubcommand('add')
-  .setDescription('Add files to staging area')
-  .addArgument('<files...>', 'Files to add')
-  .addOption('-A, --all', 'Add all files')
-
-const commit = cmd
-  .addSubcommand('commit')
-  .setDescription('Create a commit')
-  .addArgument('[message]', 'Commit message')
-  .addOption('-m, --message <msg>', 'Commit message')
-  .addOption('-a, --all', 'Commit all changes')
-
-// Parsing automatically routes to subcommands
-const result = cmd.parseArgv(['add', 'file1.js', 'file2.js', '-A'])
-// result.command === add subcommand instance
-```
-
-## Help System
-
-### Rendering Help
-
-```ts
-import { Help } from '@bemoje/cli'
-
-// Use help formatting (requires Help instance)
-const help = new Help()
-console.log(cmd.renderHelp(help))
-
-// Customize help configuration
-const customHelp = new Help()
-customHelp.helpWidth = 100
-customHelp.sortOptions = true
-customHelp.showGlobalOptions = true
-console.log(cmd.renderHelp(customHelp))
-```
-
-### Help Configuration
-
-Configure help behavior per command:
-
-```ts
-cmd.setHelpConfiguration({
-  sortOptions: true,
-  sortSubcommands: true,
-  showGlobalOptions: false,
-  helpWidth: 80,
-})
-```
-
-### Custom Help Styling
-
-It may be more convenient to extend the Help class for more extensive customization.
-
-```ts
-import { Help } from '@bemoje/cli'
-
-class ColoredHelp extends Help {
-  styleTitle(str: string): string {
-    return `\x1b[1m${str}\x1b[0m` // Bold
-  }
-
-  styleOptionText(str: string): string {
-    return `\x1b[36m${str}\x1b[0m` // Cyan
-  }
-
-  styleArgumentText(str: string): string {
-    return `\x1b[33m${str}\x1b[0m` // Yellow
-  }
-}
-
-console.log(cmd.renderHelp(new ColoredHelp()))
-```
-
-## Validation
-
-Commands automatically validate:
-
-- Argument ordering (required before optional before variadic)
-
-```ts
-cmd.addArgument('[optional]', 'Optional arg').addArgument('<required>', 'Required arg')
-//=> ❌ Error!
-```
-
-- Unique option names and short flags, including globals across parent/child commands
-
-```ts
-cmd.addOption('-v, --verbose', 'Verbose output').addOption('-v, --video', 'Video mode')
-//=> ❌ Error!
-```
-
-- Single variadic argument per command
-
-```ts
-cmd.addArgument('<files...>', 'First variadic').addArgument('<more...>', 'Second variadic')
-//=> ❌ Error!
-```
-
-## Command Class
-
-**Constructor**:
-
-```ts
-- new (name: string, parent?: Command): Command
-```
-
-**Structure Methods**:
-
-```ts
-- addArgument(usage, description, options?): this
-- addOption(usage, description, options?): this
-- addSubcommand(name: string): Command
-```
-
-**Configuration Methods**:
-
-```ts
-- setVersion(version?: string): this
-- setName(name: string): this
-- setDescription(...lines: string[]): this
-- setSummary(summary?: string): this
-- setHidden(hidden?: boolean): this
-- setGroup(group?: string): this
-- setHelpConfiguration(config?: Partial<IHelp>): this
-- extendHelpConfiguration(config: Partial<IHelp>): this
-- setAliases(...aliases: (string | string[])[]): this
-- addAliases(...aliases: (string | string[])[]): this
-- setParent(parent: Command | null): this
-```
-
-**Parsing & Help**:
-
-```ts
-- parseArgv(argv?: string[], globalOptions?: OptionDescriptor[]): ParseResult
-- renderHelp(help: IHelp): string
-```

package/index.js

@@ -1,3 +0,0 @@
-export * from "./lib/Command.js";
-export * from "./lib/Help.js";
-//# sourceMappingURL=index.js.map

package/lib/Command.js

@@ -1,421 +0,0 @@
-var __defProp = Object.defineProperty;
-var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
-import { parseArgs } from "node:util";
-import { Help } from "./Help.js";
-class Command {
-  static {
-    __name(this, "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 });
-  }
-  /** 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 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;
-  }
-  /** 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 */
-  addSubcommand(name) {
-    const sub = this.createCommand(name, this);
-    this.commands.push(sub);
-    return sub;
-  }
-  /**
-   * Adds positional argument with type inference and CLI ordering validation.
-   */
-  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({
-          ...options,
-          ...props,
-          required: true,
-          variadic: true
-        });
-      } else {
-        this.assertNoOptionalOrVariadicArguments();
-        this.arguments.push({
-          ...options,
-          ...props,
-          required: true,
-          variadic: false
-        });
-      }
-    } else if (usage.startsWith("[")) {
-      if (nameMatch.endsWith("...")) {
-        this.assertNoMultipleVariadicArguments();
-        this.arguments.push({
-          ...options,
-          ...props,
-          required: false,
-          variadic: true,
-          defaultValue: options.defaultValue ?? []
-        });
-      } else {
-        this.assertNoVariadicArgument();
-        this.arguments.push({
-          ...options,
-          ...props,
-          required: false,
-          variadic: false
-        });
-      }
-    }
-    return this;
-  }
-  /**
-   * Adds command-line option with type inference. Parses format: `-s, --long [<value>|[value]|<value...>|[value...]]`
-   */
-  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._addOption({
-        type: "boolean",
-        ...opts,
-        ...props,
-        negate: false,
-        optional: true,
-        variadic: false,
-        get multiple() {
-          return this.variadic;
-        }
-      });
-    } else if (flags.endsWith(">")) {
-      if (flags.endsWith("...>")) {
-        this._addOption({
-          type: "string",
-          ...opts,
-          ...props,
-          argName,
-          required: true,
-          optional: false,
-          variadic: true,
-          get multiple() {
-            return this.variadic;
-          }
-        });
-      } else {
-        this._addOption({
-          type: "string",
-          ...opts,
-          ...props,
-          argName,
-          required: true,
-          optional: false,
-          variadic: false,
-          get multiple() {
-            return this.variadic;
-          }
-        });
-      }
-    } else if (flags.endsWith("]")) {
-      if (flags.endsWith("...]")) {
-        this._addOption({
-          type: "string",
-          ...opts,
-          ...props,
-          argName,
-          required: false,
-          optional: true,
-          variadic: true,
-          get multiple() {
-            return this.variadic;
-          },
-          defaultValue: opts.defaultValue ?? []
-        });
-      } else {
-        this._addOption({
-          type: "string",
-          ...opts,
-          ...props,
-          argName,
-          required: false,
-          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.
-   *
-   * @example
-   * ```typescript
-   * const result = cmd.parse(['input.txt', '-v', '--format', 'json'])
-   * // { arguments: ['input.txt'], options: { verbose: true, format: 'json' } }
-   * ```
-   */
-  parseArgv(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.parseArgv(
-        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.variadic && 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.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);
-      }
-    }
-    const self = this;
-    return {
-      get command() {
-        return self;
-      },
-      arguments: parsedArguments,
-      options: { ...parsed.values }
-    };
-  }
-  /** Renders formatted help text using provided help definition */
-  renderHelp(help = new 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)) {
-      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.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.variadic)) {
-      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 new Command instance. Override this method in subclasses. */
-  createCommand(name = "", parent = null) {
-    return new Command(name, parent);
-  }
-}
-export {
-  Command
-};
-//# sourceMappingURL=Command.js.map