mixcli 3.0.0 → 3.0.2

package/src/command.ts

@@ -0,0 +1,451 @@
+import { Command, Option } from "commander";
+import prompts, { PromptObject } from "prompts";
+import { MixOption, type MixedOptionParams } from "./option";
+import { addBuiltInOptions, isEnablePrompts, outputDebug } from "./utils";
+import path from "node:path";
+import fs from "node:fs";
+import type { AsyncFunction } from "flex-tools";
+
+export type ICommandHookListener = ({
+	args,
+	options,
+	command,
+}: {
+	args: any[];
+	options: Record<string, any>;
+	command: MixCommand;
+}) => void | Promise<void>;
+
+export type BeforeCommandHookListener = ({
+	args,
+	options,
+	command,
+}: {
+	args: any[];
+	options: Record<string, any>;
+	command: MixCommand;
+}) => void | Promise<void>;
+export type AfterCommandHookListener = ({
+	value,
+	args,
+	options,
+	command,
+}: {
+	value: any;
+	args: any[];
+	options: Record<string, any>;
+	command: MixCommand;
+}) => void | Promise<void>;
+
+export interface ActionOptions {
+	id: string;
+	at: "replace" | "before" | "after" | "preappend" | "append" | number;
+	// 函数签名类型，即采用原始的commander的action函数签名，还是mixcli的action函数签名
+	enhance: boolean;
+}
+
+export interface ActionRegistry extends Omit<ActionOptions, "at"> {
+	fn: Function;
+}
+
+// 原始的Action动作函数
+export type OriginalAction = (...args: any[]) => void | Promise<void>;
+// 增强的Action函数签名
+export type EnhanceAction = ({
+	args,
+	options,
+	value,
+	command,
+}: {
+	args: any[];
+	options: Record<string, any>;
+	value: any;
+	command: MixCommand;
+}) => void | Promise<any>;
+
+// 执行action的返回结果
+export const BREAK = Symbol("BREAK_ACTION"); // 中止后续的action执行
+
+export class MixCommand extends Command {
+	private _beforeHooks: [BeforeCommandHookListener, boolean][] = [];
+	private _afterHooks: [AfterCommandHookListener, boolean][] = [];
+	private _customPrompts: PromptObject[] = [];
+	private _optionValues: Record<string, any> = {}; // 命令行输入的选项值
+	private _actions: ActionRegistry[] = []; // 允许多个action
+	private _enable_prompts: boolean = true; // 是否启用交互提示
+	constructor(name?: string) {
+		super(name);
+		const self = this;
+		if (!this.isRoot) addBuiltInOptions(this);
+		this.hook("preAction", async function (this: any) {
+			self._optionValues = self.getOptionValues(this.hookedCommand);
+			try {
+				// @ts-ignore
+				await self.preActionHook.apply(self, arguments);
+			} catch {}
+		});
+	}
+	/**
+	 * 是否是根命令
+	 */
+	get isRoot() {
+		return !!!this.parent;
+	}
+	get actions() {
+		return this._actions;
+	}
+	get beforeHooks() {
+		return this._beforeHooks;
+	}
+	get afterHooks() {
+		return this._afterHooks;
+	}
+	get fullname() {
+		let names = [this.name()];
+		let parent = this.parent;
+		while (parent) {
+			if (parent.name() !== "root") {
+				names.unshift(parent.name());
+			}
+			parent = parent.parent;
+		}
+		return names.join(".");
+	}
+
+	/**
+	 * 返回根命令
+	 */
+	root() {
+		let root: MixCommand | null | undefined = this;
+		while (root && root.parent != null) {
+			root = root.parent as unknown as MixCommand;
+		}
+		return root;
+	}
+	action(fn: EnhanceAction, options: ActionOptions): this;
+	action(fn: OriginalAction): this;
+	action(fn: OriginalAction): this {
+		const actionFunc = arguments[0];
+		if (arguments.length == 1 && typeof actionFunc == "function") {
+			// 原始方式
+			this._actions.push({
+				id: Math.random().toString(36).substring(2),
+				enhance: false,
+				fn: actionFunc,
+			});
+		} else if (
+			arguments.length == 2 &&
+			typeof actionFunc == "function" &&
+			typeof arguments[1] == "object"
+		) {
+			// 增强模式
+			const actionFn = arguments[0];
+			const actionOpts: ActionOptions = Object.assign({ at: "append" }, arguments[1]);
+			if (actionOpts.at == "replace") this._actions = [];
+			const actionItem = {
+				id: actionOpts.id || Math.random().toString(36).substring(2),
+				enhance: actionOpts.enhance == undefined ? true : actionOpts.enhance,
+				fn: actionFn,
+			} as const;
+			if (typeof actionOpts.at == "number") {
+				this._actions.splice(Number(actionOpts.at), 0, actionItem);
+			} else if (["append", "before"].includes(actionOpts.at)) {
+				this._actions.push(actionItem);
+			} else if (["preappend", "after"].includes(actionOpts.at)) {
+				this._actions.splice(0, 0, actionItem);
+			} else {
+				this._actions.push(actionItem);
+			}
+		} else {
+			console.log("[mixcli] action params error");
+		}
+		return super.action(this.getWrapperedAction());
+	}
+
+	/**
+	 * 读取命令配置值，包括父命令提供的配置选项
+	 * @param command
+	 */
+	private getOptionValues(command: Command) {
+		let opts = {};
+		let parent: Command | null = command;
+		while (parent) {
+			Object.assign(opts, (parent as MixCommand)._optionValues);
+			parent = parent.parent;
+		}
+		return opts;
+	}
+	/**
+	 * 本函数在运行时子类进行action生成该命令的action
+	 */
+	private getWrapperedAction() {
+		return this.wrapperWorkDirsAction(this.wrapperChainActions());
+	}
+
+	/**
+	 * 向上查找所有祖先命令
+	 */
+	private getAncestorCommands(): MixCommand[] {
+		let cmds: MixCommand[] = [];
+		let cmd: MixCommand | null = this;
+		while (cmd) {
+			cmd = cmd.parent as MixCommand;
+			if (cmd) {
+				cmds.push(cmd);
+			}
+		}
+		return cmds;
+	}
+	/***
+	 * 将所有actions包装成一个链式调用的函数
+	 */
+	private wrapperChainActions() {
+		const self = this;
+		return async function (this: any) {
+			const args = Array.from(arguments); // 原始输入的参数
+			let preValue: any; // 保存上一个action的返回值
+			//解析参数, 0-1个参数为options,最后一个参数为command
+			let actionOpts: Record<string, any> = {},
+				actionArgs: any[] = [],
+				cmd: any;
+			if (args.length >= 2) {
+				cmd = args[args.length - 1]; // 最后一个command
+				actionOpts = args[args.length - 2];
+				actionArgs = args.slice(0, args.length - 2);
+			}
+			await self.executeBeforeHooks({ args: actionArgs, options: actionOpts, command: cmd });
+			try {
+				for (let action of self._actions) {
+					try {
+						if (action.enhance) {
+							// 增强模式
+							outputDebug("执行<{}>: args={}, options={}", () => [
+								self.name(),
+								actionArgs,
+								actionOpts,
+							]);
+							preValue = await action.fn.call(this, {
+								command: cmd,
+								value: preValue,
+								args: actionArgs,
+								options: actionOpts,
+							});
+						} else {
+							// 原始模式
+							preValue = await action.fn.apply(this, args);
+						}
+						if (preValue === BREAK) break;
+					} catch (e) {
+						outputDebug("命令{}的Action({})执行出错:{}", [self.name, action.id, e]);
+						throw e;
+					}
+				}
+			} finally {
+				await self.executeAfterHooks({
+					value: preValue,
+					args: actionArgs,
+					options: actionOpts,
+					command: cmd,
+				});
+			}
+		};
+	}
+	/**
+	 * 当传入--work-dirs时用来处理工作目录
+	 */
+	private wrapperWorkDirsAction(fn: AsyncFunction) {
+		const self = this;
+		return async function (this: any) {
+			let workDirs = self._optionValues.workDirs;
+			// 未指定工作目录参数
+			if (!workDirs) {
+				return await fn.apply(this, Array.from(arguments));
+			}
+			if (!Array.isArray(workDirs)) workDirs = workDirs.split(",");
+			workDirs = workDirs.reduce((dirs: any[], dir: string) => {
+				if (typeof dir == "string") dirs.push(...dir.split(","));
+				return dirs;
+			}, []);
+			for (let workDir of workDirs) {
+				const cwd = process.cwd();
+				try {
+					if (!path.isAbsolute(workDir)) workDir = path.join(cwd, workDir);
+					if (fs.existsSync(workDir) && fs.statSync(workDir).isDirectory()) {
+						outputDebug("切换到工作目录:{}", workDir);
+						process.chdir(workDir); // 切换
+						await fn.apply(this, Array.from(arguments));
+					} else {
+						outputDebug("无效的工作目录:{}", workDir);
+					}
+				} catch (e) {
+					throw e;
+				} finally {
+					process.chdir(cwd);
+				}
+			}
+		};
+	}
+	getOption(name: string): MixOption {
+		return this.options.find((option) => option.name() == name) as unknown as MixOption;
+	}
+	/**
+	 * 添加一个Before钩子
+	 * @param listener
+	 * @param scope     =false时代表只在本命令执行，=true时代表在本命令及其子命令执行
+	 * @returns
+	 */
+	before(listener: BeforeCommandHookListener, scope: boolean = true) {
+		this._beforeHooks.push([listener, scope]);
+		return this;
+	}
+	private async executeBeforeHooks(args: any) {
+		const hooks: [BeforeCommandHookListener, boolean, MixCommand][] = this.beforeHooks.map(
+			([hook, scope]) => [hook, scope, this]
+		);
+		this.getAncestorCommands().forEach((cmd: MixCommand) => {
+			hooks.unshift(
+				...cmd.beforeHooks.map(([hook, scope]) => {
+					return [hook, scope, cmd] as [BeforeCommandHookListener, boolean, MixCommand];
+				})
+			);
+		});
+		for (let [hook, scope, cmd] of hooks) {
+			if (!scope) continue;
+			await hook.call(cmd, args);
+		}
+	}
+	/**
+	 * 添加一个After钩子
+	 * @param listener
+	 * @param scope     =false时代表只在本命令执行，=true时代表在本命令及其子命令执行
+	 * @returns
+	 */
+	after(listener: AfterCommandHookListener, scope: boolean = true) {
+		this._afterHooks.push([listener, scope]);
+		return this;
+	}
+	private async executeAfterHooks(args: any) {
+		const hooks: [AfterCommandHookListener, boolean, MixCommand][] = this.afterHooks.map(
+			([hook, scope]) => [hook, scope, this]
+		);
+		this.getAncestorCommands().forEach((cmd: MixCommand) => {
+			hooks.push(
+				...cmd.afterHooks.map(([hook, scope]) => {
+					return [hook, scope, cmd] as [BeforeCommandHookListener, boolean, MixCommand];
+				})
+			);
+		});
+		for (let [hook, scope, cmd] of hooks) {
+			if (!scope) continue; //=false时不执行
+			await hook.call(cmd, args);
+		}
+	}
+	private async preActionHook(thisCommand: Command, actionCommand: Command) {
+		if (this.isEnablePrompts()) {
+			// 自动生成提示
+			const questions: PromptObject[] = [
+				...this.generateAutoPrompts(),
+				...this._customPrompts,
+			];
+			// 用户提示
+			if (questions.length > 0) {
+				const results = await prompts(questions);
+				Object.entries(results).forEach(([key, value]) => {
+					thisCommand.setOptionValue(key, value);
+				});
+			}
+		}
+	}
+
+	private isEnablePrompts() {
+		if (isEnablePrompts() === false) {
+			// 命令行参数禁用了提示，优先级最高
+			return false;
+		} else {
+			return this._enable_prompts;
+		}
+	}
+
+	/**
+	 * 生成选项自动提示
+	 *
+	 * @remarks
+	 * FlexCli要求所有未提供默认值的Option自动生成提示
+	 *
+	 * - 未提供默认值，并且是必选的参数Option
+	 * - 指定了choices但未提供有效值的Option
+	 *
+	 */
+	private generateAutoPrompts(): PromptObject[] {
+		const options = this.options as unknown as MixOption[];
+		const optionPromports = options
+			.filter((option) => !option.hidden && option instanceof MixOption)
+			.map((option) => option.getPrompt(this._optionValues[option.name()]))
+			.filter((prompt) => prompt) as PromptObject[];
+		outputDebug("命令<{}>自动生成{}个选项提示:{}", [
+			this.name(),
+			optionPromports.length,
+			optionPromports.map((prompt) => `${prompt.name}(${prompt.type})`).join(","),
+		]);
+		return optionPromports;
+	}
+	option(flags: string, description?: string | undefined, defaultValue?: any): this;
+	option(flags: string, description?: string | undefined, options?: MixedOptionParams): this {
+		// @ts-ignore
+		const option = new MixOption(...arguments);
+		if (option.required && !this.isEnablePrompts()) option.mandatory = true;
+		return this.addOption(option as unknown as Option);
+	}
+
+	/**
+	 * 添加提示
+	 *
+	 * @remarks
+	 *
+	 * 添加一些自定义提示
+	 *
+	 *
+	 * @param questions
+	 * @param show              是否显示提示信息，auto表示只有在用户没有提供option的值时才显示提示信息,always表示总是显示提示信息，never表示不显示提示信息
+	 * @returns
+	 */
+	prompt(questions: PromptObject | PromptObject[]) {
+		this._customPrompts.push(...(Array.isArray(questions) ? questions : [questions]));
+		return this;
+	}
+	/**
+	 *
+	 *  选择命令并执行
+	 *
+	 * @remorks
+	 *
+	 * 当命令具有多个子命令时，并且没有提供默认子命令时，提示用户选择一个子命令
+	 *
+	 */
+	async selectCommands() {
+		const choices = this.commands.map((command) => ({
+			title: `${command.description()}(${command.name()})`,
+			value: command.name(),
+		}));
+		const result = await prompts({
+			type: "select",
+			name: "command",
+			message: "请选择命令:",
+			choices,
+		});
+		// 重新解析命令行参数标志,
+		const command = this.commands.find((command) => command.name() === result.command);
+		await command?.parseAsync([result.command], { from: "user" });
+	}
+	/**
+	 * 禁用/启用所有提示
+	 */
+	disablePrompts() {
+		this._enable_prompts = false;
+		return this;
+	}
+	enablePrompts() {
+		this._enable_prompts = true;
+		return this;
+	}
+}

package/src/finder.ts

@@ -0,0 +1,142 @@
+import { getPackageRootPath } from 'flex-tools';
+import type { MixCli } from './cli';
+import {  globSync } from 'glob'
+import { MixCliCommand } from './cli';
+import { isDebug, outputDebug } from './utils';
+import fs from "node:fs"
+import path from "node:path"
+import { getPackageJson } from  "flex-tools/package/getPackageJson"
+
+/**
+ * 
+ * 在当前工程中查找符合FlexCli.prefix约定的命令 
+ *  
+ * - 读取当前包的package.json
+ * - 找出所有以cli.prefix开头的依赖
+ * - 加载这些依赖的目录下的匹配cli.pattern的命令
+ * - 加载加载这样命令
+ * 
+ */
+ 
+
+export function getMatchedDependencies(this:MixCli,entry:string):string[]{
+    const pacakgeMacher = this.options.include
+    if(!(pacakgeMacher instanceof RegExp)) return  []
+    
+    // 找出当前包的所有依赖
+    const { dependencies={},devDependencies={},peerDependencies={},optionalDependencies={},bundleDependencies={} } = getPackageJson(entry)
+    const packageNames = [
+        ...Object.keys(dependencies),
+        ...Object.keys(devDependencies),
+        ...Object.keys(peerDependencies),
+        ...Object.keys(optionalDependencies),
+        ...Object.keys(bundleDependencies)
+    ]
+    return packageNames.filter(name=>name!=="@voerka/cli" && pacakgeMacher.test(name))
+}
+
+function isMatched(str:string,reg?:string | RegExp | string[] | RegExp[]):boolean{
+    // let regexps:RegExp[]=[]
+    const regexps = reg ? (Array.isArray(reg) ? reg : [reg]) : []
+    return regexps.some(regexp=>{
+        if(typeof regexp === "string"){
+            return (new RegExp(regexp)).test(str)
+        }else if(regexp instanceof RegExp){
+            return regexp.test(str)
+        }else{
+            return false
+        }
+    })
+}
+
+export function findCliPaths(this:MixCli,packageName?:string ,entry?:string):string[]{
+    const includeMacher = this.options.include
+    const excludeMacher = this.options.exclude
+    if(!includeMacher) return []
+    const packageRoot = getPackageRootPath(entry || process.cwd())
+    const packagePath = packageName ? path.dirname(require.resolve(packageName,{paths:[packageRoot as string]})) : packageName!
+
+    // 找出当前包的所有依赖
+    const packageNames = getMatchedDependencies.call(this,packagePath)
+
+    const cliDirs:string[]=[]
+    
+    if(entry!==undefined) cliDirs.push(path.join(packagePath,this.options.cliDir))
+    packageNames.filter(name=>{
+            return  isMatched(name,includeMacher) && !isMatched(name,excludeMacher) 
+        })
+        .forEach(name=>{
+            outputDebug("匹配包:{}",`${packageName ? name+" <- "+packageName  : name}`)
+            try{
+                const packageEntry = path.dirname(require.resolve(name,{paths:packagePath ? [packagePath] : [process.cwd()]}))
+                const packageCliDir =path.join(packageEntry,this.options.cliDir!)                
+                // 查找当前包的所属工程的依赖
+                let dependencies = getMatchedDependencies.call(this,packageEntry)
+                cliDirs.push(...dependencies.reduce<string[]>((result,dependencie)=>{
+                    outputDebug("匹配包:{}",`${dependencie} <- ${name}`)
+                    result.push(...findCliPaths.call(this,dependencie,packageEntry))
+                    return result
+                },[])) 
+                if(fs.existsSync(packageCliDir)){
+                    cliDirs.push(packageCliDir)
+                }
+            }catch(e:any){
+                outputDebug("解析包<{}>路径出错：{}",[name,e.stack])
+            }    
+        })
+    // 由于一些包可能存在循环依赖，所以需要去重
+    return [...new Set(cliDirs)]
+}
+
+
+function showError(e:any){
+    if(isDebug()){
+        outputDebug("导入命令<>出错:{}",e.stack)
+    }else{
+        console.error(e)
+    }  
+
+}
+
+/**
+ * 
+ *  扫描当前工程中所有符合条件的命令
+ * 
+ * @param cli 
+ * 
+ */
+export async function findCommands(cli:MixCli){ 
+    const cliDirs =  findCliPaths.call(cli)
+    const commands:MixCliCommand[] = []
+    const files = [] as string[]
+    cliDirs.forEach(dir=>{
+        files.push(...globSync("*",{
+            cwd:dir,
+            absolute :true 
+        }).filter((file:string)=>(file.endsWith(".js") || file.endsWith(".cjs") || file.endsWith(".mjs")) && !fs.statSync(file).isDirectory()))
+    })
+    for(let file of files){    
+        try{
+            outputDebug("导入命令:{}",file)
+            if(file.endsWith(".cjs") || file.endsWith(".js")){
+                commands.push(require(file))
+            }else if(file.endsWith(".mjs")){
+                const cmd = await import(`file://${file}`)
+                commands.push(cmd.default)
+            }            
+        }catch(e:any){
+            if(e.code==="ERR_REQUIRE_ESM"){                                
+                try{
+                    const cmd = await import(`file://${file.replace(".js",".mjs")}`)
+                    commands.push(cmd.default)
+                }catch(err){
+                    showError(err)
+                }
+            }else{
+                showError(e) 
+            }
+        }
+    }
+    return commands
+}
+

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./cli"
+export * from "./utils"
+export * from "./command"
+export * from "./option"

package/src/option.ts

@@ -0,0 +1,102 @@
+import { Option } from 'commander'
+import { PromptObject } from 'prompts'
+import { IPromptable, IPromptableOptions, PromptChoice, PromptManager } from './prompt'
+
+
+export 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}  
+}
+
+
+export class MixOption extends Option implements IPromptable{
+    // 是否提示用户输入
+    prompt?: PromptManager     
+    promptChoices?:PromptChoice[]
+    private _validate?: (value: any) => boolean       
+    constructor(flags: string, description?: string | undefined,optsOrDefault?:any) {
+        super(flags, description)
+        let params:MixedOptionParams = {}
+        if(arguments.length==3 && typeof arguments[2] == "object"){
+            params = Object.assign({ },arguments[2])  
+        }else if(arguments.length==3){
+            params.default = arguments[2]
+        }
+        if(params.prompt===undefined) params.prompt = 'auto'
+        if(params.default) this.default(params.default,params.defaultDescription)
+        if(params.choices) this.choices(params.choices)
+        if(params.conflicts) this.conflicts(params.conflicts)
+        if(params.env) this.env(params.env)
+        if(params.argParser) this.argParser(params.argParser)
+        if(params.hideHelp) this.hideHelp(params.hideHelp)
+        if(params.hidden) this.hidden = params.hidden
+        if(params.mandatory) this.makeOptionMandatory(params.mandatory)
+        if(params.implies) this.implies(params.implies) 
+        if(params.optional) this.optional=params.optional
+        if(typeof(params.validate)=='function') this._validate = params.validate.bind(this)
+        if(params.required) {
+            this.required = params.required
+            if(!this._validate ) this._validate  = (value:any)=>String(value).length>0
+        }
+        this.prompt = new PromptManager(this as IPromptable,params.prompt)
+    } 
+    validate(value: any): boolean {
+        if(typeof(this._validate)=='function'){
+            return this._validate(value)
+        }else{
+            return true
+        }
+    }
+    // @ts-ignore
+    choices(values:(PromptChoice | string)[]){
+        if(!this.promptChoices){
+            this.promptChoices = values.map(choice=>{
+                if(typeof(choice)=='object'){
+                    return choice
+                }else{
+                    return {title:choice,value:choice}                    
+                }
+            })
+        }        
+        super.choices(this.promptChoices.map((item:any)=>item.value))    
+    }    
+
+    private resetChoices(){
+        super.choices(this.promptChoices!.map((item:any)=>item.value))    
+    }
+
+    addChoice(value:PromptChoice | string){
+        if(!this.promptChoices || !Array.isArray(this.promptChoices)) this.promptChoices = []
+        this.promptChoices!.push(typeof(value)=='string' ? {title:value,value} : value)
+        this.resetChoices()
+    }
+    removeChoice(value:any){
+        this.promptChoices =this.promptChoices?.filter(choice=>choice.value!==value)
+        this.resetChoices()
+    }
+    clearChoice(){
+        this.promptChoices = []
+        this.resetChoices()
+    }
+
+        
+    /**
+     * 返回选项的提示对象
+     * 
+     * @remarks
+     * 
+     *
+     * 
+     * @param inputValue 
+     * @returns 
+     */
+    getPrompt(inputValue?:any): PromptObject | undefined {
+        return this.prompt?.get(inputValue)
+    } 
+}