@bemoje/cli 0.2.0 → 0.3.0

package/lib/Command.js

@@ -0,0 +1,435 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+import { parseArgs } from "node:util";
+import { CommandHelpAdapter } from "./CommandHelpAdapter";
+const _Command = class _Command {
+  constructor(name = "", parent = null) {
+    /** Command name used for invocation */
+    __publicField(this, "name");
+    /** Optional version string */
+    __publicField(this, "version");
+    /** Alternative names for this command */
+    __publicField(this, "aliases");
+    /** Brief single-line description */
+    __publicField(this, "summary");
+    /** Full command description */
+    __publicField(this, "description");
+    /** Whether command should be hidden from help */
+    __publicField(this, "hidden");
+    /** Group name for organizing commands in help */
+    __publicField(this, "group");
+    /** Parent command if this is a subcommand */
+    __publicField(this, "parent");
+    /** Child subcommands */
+    __publicField(this, "commands");
+    /** Positional arguments */
+    __publicField(this, "arguments");
+    /** Named options/flags */
+    __publicField(this, "options");
+    /** Help system configuration */
+    __publicField(this, "helpConfiguration");
+    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);
+  }
+};
+__name(_Command, "Command");
+let Command = _Command;
+export {
+  Command
+};
+//# sourceMappingURL=Command.js.map

package/lib/CommandHelpAdapter.d.ts

@@ -0,0 +1,157 @@
+import { Command, ArgumentDescriptor, ArgumentUsage, OptionDescriptor, OptionUsage } from './Command';
+import { type ICommandHelp, type IHelp } from './Help';
+/**
+ * Adapter for @see Command instances that implements the @see ICommandHelp interface required by the Help system.
+ * Used internally by the @see Command.prototype.renderHelp method.
+ */
+export declare class CommandHelpAdapter implements ICommandHelp {
+    cmd: Command;
+    constructor(cmd: Command);
+    renderHelp(help?: IHelp): string;
+    get name(): string;
+    get aliases(): string[];
+    get summary(): string;
+    get description(): string;
+    get hidden(): boolean;
+    get usage(): string;
+    get group(): string;
+    get commands(): ICommandHelp[];
+    get options(): ({
+        flags: string;
+        long: string;
+        optional: boolean;
+        negate: boolean;
+        variadic: boolean;
+        type: "boolean";
+        argName?: never;
+        required: false;
+        multiple: false;
+        defaultValue?: boolean;
+        defaultValueDescription?: string;
+        short: string;
+        name: string;
+        description: string;
+        env?: string;
+        hidden?: boolean;
+        choices?: string[];
+        group?: string;
+    } | {
+        flags: string;
+        long: string;
+        optional: boolean;
+        negate: boolean;
+        variadic: boolean;
+        type: "string";
+        argName: string;
+        required: true;
+        multiple: false;
+        defaultValue?: never;
+        defaultValueDescription?: never;
+        short: string;
+        name: string;
+        description: string;
+        env?: string;
+        hidden?: boolean;
+        choices?: string[];
+        group?: string;
+    } | {
+        flags: string;
+        long: string;
+        optional: boolean;
+        negate: boolean;
+        variadic: boolean;
+        type: "string";
+        argName: string;
+        required: false;
+        multiple: false;
+        defaultValue?: string;
+        defaultValueDescription?: string;
+        short: string;
+        name: string;
+        description: string;
+        env?: string;
+        hidden?: boolean;
+        choices?: string[];
+        group?: string;
+    } | {
+        flags: string;
+        long: string;
+        optional: boolean;
+        negate: boolean;
+        variadic: boolean;
+        type: "string";
+        argName: string;
+        required: true;
+        multiple: true;
+        defaultValue?: never;
+        defaultValueDescription?: never;
+        short: string;
+        name: string;
+        description: string;
+        env?: string;
+        hidden?: boolean;
+        choices?: string[];
+        group?: string;
+    } | {
+        flags: string;
+        long: string;
+        optional: boolean;
+        negate: boolean;
+        variadic: boolean;
+        type: "string";
+        argName: string;
+        required: false;
+        multiple: true;
+        defaultValue?: string[];
+        defaultValueDescription?: string;
+        short: string;
+        name: string;
+        description: string;
+        env?: string;
+        hidden?: boolean;
+        choices?: string[];
+        group?: string;
+    })[];
+    get arguments(): ({
+        variadic: boolean;
+        multiple: false;
+        required: true;
+        defaultValue?: never;
+        defaultValueDescription?: never;
+        name: string;
+        description: string;
+        choices?: string[];
+    } | {
+        variadic: boolean;
+        required: false;
+        multiple: false;
+        defaultValue?: string;
+        defaultValueDescription?: string;
+        name: string;
+        description: string;
+        choices?: string[];
+    } | {
+        variadic: boolean;
+        required: true;
+        multiple: true;
+        defaultValue?: never;
+        defaultValueDescription?: never;
+        name: string;
+        description: string;
+        choices?: string[];
+    } | {
+        variadic: boolean;
+        required: false;
+        multiple: true;
+        defaultValue?: string[];
+        defaultValueDescription?: string;
+        name: string;
+        description: string;
+        choices?: string[];
+    })[];
+    get parent(): ICommandHelp | null;
+    get helpConfiguration(): Partial<IHelp>;
+    renderArgumentFlags(arg: ArgumentDescriptor): ArgumentUsage;
+    renderOptionFlags(opt: OptionDescriptor): OptionUsage;
+}
+//# sourceMappingURL=CommandHelpAdapter.d.ts.map

package/lib/CommandHelpAdapter.js

@@ -0,0 +1,100 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: 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;
+};
+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}]`;
+  }
+};
+__name(_CommandHelpAdapter, "CommandHelpAdapter");
+__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.js.map