feat: first impl

.eslintrc

@@ -3,17 +3,5 @@
   "parserOptions": {
     "project": "./tsconfig.json",
     "createDefaultProgram": true
-  },
-  "rules": {
-    "prefer-spread": "off",
-    "no-return-assign": "off",
-    "no-case-declarations": "off",
-    "prefer-const": "off",
-    "no-regex-spaces": "off",
-    "no-return-await": "off",
-    "@typescript-eslint/no-unused-vars": "off",
-    "@typescript-eslint/no-use-before-define": "off",
-    "@typescript-eslint/no-empty-function": "off",
-    "@typescript-eslint/no-var-requires": "off"
   }
 }

.github/workflows/release.yml

@@ -0,0 +1,19 @@
+name: Release
+on:
+  # 合并后自动发布
+  # push:
+  #   branches: [ master, main, next, beta, '*.x' ]
+
+  # 手动发布
+  workflow_dispatch: {}
+
+jobs:
+  release:
+    name: Node.js
+    uses: artusjs/github-actions/.github/workflows/node-release.yml@v1
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      GIT_TOKEN: ${{ secrets.GIT_TOKEN }}
+    # with:
+      # checkTest: false
+      # dryRun: true

.npmrc

@@ -0,0 +1 @@
+package-lock=false

README.md

@@ -1,40 +1,36 @@
-# artus-cli/template
+# @artus-cli/plugin-help
 
-template repository for artus-cli
+Built-in plugin for showing help information in artus-cli
 
-<!-- Badge，自行替换掉下面的 `artus-cli/artus-cli` 占位符-->
+[![NPM version](https://img.shields.io/npm/v/@artus-cli/plugin-help.svg?style=flat-square)](https://npmjs.org/package/@artus-cli/plugin-help)
+[![NPM quality](https://img.shields.io/npms-io/final-score/@artus-cli/plugin-help.svg?style=flat-square)](https://npmjs.org/package/@artus-cli/plugin-help)
+[![NPM download](https://img.shields.io/npm/dm/@artus-cli/plugin-help.svg?style=flat-square)](https://npmjs.org/package/@artus-cli/plugin-help)
+[![Continuous Integration](https://github.com/artus-cli/plugin-help/actions/workflows/ci.yml/badge.svg)](https://github.com/artus-cli/plugin-help/actions/workflows/ci.yml)
+[![Test coverage](https://img.shields.io/codecov/c/github/artus-cli/plugin-help.svg?style=flat-square)](https://codecov.io/gh/artus-cli/plugin-help)
+[![Oss Insight Analytics](https://img.shields.io/badge/OssInsight-artus--cli%2Fartus--cli-blue.svg?style=flat-square)](https://ossinsight.io/analyze/artus-cli/plugin-help)
 
-[![NPM version](https://img.shields.io/npm/v/@artus-cli/artus-cli.svg?style=flat-square)](https://npmjs.org/package/@artus-cli/artus-cli)
-[![NPM quality](https://img.shields.io/npms-io/final-score/@artus-cli/artus-cli.svg?style=flat-square)](https://npmjs.org/package/@artus-cli/artus-cli)
-[![NPM download](https://img.shields.io/npm/dm/@artus-cli/artus-cli.svg?style=flat-square)](https://npmjs.org/package/@artus-cli/artus-cli)
-[![Continuous Integration](https://github.com/artus-cli/artus-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/artus-cli/artus-cli/actions/workflows/ci.yml)
-[![Test coverage](https://img.shields.io/codecov/c/github/artus-cli/artus-cli.svg?style=flat-square)](https://codecov.io/gh/artus-cli/artus-cli)
-[![Oss Insight Analytics](https://img.shields.io/badge/OssInsight-artus--cli%2Fartus--cli-blue.svg?style=flat-square)](https://ossinsight.io/analyze/artus-cli/artus-cli)
-
-
-## Usage
+## Install
 
 ```sh
-# print help
-$ my-bin --help
-
-# run dev
-$ my-bin dev --port=8080
+$ npm i @artus-cli/plugin-help
 ```
 
-## Commands
-
-### dev
-
+## Usage
 
-### debug
+```ts
+// plugin.ts
 
+export default {
+  help: {
+    enable: true,
+    package: '@artus-cli/plugin-help',
+  },
+};
+```
 
 ## Contributing
 
 ```sh
 $ npm test
 $ npm run cov
-
-$ npx ts-node src/bin/cli.ts dev --port=8080
 ```

package.json

@@ -1,7 +1,7 @@
 {
-  "name": "@artus-cli/template",
-  "version": "0.0.0",
-  "description": "artus-cli template",
+  "name": "@artus-cli/plugin-help",
+  "version": "0.0.1-beta.1",
+  "description": "show help information for @artus-cli",
   "homepage": "",
   "author": "",
   "main": "dist/index.js",
@@ -25,7 +25,7 @@
     "prepack": "npm run tsc"
   },
   "dependencies": {
-    "@artus-cli/artus-cli": "beta"
+    "tslib": "^2.4.0"
   },
   "devDependencies": {
     "@artus/eslint-config-artus": "^0.0.1",
@@ -38,13 +38,13 @@
     "mocha": "^10.0.0",
     "ts-mocha": "^10.0.0",
     "ts-node": "^10.9.1",
+    "@artus-cli/artus-cli": "latest",
     "tsconfig-paths": "^4.1.1",
-    "tslib": "^2.4.0",
     "typescript": "^4.8.2"
   },
   "repository": {
     "type": "git",
-    "url": ""
+    "url": "https://github.com/artus-cli/plugin-help"
   },
   "files": [
     "dist"
@@ -55,6 +55,7 @@
   "keywords": [
     "artus",
     "artus-cli",
+    "artus-cli-plugin",
     "command-line-app",
     "cli",
     "commander"

src/help.ts

@@ -0,0 +1,79 @@
+import { Option, DefineCommand, Command, DefineOption, Inject, CommandContext, Program } from '@artus-cli/artus-cli';
+import commandLineUsage from 'command-line-usage';
+
+interface HelpOption extends Option {
+  command: string;
+}
+
+@DefineCommand({
+  command: 'help [command]',
+  description: 'show help infomation for command',
+  alias: 'h',
+})
+export class HelpCommand extends Command {
+  @Inject()
+  ctx: CommandContext;
+
+  @Inject()
+  program: Program;
+
+  @DefineOption()
+  option: HelpOption;
+
+  async run() {
+    const ctx = this.ctx;
+    const { binName: bin } = this.program;
+    const command = this.option.command || bin;
+    const commandUid = command.startsWith(bin) ? command : `${bin} ${command}`;
+    const helpCommand = ctx.commands.get(commandUid) || ctx.rootCommand;
+
+    // display help informations
+    const displayTexts: string[] = [];
+    const commandLineUsageList: any[] = [];
+    const optionKeys = helpCommand.options ? Object.keys(helpCommand.options) : [];
+
+    // usage info in first line
+    displayTexts.push(`Usage: ${helpCommand.command.startsWith(bin) ? '' : `${bin} `}${helpCommand.command}`);
+    if (helpCommand.description) {
+      displayTexts.push('', helpCommand.description);
+    }
+
+    // available commands, display all subcommands if match the root command
+    const availableCommands = (
+      helpCommand.isRoot
+        ? Array.from(new Set(ctx.commands.values()))
+        : [ helpCommand ].concat(helpCommand.childs || [])
+    ).filter(c => !c.isRoot && c.isRunable);
+
+    if (availableCommands.length) {
+      commandLineUsageList.push({
+        header: 'Available Commands',
+        content: availableCommands.map(command => ({
+          name: command.command,
+          summary: command.description,
+        })),
+      });
+    }
+
+    // options list, like -h, --help / -v, --version ...
+    commandLineUsageList.push({
+      header: 'Options',
+      optionList: optionKeys
+        .map(flag => {
+          const option = helpCommand.options[flag];
+          const showFlag = flag[0].toLowerCase() + flag.substring(1).replace(/[A-Z]/g, '-$&').toLowerCase();
+          return {
+            name: showFlag,
+            type: { name: option.type },
+            description: option.description,
+            alias: option.alias,
+            defaultValue: option.default,
+          };
+        }),
+    });
+
+    // use command-line-usage to format help informations.
+    displayTexts.push(commandLineUsage(commandLineUsageList));
+    console.info(displayTexts.join('\n'));
+  }
+}

src/index.ts

@@ -1,2 +1 @@
-export * from './cmd/dev';
-export * from './cmd/debug';
+export * from './help';

src/lifecycle.ts

@@ -0,0 +1,37 @@
+import { Inject, ApplicationLifecycle, LifecycleHook, LifecycleHookUnit, Program, CommandContext, Utils } from '@artus-cli/artus-cli';
+
+@LifecycleHookUnit()
+export default class UsageLifecycle implements ApplicationLifecycle {
+  @Inject()
+  private readonly program: Program;
+
+  @LifecycleHook()
+  async configDidLoad() {
+    // add global options
+    this.program.option({
+      help: {
+        type: 'boolean',
+        description: 'Show Help',
+        alias: 'h',
+      },
+    });
+
+    this.program.use(async (ctx: CommandContext, next) => {
+      const { binName: bin } = this.program;
+      const { fuzzyMatched, matched, args, raw } = ctx;
+      if (!fuzzyMatched || !args.help) {
+        if (!matched) {
+          // can not match any command
+          console.error(`\n Command not found: '${bin} ${raw.join(' ')}', try '${fuzzyMatched?.cmds.join(' ') || bin} --help' for more information.\n`);
+          process.exit(1);
+        }
+
+        return next();
+      }
+
+      // redirect to help command
+      const utils = ctx.container.get(Utils);
+      await utils.redirect([ 'help', fuzzyMatched.uid ]);
+    });
+  }
+}

src/meta.json

@@ -0,0 +1,3 @@
+{
+  "name": "help"
+}

src/bin/cli.ts → test/fixtures/my-bin/bin/cli.ts

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
 
 import { start } from '@artus-cli/artus-cli';
-
 start();

test/fixtures/my-bin/cmd/cov.ts

@@ -0,0 +1,24 @@
+import { DefineCommand, DefineOption } from '@artus-cli/artus-cli';
+import { TestCommand, TestOption } from './test';
+
+interface CovOption extends TestOption {
+  c8?: boolean;
+}
+
+@DefineCommand({
+  command: 'cov <baseDir> [file...]',
+  description: 'Run the coverage',
+})
+export class CovCommand extends TestCommand {
+  @DefineOption<CovOption>({
+    c8: {
+      type: 'boolean',
+      default: true,
+    },
+  })
+  args: CovOption;
+
+  async run() {
+    // nothing
+  }
+}