mixcli 3.0.0

package/dist/index.d.mts

@@ -0,0 +1,410 @@
+import { LiteEvent } from 'flex-tools/events/liteEvent';
+import { Option, Command } from 'commander';
+import { PromptObject } from 'prompts';
+import * as flex_tools from 'flex-tools';
+
+type PromptType = "text" | "password" | "invisible" | "number" | "confirm" | "list" | "toggle" | "select" | "multiselect" | "autocomplete" | "date" | "autocompleteMultiselect";
+type PromptParam = 'auto' | boolean | PromptType | PromptObject;
+type InputPromptParam = PromptParam | ((value: any) => PromptParam) | boolean;
+type PromptParamDefaultValue = string | boolean | string[];
+interface PromptChoice {
+    title: string;
+    value?: any;
+    disabled?: boolean | undefined;
+    selected?: boolean | undefined;
+    description?: string | undefined;
+}
+interface IPromptableOptions {
+    required?: boolean;
+    optional?: boolean;
+    default?: PromptParamDefaultValue;
+    choices?: (PromptChoice | any)[];
+    prompt?: InputPromptParam;
+    validate?: (value: any) => boolean;
+}
+interface IPromptable {
+    name(): string;
+    description?: string;
+    flags: string;
+    promptChoices?: PromptChoice[];
+    argChoices?: string[];
+    variadic?: boolean;
+    defaultValue?: PromptParamDefaultValue;
+    input?: any;
+    required?: boolean;
+    validate?: (value: any) => boolean;
+    getPrompt(inputValue?: any): PromptObject | undefined;
+}
+/**
+ * 负责生成prompt对象
+ *
+ */
+declare class PromptManager {
+    args: InputPromptParam;
+    private _promptable;
+    constructor(promptable: IPromptable, promptArgs?: InputPromptParam);
+    /**
+     * 返回输入的是否是有效的prompt类型
+     * @param type
+     * @returns
+     */
+    isValid(type: any): boolean;
+    /**
+     * 推断是否需要提示
+     *
+     */
+    isNeed(input: any, defaultValue?: any): boolean;
+    /**
+     * 返回生成prompt对象
+     *
+     * @param inputValue   从命令行输入的值
+     */
+    get(inputValue?: any): PromptObject<string> | undefined;
+    /**
+     * 推断prompt类型
+     *
+     * @param inputValue   从命令行输入的值
+     */
+    infer(inputValue?: any): string;
+}
+
+interface MixedOptionParams extends IPromptableOptions {
+    hidden?: boolean;
+    defaultDescription?: string;
+    conflicts?: string | string[];
+    env?: string;
+    argParser?: <T>(value: string, previous: T) => T;
+    hideHelp?: boolean;
+    mandatory?: boolean;
+    implies?: {
+        [key: string]: any;
+    };
+}
+declare class MixOption extends Option implements IPromptable {
+    prompt?: PromptManager;
+    promptChoices?: PromptChoice[];
+    private _validate?;
+    constructor(flags: string, description?: string | undefined, optsOrDefault?: any);
+    validate(value: any): boolean;
+    choices(values: (PromptChoice | string)[]): void;
+    private resetChoices;
+    addChoice(value: PromptChoice | string): void;
+    removeChoice(value: any): void;
+    clearChoice(): void;
+    /**
+     * 返回选项的提示对象
+     *
+     * @remarks
+     *
+     *
+     *
+     * @param inputValue
+     * @returns
+     */
+    getPrompt(inputValue?: any): PromptObject | undefined;
+}
+
+type ICommandHookListener = ({ args, options, command, }: {
+    args: any[];
+    options: Record<string, any>;
+    command: MixCommand;
+}) => void | Promise<void>;
+type BeforeCommandHookListener = ({ args, options, command, }: {
+    args: any[];
+    options: Record<string, any>;
+    command: MixCommand;
+}) => void | Promise<void>;
+type AfterCommandHookListener = ({ value, args, options, command, }: {
+    value: any;
+    args: any[];
+    options: Record<string, any>;
+    command: MixCommand;
+}) => void | Promise<void>;
+interface ActionOptions {
+    id: string;
+    at: "replace" | "before" | "after" | "preappend" | "append" | number;
+    enhance: boolean;
+}
+interface ActionRegistry extends Omit<ActionOptions, "at"> {
+    fn: Function;
+}
+type OriginalAction = (...args: any[]) => void | Promise<void>;
+type EnhanceAction = ({ args, options, value, command, }: {
+    args: any[];
+    options: Record<string, any>;
+    value: any;
+    command: MixCommand;
+}) => void | Promise<any>;
+declare const BREAK: unique symbol;
+declare class MixCommand extends Command {
+    private _beforeHooks;
+    private _afterHooks;
+    private _customPrompts;
+    private _optionValues;
+    private _actions;
+    private _enable_prompts;
+    constructor(name?: string);
+    /**
+     * 是否是根命令
+     */
+    get isRoot(): boolean;
+    get actions(): ActionRegistry[];
+    get beforeHooks(): [BeforeCommandHookListener, boolean][];
+    get afterHooks(): [AfterCommandHookListener, boolean][];
+    get fullname(): string;
+    /**
+     * 返回根命令
+     */
+    root(): MixCommand;
+    action(fn: EnhanceAction, options: ActionOptions): this;
+    action(fn: OriginalAction): this;
+    /**
+     * 读取命令配置值，包括父命令提供的配置选项
+     * @param command
+     */
+    private getOptionValues;
+    /**
+     * 本函数在运行时子类进行action生成该命令的action
+     */
+    private getWrapperedAction;
+    /**
+     * 向上查找所有祖先命令
+     */
+    private getAncestorCommands;
+    /***
+     * 将所有actions包装成一个链式调用的函数
+     */
+    private wrapperChainActions;
+    /**
+     * 当传入--work-dirs时用来处理工作目录
+     */
+    private wrapperWorkDirsAction;
+    getOption(name: string): MixOption;
+    /**
+     * 添加一个Before钩子
+     * @param listener
+     * @param scope     =false时代表只在本命令执行，=true时代表在本命令及其子命令执行
+     * @returns
+     */
+    before(listener: BeforeCommandHookListener, scope?: boolean): this;
+    private executeBeforeHooks;
+    /**
+     * 添加一个After钩子
+     * @param listener
+     * @param scope     =false时代表只在本命令执行，=true时代表在本命令及其子命令执行
+     * @returns
+     */
+    after(listener: AfterCommandHookListener, scope?: boolean): this;
+    private executeAfterHooks;
+    private preActionHook;
+    private isEnablePrompts;
+    /**
+     * 生成选项自动提示
+     *
+     * @remarks
+     * FlexCli要求所有未提供默认值的Option自动生成提示
+     *
+     * - 未提供默认值，并且是必选的参数Option
+     * - 指定了choices但未提供有效值的Option
+     *
+     */
+    private generateAutoPrompts;
+    option(flags: string, description?: string | undefined, defaultValue?: any): this;
+    /**
+     * 添加提示
+     *
+     * @remarks
+     *
+     * 添加一些自定义提示
+     *
+     *
+     * @param questions
+     * @param show              是否显示提示信息，auto表示只有在用户没有提供option的值时才显示提示信息,always表示总是显示提示信息，never表示不显示提示信息
+     * @returns
+     */
+    prompt(questions: PromptObject | PromptObject[]): this;
+    /**
+     *
+     *  选择命令并执行
+     *
+     * @remorks
+     *
+     * 当命令具有多个子命令时，并且没有提供默认子命令时，提示用户选择一个子命令
+     *
+     */
+    selectCommands(): Promise<void>;
+    /**
+     * 禁用/启用所有提示
+     */
+    disablePrompts(): this;
+    enablePrompts(): this;
+}
+
+interface MixCliOptions {
+    name: string;
+    title?: string | (string | boolean | number)[];
+    description?: string;
+    version?: string;
+    logo?: string;
+    before?: (thisCommand: Command, actionCommand: Command) => void;
+    after?: (thisCommand: Command, actionCommand: Command) => void;
+    include?: string | RegExp | string[] | RegExp[];
+    exclude?: string | RegExp | string[] | RegExp[];
+    cliDir?: string;
+    context?: Record<string, any>;
+    prompt?: 'auto' | boolean;
+}
+type MixCliCommand = (cli: MixCli) => MixCommand | MixCommand[] | void;
+type MixCliEvents = "register";
+declare class MixCli extends LiteEvent<any, MixCliEvents> {
+    options: Required<MixCliOptions>;
+    root: Command;
+    private findSignals;
+    constructor(options?: MixCliOptions);
+    get context(): Record<string, any>;
+    get name(): string;
+    /**
+     * 是否禁用了所有的交互提示
+     */
+    get isDisabledPrompts(): any;
+    /**
+     * 扫描当前工程的依赖，加载匹配include的依赖下的命令
+     */
+    private installCommands;
+    /**
+     * 创建根命令
+     *
+     */
+    private createRootCommand;
+    /**
+     * 添加帮助选项
+     *
+     * @param text      帮助文本
+     * @param position  显示位置，可选值：before|after|beforeAll|afterAll
+     * @param fixIndent   是否自动修正缩进，如果为true，则会自动修正缩进，当显示多行时文本时，会自动修正缩进
+     *
+     */
+    addHelp(text: string, { pos, alignIndent }: {
+        pos: 'before' | 'after' | 'beforeAll' | 'afterAll';
+        alignIndent?: boolean | number;
+    }): void;
+    /**
+     * 注册一个命令
+     * @param cmd
+     */
+    register(cmd: MixCliCommand): void;
+    hasCommand(name: string): boolean;
+    /**
+     * 根据命令名称查找命令
+     *
+     * @remarks
+     *
+     * find("dev")
+     * find("dev.microservice")  支持多级命令
+     * find("abc",DevCommand)  允许指定从DevCommand下开始查找abc命令
+     *
+     * @param name
+     */
+    get(name: string): MixCommand | undefined;
+    /**
+     * 查找一个命令
+     *
+     * 如果命令不存在，则等待命令注册后再返回
+     *
+     * 在多包场景下，如果命令在其他包中注册并且该包中的命令还没注册，则会等待命令注册后再返回
+     *
+     * @param name
+     * @returns
+     */
+    find(name: string): Promise<MixCommand | undefined>;
+    /**
+     * 判断命令是否存在
+     *
+     * @param name
+     * @returns
+     */
+    exists(name: string): boolean;
+    /**
+     * 运行命令行程序
+     */
+    run(): void;
+    /**
+     * 创建一个命令
+     *
+     *
+     */
+    create(): void;
+}
+
+/**
+ *
+ * 在控制台输出一个字符串
+ * 本方法会将字符串中的每一行空格去掉
+ *
+ * @remarks
+ *
+ * outputStr(String.raw`
+ *     a
+ *       b`)
+ *
+ * 会输出
+ * a
+ *   b
+ *
+ * 此功能可以用于输出多行字符串时，保持代码的缩进格式，而不会影响输出结果
+ *
+ * @param str : 要输出的字符串
+ * @param vars : 用于替换字符串中的变量
+ *
+ */
+declare function outputStr(str: string, vars?: Record<string, any> | any[]): void;
+/**
+ * 修正多行字符串的缩进
+ *
+ * @param text
+ * @param indent
+ * @returns
+ */
+declare function fixIndent(text: string, indent?: boolean | number): string;
+/**
+ * 增加内置选项
+ * @param command
+ */
+declare function addBuiltInOptions(command: any): void;
+/**
+ * 是否命令行中包含了--debug-cli选项
+ */
+declare function isDebug(): boolean;
+declare function isEnablePrompts(): boolean;
+/**
+ * 打印调试信息
+ * @param message
+ * @param args
+ */
+declare function outputDebug(message: string, ...args: any[]): void;
+declare const fileExists: flex_tools.AsyncFunction;
+declare const readFile: flex_tools.AsyncFunction;
+declare const writeFile: flex_tools.AsyncFunction;
+declare const mkdir: flex_tools.AsyncFunction;
+/**
+ * 基于artTemplate模板生成文件
+ *
+ * @param {*} tmplFile
+ * @param {*} vars
+ */
+declare function createFileByTemplate(targetFile: string, tmplFile: string, vars?: Record<string, any>): Promise<string>;
+/**
+ * 创建目录
+ *
+ *
+ *
+ * @param {String[]} dirs 要创建的目录列表，类型为字符串数组
+ * @param callback      创建目录过程中的回调函数，类型为异步函数，接收一个参数 dir，表示当前正在创建的目录
+ * @returns 该函数返回一个 Promise 对象，表示创建目录的操作是否完成
+ */
+declare function mkDirs(dirs: string[], { callback, base }: {
+    callback?: Function;
+    base?: string;
+}): Promise<void>;
+
+export { ActionOptions, ActionRegistry, AfterCommandHookListener, BREAK, BeforeCommandHookListener, EnhanceAction, ICommandHookListener, MixCli, MixCliCommand, MixCliEvents, MixCliOptions, MixCommand, MixOption, MixedOptionParams, OriginalAction, addBuiltInOptions, createFileByTemplate, fileExists, fixIndent, isDebug, isEnablePrompts, mkDirs, mkdir, outputDebug, outputStr, readFile, writeFile };