feat($core): registerCommand Plugin Option API (#1069)

Author: ulivz

package.json

@@ -12,6 +12,7 @@
     "boot": "node scripts/bootstrap.js",
     "dev": "yarn workspace docs dev",
     "build": "yarn workspace docs build",
+    "show-help": "yarn workspace docs show-help",
     "dev:blog": "yarn workspace blog dev",
     "build:blog": "yarn workspace blog build",
     "register-vuepress": "lerna exec --scope vuepress -- yarn link",

packages/@vuepress/cli/.npmignore

@@ -19,7 +19,8 @@ const PLUGIN_OPTION_META_MAP = {
   ADDITIONAL_PAGES: { name: 'additionalPages', types: [Function, Array] },
   GLOBAL_UI_COMPONENTS: { name: 'globalUIComponents', types: [String, Array] },
   DEFINE: { name: 'define', types: [Function, Object] },
-  ALIAS: { name: 'alias', types: [Function, Object] }
+  ALIAS: { name: 'alias', types: [Function, Object] },
+  EXTEND_CLI: { name: 'extendCli', types: [Function] }
 }
 
 const PLUGIN_OPTION_MAP = {}

packages/@vuepress/cli/README.md

@@ -206,7 +206,8 @@ module.exports = class PluginAPI {
     additionalPages,
     globalUIComponents,
     define,
-    alias
+    alias,
+    extendCli
   }) {
     const isInternalPlugin = pluginName.startsWith('@vuepress/internal-')
     logger[isInternalPlugin ? 'debug' : 'tip'](pluginLog(pluginName, shortcut))
@@ -229,6 +230,7 @@ module.exports = class PluginAPI {
       .registerOption(PLUGIN_OPTION_MAP.GLOBAL_UI_COMPONENTS.key, globalUIComponents, pluginName)
       .registerOption(PLUGIN_OPTION_MAP.DEFINE.key, define, pluginName)
       .registerOption(PLUGIN_OPTION_MAP.ALIAS.key, alias, pluginName)
+      .registerOption(PLUGIN_OPTION_MAP.EXTEND_CLI.key, extendCli, pluginName)
   }
 }
 

packages/@vuepress/cli/index.js

@@ -43,6 +43,7 @@ module.exports = class AppContext {
    */
 
   constructor (sourceDir, cliOptions = {}, isProd) {
+    logger.debug('sourceDir', sourceDir)
     this.sourceDir = sourceDir
     this.cliOptions = cliOptions
     this.isProd = isProd

packages/@vuepress/cli/package.json

@@ -68,10 +68,12 @@
     "webpack-chain": "^4.6.0",
     "webpack-merge": "^4.1.2",
     "webpack-serve": "^1.0.2",
-    "webpackbar": "^2.6.1"
+    "webpackbar": "^2.6.1",
+    "semver": "^5.5.0",
+    "cac": "^6.3.9"
   },
   "engines": {
-    "node": ">=8"
+    "node": ">=8.6"
   },
   "browserslist": [
     ">1%"

packages/@vuepress/core/lib/plugin-api/constants.js

@@ -187,9 +187,8 @@ Then the final route of i18n UI is `/i18n/`.
 
 ## Others
 
-With the goal of decoupling, we were able to separate VuePress into the following libraries by introducing monorepo:
+With the goal of decoupling, we were able to separate VuePress into the following two libraries by introducing monorepo:
 
-- [@vuepress/cli](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/cli): Management of command line;
 - [@vuepress/core](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/core)：Including the core implementation of `dev`, `build` and `Plugin API`;
 - [@vuepress/theme-default](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/theme-default)：The default theme you see now.
 

packages/@vuepress/core/lib/plugin-api/index.js

@@ -434,3 +434,29 @@ Then, VuePress will automatically inject these components behind the layout comp
 </div>
 </div>
 ```
+
+## registerCommand
+
+- Type: `function`
+- Default: `undefined`
+
+Register a extra command to enhance the CLI of vuepress. The function will be called with a [CAC](https://github.com/cacjs/cac)'s instance as the first argument.
+
+```js
+module.exports = {
+  registerCommand (cli) {
+    cli
+      .command('info [targetDir]', '')
+      .option('--debug', 'display info in debug mode')
+      .action((dir = '.') => {
+        console.log('Display info of your website')
+      })
+  }
+}
+```
+
+Now you can use `vuepress info [targetDir]` a in your project!
+
+::: tip
+Note that a custom command registered by a plugin requires VuePress to locate your site configuration like `vuepress dev` and `vuepress build`, so when developing a command, be sure to lead the user to pass `targetDir` as an CLI argument.
+:::

packages/@vuepress/core/lib/prepare/AppContext.js

@@ -187,9 +187,8 @@ i18n UI 最终的路由将是 `/i18n/`.
 
 ## 其他
 
-本着解耦的目标，引入 monorepo 后，我们也得以将 VuePress 分离成以下几个库：
+本着解耦的目标，引入 monorepo 后，我们也得以将 VuePress 分离成以下两个库：
 
-- [@vuepress/cli](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/cli): 命令行指令的管理；
 - [@vuepress/core](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/core)：包含 dev、build 的核心实现和 Plugin API；
 - [@vuepress/theme-default](https://github.com/vuejs/vuepress/tree/master/packages/@vuepress/theme-default)：你现在所看到的默认主题。
 

packages/@vuepress/core/package.json

@@ -436,3 +436,30 @@ VuePress 将会自动将这些组件注入到布局组件的隔壁：
 </div>
 </div>
 ```
+
+## registerCommand
+
+- 类型: `function`
+- 默认值: `undefined`
+
+注册一个额外的 command 来增强 vuepress 的 CLI。这个函数将会以一个 [CAC](https://github.com/cacjs/cac) 的实例作为第一个参数被调用。
+
+```js
+module.exports = {
+  registerCommand (cli) {
+    cli
+      .command('info [targetDir]', '')
+      .option('--debug', 'display info in debug mode')
+      .action((dir = '.') => {
+        console.log('Display info of your website')
+      })
+  }
+}
+```
+
+现在你可以在你项目中使用 `vuepress info [targetDir]` 了！
+
+::: tip
+值得注意的是，一个自定义的 command 需要 VuePress 像 `vuepress dev` 或 `vuepress build` 去定位到你的站点配置，所以在开发一个 command 时，请确保引导用户去传入 `targetDir` 作为 CLI 参数的一部分。
+:::
+

packages/docs/docs/miscellaneous/design-concepts.md

@@ -5,7 +5,8 @@
   "description": "docs of VuePress",
   "scripts": {
     "dev": "vuepress dev docs --temp .temp",
-    "build": "vuepress build docs --temp .temp"
+    "build": "vuepress build docs --temp .temp",
+    "show-help": "vuepress --help"
   },
   "repository": {
     "type": "git",

packages/docs/docs/plugin/option-api.md

@@ -0,0 +1,25 @@
+'use strict'
+
+/**
+ * Module dependencies.
+ */
+
+const { chalk } = require('@vuepress/shared-utils')
+const semver = require('semver')
+
+/**
+ * Expose handleUnknownCommand function.
+ */
+
+module.exports = function checkEnv (pkg) {
+  const requiredVersion = pkg.engines.node
+
+  if (!semver.satisfies(process.version, requiredVersion)) {
+    console.log(chalk.red(
+      `\n[vuepress] minimum Node version not met:` +
+      `\nYou are using Node ${process.version}, but VuePress ` +
+      `requires Node ${requiredVersion}.\nPlease upgrade your Node version.\n`
+    ))
+    process.exit(1)
+  }
+}