@bemoje/cli 0.2.0 → 0.3.0

package/lib/CommanderHelpAdapter.d.ts

@@ -0,0 +1,56 @@
+import type { Command as Commander } from 'commander';
+import { type ICommandHelp, type IHelp } from './Help';
+/**
+ * Adapter for commander.js @see Command instances that implements the @see ICommandHelp interface required by the Help system.
+ *
+ * @example ```ts
+ * import { Command } from 'commander'
+ * const cmd = new Command('myapp')
+ * new CommanderHelpAdapter(cmd).renderHelp()
+ * ```
+ */
+export declare class CommanderHelpAdapter implements ICommandHelp {
+    cmd: Commander;
+    constructor(cmd: Commander);
+    renderHelp(help?: IHelp): string;
+    get name(): string;
+    get aliases(): string[];
+    get summary(): string;
+    get description(): string;
+    get hidden(): any;
+    get usage(): string;
+    get group(): string;
+    get commands(): CommanderHelpAdapter[];
+    get options(): {
+        short: string;
+        long: string;
+        flags: string;
+        description: string;
+        required: boolean;
+        optional: boolean;
+        variadic: boolean;
+        mandatory: boolean;
+        negate: boolean;
+        defaultValue?: any;
+        defaultValueDescription?: string;
+        presetArg?: unknown;
+        envVar?: string;
+        parseArg?: <T>(value: string, previous: T) => T;
+        hidden: boolean;
+        argChoices?: string[];
+        helpGroupHeading?: string;
+    }[];
+    get arguments(): {
+        name: string;
+        description: string;
+        required: boolean;
+        variadic: boolean;
+        defaultValue?: any;
+        defaultValueDescription?: string;
+        parseArg?: <T>(value: string, previous: T) => T;
+        argChoices?: string[];
+    }[];
+    get parent(): ICommandHelp | null;
+    get helpConfiguration(): Partial<IHelp>;
+}
+//# sourceMappingURL=CommanderHelpAdapter.d.ts.map

package/lib/CommanderHelpAdapter.js

@@ -0,0 +1,90 @@
+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 { 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() };
+  }
+};
+__name(_CommanderHelpAdapter, "CommanderHelpAdapter");
+__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.js.map

package/lib/Help.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Although this is a class, methods are static in style to allow override using subclass or just functions.
+ */
+export declare class Help implements IHelp {
+    /** output helpWidth, long lines are wrapped to fit */
+    helpWidth: number;
+    minWidthToWrap: number;
+    sortSubcommands?: boolean;
+    sortOptions?: boolean;
+    showGlobalOptions?: boolean;
+    /**
+     * Get an array of the visible subcommands. Includes a placeholder for the implicit help command, if there is one.
+     */
+    visibleCommands(cmd: ICommandHelp): ICommandHelp[];
+    /**
+     * Compare options for sort.
+     */
+    compareOptions(a: IOptionHelp, b: IOptionHelp): number;
+    /**
+     * Get an array of the visible options. Includes a placeholder for the implicit help option, if there is one.
+     */
+    visibleOptions(cmd: ICommandHelp): IOptionHelp[];
+    /**
+     * Get an array of the visible global options. (Not including help.)
+     */
+    visibleGlobalOptions(cmd: ICommandHelp): IOptionHelp[];
+    /**
+     * Get an array of the arguments if any have a description.
+     */
+    visibleArguments(cmd: ICommandHelp): IArgumentHelp[];
+    /**
+     * Get the command term to show in the list of subcommands.
+     */
+    subcommandTerm(cmd: ICommandHelp): string;
+    /**
+     * Get the option term to show in the list of options.
+     */
+    optionTerm(option: IOptionHelp): string;
+    /**
+     * Get the argument term to show in the list of arguments.
+     */
+    argumentTerm(argument: IArgumentHelp): string;
+    /**
+     * Get the longest command term length.
+     */
+    longestSubcommandTermLength(cmd: ICommandHelp, helper: Help): number;
+    /**
+     * Get the longest option term length.
+     */
+    longestOptionTermLength(cmd: ICommandHelp, helper: Help): number;
+    /**
+     * Get the longest global option term length.
+     */
+    longestGlobalOptionTermLength(cmd: ICommandHelp, helper: Help): number;
+    /**
+     * Get the longest argument term length.
+     */
+    longestArgumentTermLength(cmd: ICommandHelp, helper: Help): number;
+    /**
+     * Get the command usage to be displayed at the top of the built-in help.
+     */
+    commandUsage(cmd: ICommandHelp): string;
+    /**
+     * Get the description for the command.
+     */
+    commandDescription(cmd: ICommandHelp): string;
+    /**
+     * Get the subcommand summary to show in the list of subcommands.
+     * (Fallback to description for backwards compatibility.)
+     */
+    subcommandDescription(cmd: ICommandHelp): string;
+    /**
+     * Get the option description to show in the list of options.
+     */
+    optionDescription(option: IOptionHelp): string;
+    /**
+     * Get the argument description to show in the list of arguments.
+     */
+    argumentDescription(argument: IArgumentHelp): string;
+    /**
+     * Format a list of items, given a heading and an array of formatted items.
+     */
+    formatItemList(heading: string, items: string[], helper: Help): string[];
+    /**
+     * Group items by their help group heading.
+     */
+    groupItems<T extends ICommandHelp | IOptionHelp>(unsortedItems: T[], visibleItems: T[], getGroup: (item: T) => string): Map<string, T[]>;
+    /**
+     * Generate the built-in help text.
+     */
+    formatHelp(cmd: ICommandHelp, helper: IHelp): string;
+    /**
+     * Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations.
+     */
+    displayWidth(str: string): number;
+    /**
+     * Style the title for displaying in the help. Called with 'Usage:', 'Options:', etc.
+     */
+    styleTitle(str: string): string;
+    /**
+     * Style the usage line for displaying in the help. Applies specific styling to different parts like options, commands, and arguments.
+     */
+    styleUsage(str: string): string;
+    /**
+     * Style command descriptions for display in help output.
+     */
+    styleCommandDescription(str: string): string;
+    /**
+     * Style option descriptions for display in help output.
+     */
+    styleOptionDescription(str: string): string;
+    /**
+     * Style subcommand descriptions for display in help output.
+     */
+    styleSubcommandDescription(str: string): string;
+    /**
+     * Style argument descriptions for display in help output.
+     */
+    styleArgumentDescription(str: string): string;
+    /**
+     * Base style used by descriptions. Override in subclass to apply custom formatting.
+     */
+    styleDescriptionText(str: string): string;
+    /**
+     * Style option terms (flags) for display in help output.
+     */
+    styleOptionTerm(str: string): string;
+    /**
+     * Style subcommand terms for display in help output. Applies specific styling to different parts like options and arguments.
+     */
+    styleSubcommandTerm(str: string): string;
+    /**
+     * Style argument terms for display in help output.
+     */
+    styleArgumentTerm(str: string): string;
+    /**
+     * Base style used in terms and usage for options. Override in subclass to apply custom formatting.
+     */
+    styleOptionText(str: string): string;
+    /**
+     * Base style used in terms and usage for arguments. Override in subclass to apply custom formatting.
+     */
+    styleArgumentText(str: string): string;
+    /**
+     * Base style used in terms and usage for subcommands. Override in subclass to apply custom formatting.
+     */
+    styleSubcommandText(str: string): string;
+    /**
+     * Base style used in terms and usage for commands. Override in subclass to apply custom formatting.
+     */
+    styleCommandText(str: string): string;
+    /**
+     * Calculate the pad width from the maximum term length.
+     */
+    padWidth(cmd: ICommandHelp, helper: Help): number;
+    /**
+     * Detect manually wrapped and indented strings by checking for line break followed by whitespace.
+     */
+    preformatted(str: string): boolean;
+    /**
+     * 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: string, termWidth: number, description: string, helper: Help): string;
+    /**
+     * Wrap a string at whitespace, preserving existing line breaks.
+     * Wrapping is skipped if the width is less than `minWidthToWrap`.
+     */
+    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;
+    displayWidth(str: string): number;
+    styleTitle(title: string): string;
+    styleUsage(str: string): string;
+    styleCommandText(str: string): string;
+    styleCommandDescription(str: string): string;
+    styleOptionDescription(str: string): string;
+    styleSubcommandDescription(str: string): string;
+    styleArgumentDescription(str: string): string;
+    styleDescriptionText(str: string): string;
+    styleOptionTerm(str: string): string;
+    styleSubcommandTerm(str: string): string;
+    styleArgumentTerm(str: string): string;
+    styleOptionText(str: string): string;
+    styleSubcommandText(str: string): string;
+    styleArgumentText(str: string): string;
+    compareOptions(a: IOptionHelp, b: IOptionHelp): number;
+    padWidth(cmd: ICommandHelp, 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;
+}
+//# sourceMappingURL=Help.d.ts.map