Code Monkey home page Code Monkey logo

common-bin's Introduction

common-bin

NPM version Node.js CI Test coverage Known Vulnerabilities npm download

Abstraction bin tool wrap yargs, to provide more convenient usage, support async / await style.


Install

$ 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 sub class to do that.

Example: Write your own git command

This example will show you how to create a new my-git tool.

test/fixtures/my-git
├── bin
│   └── my-git.js
├── command
│   ├── remote
│   │   ├── add.js
│   │   └── remove.js
│   ├── clone.js
│   └── remote.js
├── index.js
└── package.json
#!/usr/bin/env node

'use strict';

const Command = require('..');
new Command().start();

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.

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;
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',
      },
    };
  }

  async 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

$ 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:

  • async start() - start your program, only use once in your bin file.
  • async 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

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:

get version() {
  return 'v1.0.0';
}

Helper

  • async forkNode(modulePath, args, opt) - fork child process, wrap with promise and gracefull exit
  • async spawn(cmd, args, opt) - spawn a new process, wrap with promise and gracefull exit
  • async npmInstall(npmCli, name, cwd) - install node modules, wrap with promise
  • async 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

// 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().

const Command = require('common-bin');
class MainCommand extends Command {
  constructor(rawArgv) {
    super(rawArgv);
    this.options = {
      baseDir: {
        description: 'target directory',
      },
    };
  }

  async 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.

// 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'));
  }

  async 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',
      },
    };

  }

  async 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 for more detail.

Async Support

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 for more detail.

Bash-Completions

$ # 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

Migrating from v1 to v3

bin

  • run method is not longer exist.
// 1.x
const run = require('common-bin').run;
run(require('../lib/my_program'));

// 3.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.
// 1.x
this.addCommand('test', path.join(__dirname, 'test_command.js'));

// 3.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.
  • async 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
// 1.x
class TestCommand extends Command {
  * run(cwd, args) {
    console.log('run mocha test at %s with %j', cwd, args);
  }
}

// 3.x
class TestCommand extends Command {
  constructor() {
    super();
    // my-bin test --require=co-mocha
    this.options = {
      require: {
        description: 'require module name',
      },
    };
  }

  async 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

Contributors


atian25


fengmk2


popomore


dead-horse


whxaxes


DiamondYuan


tenpend


hacke2


liuqipeng417


Jarvis2018

This project follows the git-contributor spec, auto updated at Sat Jun 04 2022 00:31:29 GMT+0800.

common-bin's People

Contributors

atian25 avatar dead-horse avatar diamondyuan avatar fengmk2 avatar geekdada avatar hacke2 avatar jarvis2018 avatar liuqipeng417 avatar popomore avatar semantic-release-bot avatar tenpend avatar whxaxes avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

common-bin's Issues

argv获取传入的参数npm运行取不到,yarn可以

command constructor

constructor (rawArgv) {
    super(rawArgv)
    this.options = {
      lib: {
        type: 'boolean',
        default: false,
        description: 'whether library mode'
      }
    }
  }

scripts

"start": "npm run command serve --lib",
"start": "yarn run command serve --lib", // when use yarn
"command": "node ../../bin/command.js"

result

npm(the lib argument is false)

{ _: [],
  lib: false,
  '$0': '..\\..\\bin\\command.js',
  help: undefined,
  h: undefined,
  version: undefined,
  v: undefined }

yarn(this lib argument is true)

{ _: [],
  lib: true,
  '$0': '..\\..\\bin\\command.js',
  help: undefined,
  h: undefined,
  version: undefined,
  v: undefined }

Are there some way to disable some command ?

const Command = require('common-bin')

class SubBin extends Command {
  constructor(args) {
    super(args)

    // For example load some commander
    this.load('path/to/command(include test, dev, cov)')
  }
}

class MyBin extends SubBin {
  constructor(args) {
    super(args)

    this.load('path/to/mycommand(include run)')
  }
}

module.exports = MyBin

So, My question is how can I disable some SubBin Command

问题就是我想仅仅继承于 SubBin 的一部分命令,但是其他的我又不想要,或者不想要在 help 里面显示出来,有没有提供 disable command 的接口?

Does not support typescript commonjs module

tsconfig.json

{
  "compilerOptions": {
    "module": "commonjs",
    "outDir": "./lib",
    "target": "es2015",
    "moduleResolution": "node",
    "strict": true,
    "sourceMap": true,
    "removeComments": true,
    "importHelpers": true,
    "noEmitOnError": false,
    "noImplicitAny": false,
    "skipLibCheck": true,
    "declaration": true,
  },
  "exclude": [
    "node_modules",
    "lib"
  ],
  "include": [
    "./src/**/*"
  ]
}

If use es module will throw a error.

import * as Command from 'common-bin';

export default class CheckCommand extends Command {
  constructor(rawArgv: string[]) {
    super(rawArgv);
    this.yargs.usage('check me');
  }

  run(context: Command.Context) {
    
  }

  get description(): string {
    return 'Clone a repository into a new directory';
  }
}

The error:

AssertionError [ERR_ASSERTION]: command class should be sub class of common-bin
    at MainCommand.add (/Users/hacke2/projj/gitlab.alipay-inc.com/xinglong.wangwxl/vscode-extension-scan/node_modules/[email protected]@common-bin/lib/command.js:109:7)
    at MainCommand.load (/Users/hacke2/projj/gitlab.alipay-inc.com/xinglong.wangwxl/vscode-extension-scan/node_modules/[email protected]@common-bin/lib/command.js:86:14)
    at new MainCommand (/Users/hacke2/projj/gitlab.alipay-inc.com/xinglong.wangwxl/vscode-extension-scan/lib/index.js:9:14)
    at Object.<anonymous> (/Users/hacke2/projj/gitlab.alipay-inc.com/xinglong.wangwxl/vscode-extension-scan/lib/bin/vc.js:5:1)
    at Module._compile (internal/modules/cjs/loader.js:721:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:732:10)
    at Module.load (internal/modules/cjs/loader.js:620:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:560:12)
    at Function.Module._load (internal/modules/cjs/loader.js:552:3)
    at Function.Module.runMain (internal/modules/cjs/loader.js:774:12)

git clone undefined to undefined with depth NaN

I tried to run the following example of the test/fixtures/my-git ,I run it in local:

-- cd common-bin/test/fixtures/my-git

-- npm run my-git clone gh://node-modules/common-bin dist --depth=1

I get something like this:

{ _: [ 'gh://node-modules/common-bin', 'dist' ],
  '$0': 'bin/my-git.js',
  help: undefined,
  h: undefined,
  version: undefined,
  v: undefined }
git clone undefined to undefined with depth NaN

and I want to know why this is not consistent with what I expected ?

posibility of a 2.9.1 release with less strict yargs version dependency

Hi, @atian25 @fengmk2, there is a vulnerability introduced by package ** [email protected]**:

Issue Description

I noticed that a vulnerability is introduced in [email protected]:
Vulnerability CVE-2020-7608 affects package yargs-parser (versions:>5.0.0-security.0 <5.0.1,>=6.0.0 <13.1.2,>=14.0.0 <15.0.1,>=16.0.0 <18.1.1): https://snyk.io/vuln/SNYK-JS-YARGSPARSER-560381
The above vulnerable package is referenced by [email protected] via:
[email protected][email protected][email protected]

Since [email protected] (36,523 downloads per week) is referenced by 68 downstream projects (e.g., egg-scripts 2.14.0 (latest version), egg-bin 4.16.4 (latest version), surgio 2.9.1 (latest version), cabloy 4.11.16 (latest version), midway-bin 1.20.3 (latest version)), the vulnerability CVE-2020-7608 can be propagated into these downstream projects and expose security threats to them via the following package dependency paths:
(1)[email protected][email protected][email protected][email protected][email protected]
(2)[email protected][email protected][email protected][email protected][email protected]
......

If [email protected] removes the vulnerable package from the above version, then its fixed version can help downstream users decrease their pain.

Given the large number of downstream users, could you help update your package to remove the vulnerability from [email protected] ?

Fixing suggestions

In [email protected], maybe you can kindly try to perform the following upgrade :
yargs ^12.0.2 ➔ ^13.1.0;

Note:
[email protected](>=13.1.0 <14.1.0) directly depends on [email protected] which has fixed the vulnerability CVE-2020-7608.

Thank you for your attention to this issue and welcome to share other ways to resolve the issue.^_^

Refactor RFC

  • Node.js 14.x+
  • update deps
  • remove generator function
  • forkNode -> execa
  • use clet instead of coffee
  • use jest instead of egg-bin / mocha

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.