@zhennann/common-bin 2.9.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-present node-modules and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,430 @@
+# common-bin
+
+[![NPM version][npm-image]][npm-url]
+[![Test coverage][codecov-image]][codecov-url]
+[![Known Vulnerabilities][snyk-image]][snyk-url]
+[![npm download][download-image]][download-url]
+
+[npm-image]: https://img.shields.io/npm/v/common-bin.svg?style=flat-square
+[npm-url]: https://npmjs.org/package/common-bin
+[codecov-image]: https://codecov.io/gh/node-modules/common-bin/branch/master/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/node-modules/common-bin
+[snyk-image]: https://snyk.io/test/npm/common-bin/badge.svg?style=flat-square
+[snyk-url]: https://snyk.io/test/npm/common-bin
+[download-image]: https://img.shields.io/npm/dm/common-bin.svg?style=flat-square
+[download-url]: https://npmjs.org/package/common-bin
+
+Abstraction bin tool wrap [yargs](http://yargs.js.org/), to provide more convenient usage, support async / generator.
+
+---
+
+## Install
+
+```bash
+$ npm i common-bin
+```
+
+## Build a bin tool for your team
+
+You maybe need a custom xxx-bin to implement more custom features.
+
+Now you can implement a [Command](lib/command.js) sub class to do that.
+
+### Example: Write your own `git` command
+
+This example will show you how to create a new `my-git` tool.
+
+- Full demo: [my-git](test/fixtures/my-git)
+
+```bash
+test/fixtures/my-git
+├── bin
+│   └── my-git.js
+├── command
+│   ├── remote
+│   │   ├── add.js
+│   │   └── remove.js
+│   ├── clone.js
+│   └── remote.js
+├── index.js
+└── package.json
+```
+
+#### [my-git.js](test/fixtures/my-git/bin/my-git.js)
+
+```js
+#!/usr/bin/env node
+
+'use strict';
+
+const Command = require('..');
+new Command().start();
+```
+
+#### [Main Command](test/fixtures/my-git/index.js)
+
+Just extend `Command`, and use as your bin start point.
+
+You can use `this.yargs` to custom yargs config, see http://yargs.js.org/docs for more detail.
+
+```js
+const Command = require('common-bin');
+const pkg = require('./package.json');
+
+class MainCommand extends Command {
+  constructor(rawArgv) {
+    super(rawArgv);
+    this.usage = 'Usage: my-git <command> [options]';
+
+    // load entire command directory
+    this.load(path.join(__dirname, 'command'));
+
+    // or load special command file
+    // this.add(path.join(__dirname, 'test_command.js'));
+
+    // more custom with `yargs` api, such as you can use `my-git -V`
+    this.yargs.alias('V', 'version');
+  }
+}
+
+module.exports = MainCommand;
+```
+
+#### [CloneCommand](test/fixtures/my-git/command/clone.js)
+
+```js
+const Command = require('common-bin');
+class CloneCommand extends Command {
+  constructor(rawArgv) {
+    super(rawArgv);
+
+    this.options = {
+      depth: {
+        type: 'number',
+        description: 'Create a shallow clone with a history truncated to the specified number of commits',
+      },
+    };
+  }
+
+  * run({ argv }) {
+    console.log('git clone %s to %s with depth %d', argv._[0], argv._[1], argv.depth);
+  }
+
+  get description() {
+    return 'Clone a repository into a new directory';
+  }
+}
+
+module.exports = CloneCommand;
+```
+
+#### Run result
+
+```bash
+$ my-git clone gh://node-modules/common-bin dist --depth=1
+
+git clone gh://node-modules/common-bin to dist with depth 1
+```
+
+## Concept
+
+### Command
+
+Define the main logic of command
+
+**Method:**
+
+- `start()` - start your program, only use once in your bin file.
+- `run(context)`
+  - should implement this to provide command handler, will exec when not found sub command.
+  - Support generator / async function / normal function which return promise.
+  - `context` is `{ cwd, env, argv, rawArgv }`
+    - `cwd` - `process.cwd()`
+    - `env` - clone env object from `process.env`
+    - `argv` - argv parse result by yargs, `{ _: [ 'start' ], '$0': '/usr/local/bin/common-bin', baseDir: 'simple'}`
+    - `rawArgv` - the raw argv, `[ "--baseDir=simple" ]`
+- `load(fullPath)` - register the entire directory to commands
+- `add(name, target)` - register special command with command name, `target` could be full path of file or Class.
+- `alias(alias, name)` - register a command with an existing command
+- `showHelp()` - print usage message to console.
+- `options=` - a setter, shortcut for `yargs.options`
+- `usage=` - a setter, shortcut for `yargs.usage`
+
+**Properties:**
+
+- `description` - {String} a getter, only show this description when it's a sub command in help console
+- `helper` - {Object} helper instance
+- `yargs` - {Object} yargs instance for advanced custom usage
+- `options` - {Object} a setter, set yargs' options
+- `version` - {String} customize version, can be defined as a getter to support lazy load.
+- `parserOptions` - {Object} control `context` parse rule.
+  - `execArgv` - {Boolean} whether extract `execArgv` to `context.execArgv`
+  - `removeAlias` - {Boolean} whether remove alias key from `argv`
+  - `removeCamelCase` - {Boolean} whether remove camel case key from `argv`
+
+You can define options by set `this.options`
+
+```js
+this.options = {
+  baseDir: {
+    alias: 'b',
+    demandOption: true,
+    description: 'the target directory',
+    coerce: str => path.resolve(process.cwd(), str),
+  },
+  depth: {
+    description: 'level to clone',
+    type: 'number',
+    default: 1,
+  },
+  size: {
+    description: 'choose a size',
+    choices: ['xs', 's', 'm', 'l', 'xl']
+  },
+};
+```
+
+You can define version by define `this.version` getter:
+
+```js
+get version() {
+  return 'v1.0.0';
+}
+```
+
+### Helper
+
+- `forkNode(modulePath, args, opt)` - fork child process, wrap with promise and gracefull exit
+- `spawn(cmd, args, opt)` - spawn a new process, wrap with promise and gracefull exit
+- `npmInstall(npmCli, name, cwd)` - install node modules, wrap with promise
+- `* callFn(fn, args, thisArg)` - call fn, support gernerator / async / normal function return promise
+- `unparseArgv(argv, opts)` - unparse argv and change it to array style
+
+**Extend Helper**
+
+```js
+// index.js
+const Command = require('common-bin');
+const helper = require('./helper');
+class MainCommand extends Command {
+  constructor(rawArgv) {
+    super(rawArgv);
+
+    // load sub command
+    this.load(path.join(__dirname, 'command'));
+
+    // custom helper
+    Object.assign(this.helper, helper);
+  }
+}
+```
+
+## Advanced Usage
+
+### Single Command
+
+Just need to provide `options` and `run()`.
+
+```js
+const Command = require('common-bin');
+class MainCommand extends Command {
+  constructor(rawArgv) {
+    super(rawArgv);
+    this.options = {
+      baseDir: {
+        description: 'target directory',
+      },
+    };
+  }
+
+  * run(context) {
+    console.log('run default command at %s', context.argv.baseDir);
+  }
+}
+```
+
+### Sub Command
+
+Also support sub command such as `my-git remote add <name> <url> --tags`.
+
+```js
+// test/fixtures/my-git/command/remote.js
+class RemoteCommand extends Command {
+  constructor(rawArgv) {
+    // DO NOT forgot to pass params to super
+    super(rawArgv);
+    // load sub command for directory
+    this.load(path.join(__dirname, 'remote'));
+  }
+
+  * run({ argv }) {
+    console.log('run remote command with %j', argv._);
+  }
+
+  get description() {
+    return 'Manage set of tracked repositories';
+  }
+}
+
+// test/fixtures/my-git/command/remote/add.js
+class AddCommand extends Command {
+  constructor(rawArgv) {
+    super(rawArgv);
+
+    this.options = {
+      tags: {
+        type: 'boolean',
+        default: false,
+        description: 'imports every tag from the remote repository',
+      },
+    };
+
+  }
+
+  * run({ argv }) {
+    console.log('git remote add %s to %s with tags=%s', argv.name, argv.url, argv.tags);
+  }
+
+  get description() {
+    return 'Adds a remote named <name> for the repository at <url>';
+  }
+}
+```
+
+see [remote.js](test/fixtures/my-git/command/remote.js) for more detail.
+
+
+### Async Support
+
+```js
+class SleepCommand extends Command {
+
+  async run() {
+    await sleep('1s');
+    console.log('sleep 1s');
+  }
+
+  get description() {
+    return 'sleep showcase';
+  }
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+```
+
+see [async-bin](test/fixtures/async-bin) for more detail.
+
+
+### Bash-Completions
+
+```bash
+$ # exec below will print usage for auto bash completion
+$ my-git completion
+$ # exec below will mount auto completion to your bash
+$ my-git completion >> ~/.bashrc
+```
+
+![Bash-Completions](https://cloud.githubusercontent.com/assets/227713/23980327/0a00e1a0-0a3a-11e7-81be-23b4d54d91ad.gif)
+
+
+## Migrating from v1 to v2
+
+### bin
+
+- `run` method is not longer exist.
+
+```js
+// 1.x
+const run = require('common-bin').run;
+run(require('../lib/my_program'));
+
+// 2.x
+// require a main Command
+const Command = require('..');
+new Command().start();
+```
+
+### Program
+
+- `Program` is just a `Command` sub class, you can call it `Main Command` now.
+- `addCommand()` is replace with `add()`.
+- Recommand to use `load()` to load the whole command directory.
+
+```js
+// 1.x
+this.addCommand('test', path.join(__dirname, 'test_command.js'));
+
+// 2.x
+const Command = require('common-bin');
+const pkg = require('./package.json');
+
+class MainCommand extends Command {
+  constructor() {
+    super();
+
+    this.add('test', path.join(__dirname, 'test_command.js'));
+    // or load the entire directory
+    this.load(path.join(__dirname, 'command'));
+  }
+}
+```
+
+### Command
+
+- `help()` is not use anymore.
+- should provide `name`, `description`, `options`.
+- `* run()` arguments had change to object, recommand to use destructuring style - `{ cwd, env, argv, rawArgv }`
+  - `argv` is an object parse by `yargs`, **not `args`.**
+  - `rawArgv` is equivalent to old `args`
+
+```js
+// 1.x
+class TestCommand extends Command {
+  * run(cwd, args) {
+    console.log('run mocha test at %s with %j', cwd, args);
+  }
+}
+
+// 2.x
+class TestCommand extends Command {
+  constructor() {
+    super();
+    // my-bin test --require=co-mocha
+    this.options = {
+      require: {
+        description: 'require module name',
+      },
+    };
+  }
+
+  * run({ cwd, env, argv, rawArgv }) {
+    console.log('run mocha test at %s with %j', cwd, argv);
+  }
+
+  get description() {
+    return 'unit test';
+  }
+}
+```
+
+### helper
+
+- `getIronNodeBin` is remove.
+- `child.kill` now support signal.
+
+## License
+
+[MIT](LICENSE)
+<!-- GITCONTRIBUTOR_START -->
+
+## Contributors
+
+|[<img src="https://avatars.githubusercontent.com/u/227713?v=4" width="100px;"/><br/><sub><b>atian25</b></sub>](https://github.com/atian25)<br/>|[<img src="https://avatars.githubusercontent.com/u/156269?v=4" width="100px;"/><br/><sub><b>fengmk2</b></sub>](https://github.com/fengmk2)<br/>|[<img src="https://avatars.githubusercontent.com/u/360661?v=4" width="100px;"/><br/><sub><b>popomore</b></sub>](https://github.com/popomore)<br/>|[<img src="https://avatars.githubusercontent.com/u/985607?v=4" width="100px;"/><br/><sub><b>dead-horse</b></sub>](https://github.com/dead-horse)<br/>|[<img src="https://avatars.githubusercontent.com/u/5856440?v=4" width="100px;"/><br/><sub><b>whxaxes</b></sub>](https://github.com/whxaxes)<br/>|[<img src="https://avatars.githubusercontent.com/u/9692408?v=4" width="100px;"/><br/><sub><b>DiamondYuan</b></sub>](https://github.com/DiamondYuan)<br/>|
+| :---: | :---: | :---: | :---: | :---: | :---: |
+[<img src="https://avatars.githubusercontent.com/u/7477670?v=4" width="100px;"/><br/><sub><b>tenpend</b></sub>](https://github.com/tenpend)<br/>|[<img src="https://avatars.githubusercontent.com/u/6399899?v=4" width="100px;"/><br/><sub><b>hacke2</b></sub>](https://github.com/hacke2)<br/>|[<img src="https://avatars.githubusercontent.com/u/11896359?v=4" width="100px;"/><br/><sub><b>liuqipeng417</b></sub>](https://github.com/liuqipeng417)<br/>|[<img src="https://avatars.githubusercontent.com/u/36788851?v=4" width="100px;"/><br/><sub><b>Jarvis2018</b></sub>](https://github.com/Jarvis2018)<br/>
+
+This project follows the git-contributor [spec](https://github.com/xudafeng/git-contributor), auto updated at `Wed Feb 09 2022 22:35:03 GMT+0800`.
+
+<!-- GITCONTRIBUTOR_END -->

package/index.d.ts

@@ -0,0 +1,188 @@
+import { Arguments, Argv, Options } from 'yargs';
+import { ForkOptions, SpawnOptions } from 'child_process';
+import * as dargs from 'dargs';
+
+interface PlainObject {
+  [key: string]: any;
+}
+
+// migrating to common-bin later
+declare class CommonBin {
+  usage: string;
+  version: string;
+
+  /**
+   * original argument
+   * @type {Array}
+   */
+  rawArgv: string[];
+
+  /**
+   * yargs
+   * @type {Object}
+   */
+  yargs: Argv;
+
+  /**
+   * helper function
+   * @type {Object}
+   */
+  helper: CommonBin.Helper;
+
+  /**
+   * parserOptions
+   * @type {Object}
+   * @property {Boolean} execArgv - whether extract `execArgv` to `context.execArgv`
+   * @property {Boolean} removeAlias - whether remove alias key from `argv`
+   * @property {Boolean} removeCamelCase - whether remove camel case key from `argv`
+   */
+  parserOptions: {
+    execArgv: boolean;
+    removeAlias: boolean;
+    removeCamelCase: boolean;
+  };
+
+  /**
+   * getter of context, default behavior is remove `help` / `h` / `version`
+   * @return {Object} context - { cwd, env, argv, rawArgv }
+   * @protected
+   */
+  protected context: CommonBin.Context;
+
+  constructor(rawArgv?: string[]);
+
+
+  /**
+   * shortcut for yargs.options
+   * @param  {Object} opt - an object set to `yargs.options`
+   */
+  set options(opt: { [key: string]: Options });
+
+  /**
+   * command handler, could be generator / async function / normal function which return promise
+   * @param {Object} context - context object
+   * @param {String} context.cwd - process.cwd()
+   * @param {Object} context.argv - argv parse result by yargs, `{ _: [ 'start' ], '$0': '/usr/local/bin/common-bin', baseDir: 'simple'}`
+   * @param {Array} context.rawArgv - the raw argv, `[ "--baseDir=simple" ]`
+   * @protected
+   */
+  protected run(context?: CommonBin.Context): any;
+
+  /**
+   * load sub commands
+   * @param {String} fullPath - the command directory
+   * @example `load(path.join(__dirname, 'command'))`
+   */
+  load(fullPath: string): void;
+
+  /**
+   * add sub command
+   * @param {String} name - a command name
+   * @param {String|Class} target - special file path (must contains ext) or Command Class
+   * @example `add('test', path.join(__dirname, 'test_command.js'))`
+   */
+  add(name: string, target: string | CommonBin): void;
+
+  /**
+   * alias an existing command
+   * @param {String} alias - alias command
+   * @param {String} name - exist command
+   */
+  alias(alias: string, name: string): void;
+
+  /**
+   * start point of bin process
+   */
+  start(): void;
+
+  /**
+   * default error hander
+   * @param {Error} err - error object
+   * @protected
+   */
+  protected errorHandler(err: Error): void;
+
+  /**
+   * print help message to console
+   * @param {String} [level=log] - console level
+   */
+  showHelp(level?: string): void;
+}
+
+declare namespace CommonBin {
+  export interface Helper {
+    /**
+     * fork child process, wrap with promise and gracefull exit
+     * @method helper#forkNode
+     * @param {String} modulePath - bin path
+     * @param {Array} [args] - arguments
+     * @param {Object} [options] - options
+     * @return {Promise} err or undefined
+     * @see https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options
+     */
+    forkNode(modulePath: string, args?: string[], options?: ForkOptions): Promise<void>;
+
+    /**
+     * spawn a new process, wrap with promise and gracefull exit
+     * @method helper#forkNode
+     * @param {String} cmd - command
+     * @param {Array} [args] - arguments
+     * @param {Object} [options] - options
+     * @return {Promise} err or undefined
+     * @see https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options
+     */
+    spawn(cmd: string, args?: string[], options?: SpawnOptions): Promise<void>;
+
+    /**
+     * exec npm install
+     * @method helper#npmInstall
+     * @param {String} npmCli - npm cli, such as `npm` / `cnpm` / `npminstall`
+     * @param {String} name - node module name
+     * @param {String} cwd - target directory
+     * @return {Promise} err or undefined
+     */
+    npmInstall(npmCli: string, name: string, cwd?: string): Promise<void>;
+
+    /**
+     * call fn
+     * @method helper#callFn
+     * @param {Function} fn - support generator / async / normal function return promise
+     * @param {Array} [args] - fn args
+     * @param {Object} [thisArg] - this
+     * @return {Object} result
+     */
+    callFn<T = any, U extends any[] = any[]>(fn: (...args: U) => IterableIterator<T> | Promise<T> | T, args?: U, thisArg?: any): IterableIterator<T>;
+
+    /**
+     * unparse argv and change it to array style
+     * @method helper#unparseArgv
+     * @param {Object} argv - yargs style
+     * @param {Object} [options] - options, see more at https://github.com/sindresorhus/dargs
+     * @param {Array} [options.includes] - keys or regex of keys to include
+     * @param {Array} [options.excludes] - keys or regex of keys to exclude
+     * @return {Array} [ '--debug=7000', '--debug-brk' ]
+     */
+    unparseArgv(argv: object, options?: dargs.Options): string[];
+
+    /**
+     * extract execArgv from argv
+     * @method helper#extractExecArgv
+     * @param {Object} argv - yargs style
+     * @return {Object} { debugPort, debugOptions: {}, execArgvObj: {} }
+     */
+    extractExecArgv(argv: object): { debugPort?: number; debugOptions?: PlainObject; execArgvObj: PlainObject };
+  }
+
+  export interface Context extends PlainObject {
+    cwd: string;
+    rawArgv: string[];
+    env: PlainObject;
+    argv: Arguments<PlainObject>;
+    execArgvObj: PlainObject;
+    readonly execArgv: string[];
+    debugPort?: number;
+    debugOptions?: PlainObject;
+  }
+}
+
+export = CommonBin;

package/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./lib/command');

package/lib/command.js

@@ -0,0 +1,370 @@
+'use strict';
+
+const debug = require('debug')('common-bin');
+const co = require('co');
+const yargs = require('yargs');
+const parser = require('yargs-parser');
+const helper = require('./helper');
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const semver = require('semver');
+const changeCase = require('change-case');
+const chalk = require('chalk');
+
+const DISPATCH = Symbol.for('eb:Command#dispatch');
+const PARSE = Symbol('Command#parse');
+const COMMANDS = Symbol('Command#commands');
+const VERSION = Symbol('Command#version');
+
+class CommonBin {
+  constructor(rawArgv) {
+    /**
+     * original argument
+     * @type {Array}
+     */
+    this.rawArgv = rawArgv || process.argv.slice(2);
+    debug('[%s] origin argument `%s`', this.constructor.name, this.rawArgv.join(' '));
+
+    /**
+     * yargs
+     * @type {Object}
+     */
+    this.yargs = yargs(this.rawArgv);
+
+    /**
+     * helper function
+     * @type {Object}
+     */
+    this.helper = helper;
+
+    /**
+     * parserOptions
+     * @type {Object}
+     * @property {Boolean} execArgv - whether extract `execArgv` to `context.execArgv`
+     * @property {Boolean} removeAlias - whether remove alias key from `argv`
+     * @property {Boolean} removeCamelCase - whether remove camel case key from `argv`
+     */
+    this.parserOptions = {
+      execArgv: false,
+      removeAlias: false,
+      removeCamelCase: false,
+    };
+
+    // <commandName, Command>
+    this[COMMANDS] = new Map();
+  }
+
+  /**
+   * command handler, could be generator / async function / normal function which return promise
+   * @param {Object} context - context object
+   * @param {String} context.cwd - process.cwd()
+   * @param {Object} context.argv - argv parse result by yargs, `{ _: [ 'start' ], '$0': '/usr/local/bin/common-bin', baseDir: 'simple'}`
+   * @param {Array} context.rawArgv - the raw argv, `[ "--baseDir=simple" ]`
+   * @protected
+   */
+  run() {
+    this.showHelp();
+  }
+
+  /**
+   * load sub commands
+   * @param {String} fullPath - the command directory
+   * @example `load(path.join(__dirname, 'command'))`
+   */
+  load(fullPath) {
+    assert(fs.existsSync(fullPath) && fs.statSync(fullPath).isDirectory(),
+      `${fullPath} should exist and be a directory`);
+
+    // load entire directory
+    const files = fs.readdirSync(fullPath);
+    const names = [];
+    for (const file of files) {
+      if (path.extname(file) === '.js') {
+        const name = path.basename(file).replace(/\.js$/, '');
+        names.push(name);
+        this.add(name, path.join(fullPath, file));
+      }
+    }
+
+    debug('[%s] loaded command `%s` from directory `%s`',
+      this.constructor.name, names, fullPath);
+  }
+
+  /**
+   * add sub command
+   * @param {String} name - a command name
+   * @param {String|Class} target - special file path (must contains ext) or Command Class
+   * @example `add('test', path.join(__dirname, 'test_command.js'))`
+   */
+  add(name, target) {
+    assert(name, `${name} is required`);
+    if (!(target.prototype instanceof CommonBin)) {
+      assert(fs.existsSync(target) && fs.statSync(target).isFile(), `${target} is not a file.`);
+      debug('[%s] add command `%s` from `%s`', this.constructor.name, name, target);
+      target = require(target);
+      // try to require es module
+      if (target && target.__esModule && target.default) {
+        target = target.default;
+      }
+      assert(target.prototype instanceof CommonBin,
+        'command class should be sub class of common-bin');
+    }
+    this[COMMANDS].set(name, target);
+  }
+
+  /**
+   * alias an existing command
+   * @param {String} alias - alias command
+   * @param {String} name - exist command
+   */
+  alias(alias, name) {
+    assert(alias, 'alias command name is required');
+    assert(this[COMMANDS].has(name), `${name} should be added first`);
+    debug('[%s] set `%s` as alias of `%s`', this.constructor.name, alias, name);
+    this[COMMANDS].set(alias, this[COMMANDS].get(name));
+  }
+
+  /**
+   * start point of bin process
+   */
+  start() {
+    co(function* () {
+      // replace `--get-yargs-completions` to our KEY, so yargs will not block our DISPATCH
+      const index = this.rawArgv.indexOf('--get-yargs-completions');
+      if (index !== -1) {
+        // bash will request as `--get-yargs-completions my-git remote add`, so need to remove 2
+        this.rawArgv.splice(index, 2, `--AUTO_COMPLETIONS=${this.rawArgv.join(',')}`);
+      }
+      yield this[DISPATCH]();
+    }.bind(this)).catch(this.errorHandler.bind(this));
+  }
+
+  /**
+   * default error hander
+   * @param {Error} err - error object
+   * @protected
+   */
+  errorHandler(err) {
+    console.error(chalk.red(`⚠️  ${err.name}: ${err.message}`));
+    console.error(chalk.red('⚠️  Command Error, enable `DEBUG=common-bin` for detail'));
+    debug('args %s', process.argv.slice(3));
+    debug(err.stack);
+    process.exit(1);
+  }
+
+  /**
+   * print help message to console
+   * @param {String} [level=log] - console level
+   */
+  showHelp(level = 'log') {
+    this.yargs.showHelp(level);
+  }
+
+  /**
+   * shortcut for yargs.options
+   * @param  {Object} opt - an object set to `yargs.options`
+   */
+  set options(opt) {
+    this.yargs.options(opt);
+  }
+
+  /**
+   * shortcut for yargs.usage
+   * @param  {String} usage - usage info
+   */
+  set usage(usage) {
+    this.yargs.usage(usage);
+  }
+
+  set version(ver) {
+    this[VERSION] = ver;
+  }
+
+  get version() {
+    return this[VERSION];
+  }
+
+  /**
+   * instantiaze sub command
+   * @param {CommonBin} Clz - sub command class
+   * @param {Array} args - args
+   * @return {CommonBin} sub command instance
+   */
+  getSubCommandInstance(Clz, ...args) {
+    return new Clz(...args);
+  }
+
+  /**
+   * dispatch command, either `subCommand.exec` or `this.run`
+   * @param {Object} context - context object
+   * @param {String} context.cwd - process.cwd()
+   * @param {Object} context.argv - argv parse result by yargs, `{ _: [ 'start' ], '$0': '/usr/local/bin/common-bin', baseDir: 'simple'}`
+   * @param {Array} context.rawArgv - the raw argv, `[ "--baseDir=simple" ]`
+   * @private
+   */
+  * [DISPATCH]() {
+    // define --help and --version by default
+    this.yargs
+      // .reset()
+      .completion()
+      .help()
+      .version()
+      .wrap(120)
+      .alias('h', 'help')
+      .alias('v', 'version')
+      .group([ 'help', 'version' ], 'Global Options:');
+
+    // get parsed argument without handling helper and version
+    const parsed = yield this[PARSE](this.rawArgv);
+    const commandName = parsed._[0];
+
+    if (parsed.version && this.version) {
+      console.log(this.version);
+      return;
+    }
+
+    // if sub command exist
+    if (this[COMMANDS].has(commandName)) {
+      const Command = this[COMMANDS].get(commandName);
+      const rawArgv = this.rawArgv.slice();
+      rawArgv.splice(rawArgv.indexOf(commandName), 1);
+
+      debug('[%s] dispatch to subcommand `%s` -> `%s` with %j', this.constructor.name, commandName, Command.name, rawArgv);
+      const command = this.getSubCommandInstance(Command, rawArgv);
+      yield command[DISPATCH]();
+      return;
+    }
+
+    // register command for printing
+    for (const [ name, Command ] of this[COMMANDS].entries()) {
+      this.yargs.command(name, Command.prototype.description || '');
+    }
+
+    debug('[%s] exec run command', this.constructor.name);
+    const context = this.context;
+
+    // print completion for bash
+    if (context.argv.AUTO_COMPLETIONS) {
+      // slice to remove `--AUTO_COMPLETIONS=` which we append
+      this.yargs.getCompletion(this.rawArgv.slice(1), completions => {
+        // console.log('%s', completions)
+        completions.forEach(x => console.log(x));
+      });
+    } else {
+      // handle by self
+      yield this.helper.callFn(this.run, [ context ], this);
+    }
+  }
+
+  /**
+   * getter of context, default behavior is remove `help` / `h` / `version`
+   * @return {Object} context - { cwd, env, argv, rawArgv }
+   * @protected
+   */
+  get context() {
+    const argv = this.yargs.argv;
+    const context = {
+      argv,
+      cwd: process.cwd(),
+      env: Object.assign({}, process.env),
+      rawArgv: this.rawArgv,
+    };
+
+    argv.help = undefined;
+    argv.h = undefined;
+    argv.version = undefined;
+    argv.v = undefined;
+
+    // remove alias result
+    if (this.parserOptions.removeAlias) {
+      const aliases = this.yargs.getOptions().alias;
+      for (const key of Object.keys(aliases)) {
+        aliases[key].forEach(item => {
+          argv[item] = undefined;
+        });
+      }
+    }
+
+    // remove camel case result
+    if (this.parserOptions.removeCamelCase) {
+      for (const key of Object.keys(argv)) {
+        if (key.includes('-')) {
+          argv[changeCase.camel(key)] = undefined;
+        }
+      }
+    }
+
+    // extract execArgv
+    if (this.parserOptions.execArgv) {
+      // extract from command argv
+      let { debugPort, debugOptions, execArgvObj } = this.helper.extractExecArgv(argv);
+
+      // extract from WebStorm env `$NODE_DEBUG_OPTION`
+      // Notice: WebStorm 2019 won't export the env, instead, use `env.NODE_OPTIONS="--require="`, but we can't extract it.
+      if (context.env.NODE_DEBUG_OPTION) {
+        console.log('Use $NODE_DEBUG_OPTION: %s', context.env.NODE_DEBUG_OPTION);
+        const argvFromEnv = parser(context.env.NODE_DEBUG_OPTION);
+        const obj = this.helper.extractExecArgv(argvFromEnv);
+        debugPort = obj.debugPort || debugPort;
+        Object.assign(debugOptions, obj.debugOptions);
+        Object.assign(execArgvObj, obj.execArgvObj);
+      }
+
+      // `--expose_debug_as` is not supported by 7.x+
+      if (execArgvObj.expose_debug_as && semver.gte(process.version, '7.0.0')) {
+        console.warn(chalk.yellow(`Node.js runtime is ${process.version}, and inspector protocol is not support --expose_debug_as`));
+      }
+
+      // remove from origin argv
+      for (const key of Object.keys(execArgvObj)) {
+        argv[key] = undefined;
+        argv[changeCase.camel(key)] = undefined;
+      }
+
+      // exports execArgv
+      const self = this;
+      context.execArgvObj = execArgvObj;
+
+      // convert execArgvObj to execArgv
+      // `--require` should be `--require abc --require 123`, not allow `=`
+      // `--debug` should be `--debug=9999`, only allow `=`
+      Object.defineProperty(context, 'execArgv', {
+        get() {
+          const lazyExecArgvObj = context.execArgvObj;
+          const execArgv = self.helper.unparseArgv(lazyExecArgvObj, { excludes: [ 'require' ] });
+          // convert require to execArgv
+          let requireArgv = lazyExecArgvObj.require;
+          if (requireArgv) {
+            if (!Array.isArray(requireArgv)) requireArgv = [ requireArgv ];
+            requireArgv.forEach(item => {
+              execArgv.push('--require');
+              execArgv.push(item.startsWith('./') || item.startsWith('.\\') ? path.resolve(context.cwd, item) : item);
+            });
+          }
+          return execArgv;
+        },
+      });
+
+      // only exports debugPort when any match
+      if (Object.keys(debugOptions).length) {
+        context.debugPort = debugPort;
+        context.debugOptions = debugOptions;
+      }
+    }
+
+    return context;
+  }
+
+  [PARSE](rawArgv) {
+    return new Promise((resolve, reject) => {
+      this.yargs.parse(rawArgv, (err, argv) => {
+        /* istanbul ignore next */
+        if (err) return reject(err);
+        resolve(argv);
+      });
+    });
+  }
+}
+
+module.exports = CommonBin;

package/lib/helper.js

@@ -0,0 +1,189 @@
+'use strict';
+
+const debug = require('debug')('common-bin');
+const cp = require('child_process');
+const is = require('is-type-of');
+const unparse = require('dargs');
+
+// only hook once and only when ever start any child.
+const childs = new Set();
+let hadHook = false;
+function gracefull(proc) {
+  // save child ref
+  childs.add(proc);
+
+  // only hook once
+  /* istanbul ignore else */
+  if (!hadHook) {
+    hadHook = true;
+    let signal;
+    [ 'SIGINT', 'SIGQUIT', 'SIGTERM' ].forEach(event => {
+      process.once(event, () => {
+        signal = event;
+        process.exit(0);
+      });
+    });
+
+    process.once('exit', () => {
+      // had test at my-helper.test.js, but coffee can't collect coverage info.
+      for (const child of childs) {
+        debug('kill child %s with %s', child.pid, signal);
+        child.kill(signal);
+      }
+    });
+  }
+}
+
+/**
+ * fork child process, wrap with promise and gracefull exit
+ * @function helper#forkNode
+ * @param {String} modulePath - bin path
+ * @param {Array} [args] - arguments
+ * @param {Object} [options] - options
+ * @return {Promise} err or undefined
+ * @see https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options
+ */
+exports.forkNode = (modulePath, args = [], options = {}) => {
+  options.stdio = options.stdio || 'inherit';
+  debug('Run fork `%s %s %s`', process.execPath, modulePath, args.join(' '));
+  const proc = cp.fork(modulePath, args, options);
+  gracefull(proc);
+
+  const promise = new Promise((resolve, reject) => {
+    proc.once('exit', code => {
+      childs.delete(proc);
+      if (code !== 0) {
+        const err = new Error(modulePath + ' ' + args + ' exit with code ' + code);
+        err.code = code;
+        reject(err);
+      } else {
+        resolve();
+      }
+    });
+  });
+
+  promise.proc = proc;
+
+  return promise;
+};
+
+/**
+ * spawn a new process, wrap with promise and gracefull exit
+ * @function helper#forkNode
+ * @param {String} cmd - command
+ * @param {Array} [args] - arguments
+ * @param {Object} [options] - options
+ * @return {Promise} err or undefined
+ * @see https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options
+ */
+exports.spawn = (cmd, args = [], options = {}) => {
+  options.stdio = options.stdio || 'inherit';
+  debug('Run spawn `%s %s`', cmd, args.join(' '));
+
+  return new Promise((resolve, reject) => {
+    const proc = cp.spawn(cmd, args, options);
+    gracefull(proc);
+    proc.once('error', err => {
+      /* istanbul ignore next */
+      reject(err);
+    });
+    proc.once('exit', code => {
+      childs.delete(proc);
+
+      if (code !== 0) {
+        return reject(new Error(`spawn ${cmd} ${args.join(' ')} fail, exit code: ${code}`));
+      }
+      resolve();
+    });
+  });
+};
+
+/**
+ * exec npm install
+ * @function helper#npmInstall
+ * @param {String} npmCli - npm cli, such as `npm` / `cnpm` / `npminstall`
+ * @param {String} name - node module name
+ * @param {String} cwd - target directory
+ * @return {Promise} err or undefined
+ */
+exports.npmInstall = (npmCli, name, cwd) => {
+  const options = {
+    stdio: 'inherit',
+    env: process.env,
+    cwd,
+  };
+
+  const args = [ 'i', name ];
+  console.log('[common-bin] `%s %s` to %s ...', npmCli, args.join(' '), options.cwd);
+
+  return exports.spawn(npmCli, args, options);
+};
+
+/**
+ * call fn
+ * @function helper#callFn
+ * @param {Function} fn - support generator / async / normal function return promise
+ * @param {Array} [args] - fn args
+ * @param {Object} [thisArg] - this
+ * @return {Object} result
+ */
+exports.callFn = function* (fn, args = [], thisArg) {
+  if (!is.function(fn)) return;
+  if (is.generatorFunction(fn)) {
+    return yield fn.apply(thisArg, args);
+  }
+  const r = fn.apply(thisArg, args);
+  if (is.promise(r)) {
+    return yield r;
+  }
+  return r;
+};
+
+/**
+ * unparse argv and change it to array style
+ * @function helper#unparseArgv
+ * @param {Object} argv - yargs style
+ * @param {Object} [options] - options, see more at https://github.com/sindresorhus/dargs
+ * @param {Array} [options.includes] - keys or regex of keys to include
+ * @param {Array} [options.excludes] - keys or regex of keys to exclude
+ * @return {Array} [ '--debug=7000', '--debug-brk' ]
+ */
+exports.unparseArgv = (argv, options = {}) => {
+  // revert argv object to array
+  // yargs will paser `debug-brk` to `debug-brk` and `debugBrk`, so we need to filter
+  return [ ...new Set(unparse(argv, options)) ];
+};
+
+/**
+ * extract execArgv from argv
+ * @function helper#extractExecArgv
+ * @param {Object} argv - yargs style
+ * @return {Object} { debugPort, debugOptions: {}, execArgvObj: {} }
+ */
+exports.extractExecArgv = argv => {
+  const debugOptions = {};
+  const execArgvObj = {};
+  let debugPort;
+
+  for (const key of Object.keys(argv)) {
+    const value = argv[key];
+    // skip undefined set uppon (camel etc.)
+    if (value === undefined) continue;
+    // debug / debug-brk / debug-port / inspect / inspect-brk / inspect-port
+    if ([ 'debug', 'debug-brk', 'debug-port', 'inspect', 'inspect-brk', 'inspect-port' ].includes(key)) {
+      if (typeof value === 'number') debugPort = value;
+      debugOptions[key] = argv[key];
+      execArgvObj[key] = argv[key];
+    } else if (match(key, [ 'es_staging', 'expose_debug_as', /^harmony.*/ ])) {
+      execArgvObj[key] = argv[key];
+    } else if (key.startsWith('node-options--')) {
+      // support node options, like: commond --node-options--trace-warnings => execArgv.push('--trace-warnings')
+      execArgvObj[key.replace('node-options--', '')] = argv[key];
+    }
+  }
+  return { debugPort, debugOptions, execArgvObj };
+};
+
+function match(key, arr) {
+  return arr.some(x => x instanceof RegExp ? x.test(key) : x === key); // eslint-disable-line no-confusing-arrow
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@zhennann/common-bin",
+  "version": "2.9.2",
+  "description": "Abstraction bin tool",
+  "main": "index.js",
+  "dependencies": {
+    "@types/dargs": "^5.1.0",
+    "@types/node": "^10.12.18",
+    "@types/yargs": "^12.0.4",
+    "chalk": "^2.4.1",
+    "change-case": "^3.0.2",
+    "co": "^4.6.0",
+    "dargs": "^6.0.0",
+    "debug": "^4.1.0",
+    "is-type-of": "^1.2.1",
+    "semver": "^5.5.1",
+    "yargs": "^13.3.0",
+    "yargs-parser": "^13.1.2"
+  },
+  "devDependencies": {
+    "autod": "^3.0.1",
+    "coffee": "^5.1.0",
+    "egg-bin": "^4.17.0",
+    "egg-ci": "^1.19.0",
+    "eslint": "^5.6.1",
+    "eslint-config-egg": "^7.1.0",
+    "git-contributor": "^1.0.10",
+    "mm": "^2.4.1",
+    "rimraf": "^2.6.2",
+    "typescript": "^3.2.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/node-modules/common-bin.git"
+  },
+  "homepage": "https://github.com/node-modules/common-bin",
+  "author": "fengmk2 <fengmk2@gmail.com> (https://github.com/fengmk2)",
+  "license": "MIT",
+  "scripts": {
+    "contributor": "git-contributor",
+    "autod": "autod",
+    "clean": "rimraf coverage",
+    "lint": "eslint .",
+    "test": "npm run lint -- --fix && npm run test-local",
+    "test-local": "egg-bin test",
+    "cov": "egg-bin cov",
+    "ci": "npm run clean && npm run lint && egg-bin cov"
+  },
+  "engines": {
+    "node": ">= 6.0.0"
+  },
+  "files": [
+    "lib",
+    "index.d.ts",
+    "index.js"
+  ],
+  "types": "index.d.ts",
+  "ci": {
+    "version": "8, 10, 12, 14, 16",
+    "type": "github",
+    "license": {
+      "year": "2017",
+      "fullname": "node-modules and other contributors"
+    }
+  }
+}