@oishi/cli-core

说明

这是一个整合了 commander 和 inquirer，用作创建脚本的底层框架。

使用该框架创建的命令行工具，一份配置通行交互式命令行和命令式命令行。

API

CliCore

框架的核心壳，用来创建声明初始命令行。

如下，创建一个空壳子，框架会自动注入 help 和 version 等指令。

1import { CliCore } from "@oishi/cli-core";
2
3const cli = new CliCore({
4  name: "cli",
5  description: "常用命令行合集",
6  version: "0.0.1",
7  commands: [],
8});
9
10cli.execute();

使用，cli -h 和 cli --version 查看信息。

1# 查看帮助
2$ cli -h
3
4Usage: cli [options]
5
6常用命令行合集
7
8Options:
9  -V, --version      output the version number
10  -i, --interactive  交互式命令行 (default: false)
11  -h, --help         display help for command

interactive

框架会自动注入 interactive 选项，当运行 cli -i 时，框架将会自动生成交互式命令行。

CliCommand

子命令对象，用来创建命令行的子命令集。

如下，创建一个最简单的命令行，我们希望程序给我们打个招呼，使用 cli say xxx 调用。

1import { CliCommand } from "@oishi/cli-core";
2
3interface IArgs {
4  name: string;
5}
6
7interface IOpts {}
8
9const say = new CliCommand<IArgs, IOpts>({
10  command: "say",
11  description: "say hello",
12  arguments: {
13    name: { description: "请输入您的名称" },
14  },
15  options: {},
16  action({ data, logger, helper }) {
17    logger.info(`hello ${data.name}`);
18  },
19});

创建完 CliCommand 之后，加入到 CliCore 的 commands 中即可。

1import { CliCore } from "@oishi/cli-core";
2
3const cli = new CliCore({
4  name: "cli",
5  description: "常用命令行合集",
6  version: "0.0.1",
7  commands: [say],
8});
9
10cli.execute();

如下调用，命令行将会输入对应信息。

1# 执行指令
2$ cli say jsjzh
320XX-XX-XXTXX:XX:XX.XXXZ [cli] info: hello jsjzh

command

required

子命令的名称，必传，接受字符串，比如传入了 say，则可以使用 cli say 调用。

description

required

子命令的描述，必传，接受字符串，传入的讯息将在 cli say -h 时显示。

arguments

optional

1interface IArguments {
2  description: string;
3  default?: any | [any, string];
4  choices?: string[];
5  optional?: boolean;
6  multiple?: boolean;
7}

子命令的参数，这个和下面的 options 有些不同，该处参数一般为必填，且不用带前缀说明。

例子如下。

1...
2arguments: {
3  name: { description: "请输入您的名称" }
4}
5...

如下，只需要直接输入 xxx 即可。

1$ cli say xxx

options

optional

1interface IOptions {
2  description: string;
3  default?: any | [any, string];
4  alias?: string;
5  choices?: string[];
6  optional?: boolean;
7  multiple?: boolean;
8}

子命令的参数，需要携带前缀说明。

如果同上面的 arguments 的例子一样，options 也想要一个 name 的参数，该如何写呢？

例子如下。

1...
2options: {
3  name: { description: "请输入您的名称" }
4}
5...

如下，需要增加前缀 --name 才行。

1$ cli say --name xxx

commands

optional

子命令的命令集，CliCommand 支持嵌套方式，且命令行的命中模式为优先匹配命令集，直接说有些难理解，请看如下的例子。

1const child = new CliCommand({
2  command: "child",
3  description: "child",
4  action({ data, logger, helper }) {
5    logger.info(`child`);
6  },
7});
8
9const parent = new CliCommand({
10  command: "parent",
11  commands: [child],
12  description: "parent",
13  arguments: {
14    name: { description: "请输入您的名称" },
15  },
16  options: {},
17  action({ data, logger, helper }) {
18    logger.info(`hello ${data.name}`);
19  },
20});

如上，在 parent 接收一个 arguments 时，parent 还有一个 commands，那程序如果运行 cli parent child，程序将如何匹配？

答案是优先匹配子命令集，将 cli parent child 传入的 child 当做是子命令集的触发，也就是会输出 child。

所以，即使 parent 的参数中有 arguments，但如果传入的 arguments 和其子命令集的 command 重复，将会命中子命令集的任务。

Arguments

arguments 的对象描述如下

1interface IArguments {
2  description: string;
3  default?: any | [any, string];
4  choices?: string[];
5  optional?: boolean;
6  multiple?: boolean;
7}

• default 表示默认值，当没有传入值时，框架会传入默认值。
• choices 表示可以输入的值，交互式的呈现是 list or checkbox(若开启 multiple) 选择，命令式的呈现是对输入进行验证。
• optional 表示该参数是否可选，默认参数都为必选。若配置为 true，则交互式会跳过生成该条交互命令。
• multiple 与 choices 配合使用，表示多选，输入的值会以数组的形式传入。

Options

1interface IOptions {
2  description: string;
3  default?: any | [any, string];
4  alias?: string;
5  choices?: string[];
6  optional?: boolean;
7  multiple?: boolean;
8}

• alias 表示短缀，如 --build 设置 alias 为 b，则可使用 -b 调用。
• default 表示默认值，当没有传入值时，框架会传入默认值。
• choices 表示可以输入的值，交互式的呈现是 list or checkbox(若开启 multiple) 选择，命令式的呈现是对输入进行验证。
• optional 表示该参数是否可选，默认参数都为必选。若配置为 true，则交互式会跳过生成该条交互命令。
• multiple 与 choices 配合使用，表示多选，输入的值会以数组的形式传入。

Logger

如下为日志的严重程度，error 为 0，是最大 P0 级错误日志。

1enum levels {
2  error = 0,
3  warn = 1,
4  info = 2,
5  http = 3,
6  verbose = 4,
7  debug = 5,
8  silly = 6,
9}

CliCommand 的 action 中接收一个 logger 方法，该方法是包装的 winston，该日志工具会以天为维度，记录 warn 和 error 等级的内容到 ~/logs/oishi/${cli} 中，文件最大为 20mb，会以滑动窗口的方式滚动记录最近 14 天的日志。

1...
2action({ data, logger, helper }) {
3  logger.warn(`hello ${data.name}`);
4}
5...

Helper

框架提供了几个常用的工具。

runPrompt

创建交互式命令行。

1const prompt = helper.runPrompt();
2
3prompt.addInput({ name: "name", message: "请输入你的名字" });
4
5prompt.execute((answers) => {
6  console.log(answers);
7});

runCron

创建定时任务。

1helper.runCron({
2  cronTime: "* * * * * *",
3  onTick() {
4    console.log("hello wrold");
5  },
6});

runCmd

创建命令行运行工具。

1const run = helper.runCmd();
2
3run("echo hello world");

runTask

创建任务链，方便管理任务顺序。

1await helper
2  .runTask({ hasTip: true })
3  .add({
4    title: "切换 registry 至 npm 源",
5    async task() {
6      run("npm set registry=https://registry.npmjs.org/");
7    },
8  })
9  .add({
10    title: "执行项目构建和发布",
11    async task() {
12      run("npm run build");
13      run("npm publish");
14    },
15  })
16  .add({
17    title: "切换 registry 至国内镜像",
18    async task() {
19      run("npm set registry=https://registry.npmmirror.com/");
20    },
21  })
22  .run();

待办

• choices 和 default 允许传入 name value 的方式
• 类型转换有问题，因为命令行解析的结果都是字符串，无法通过 ts 传入值来修改获取值
• 后续 logger 可能可以支持自定义 winston transports
• 添加更多的 inquirer 的输入类型支持
• 命令运行时互相调用