lub-command v1.0.1-alpha.0

lub-command

A base command class to help develop your lub-plugin based on yargs.

It's quit convenient to define your bin's version, help info, description and option description by extending this command class.

Install

npm install lub-command --save

Usage

Usage for developing lub-plugin

Make your subcommand's class extend lub-command, and export it in your plugin npm package's entry file. Do your biz logic in run method, support async and generator * run.

// lib/clone.js

"use strict";

const Command = require("lub-command");

class GitClone extends Command {
  // here lub-core will pass raw arguments in the running cli and config from .lubrc
  constructor(rawArgv, config) {
    // don't forget this line
    super(rawArgv, config);

    // define your command's usage and description info
    this.usage = "lub clone <repository> [directory]";

    // pass your options to yargs
    this.options = {
      depth: {
        type: "number",
        description:
          "Create a shallow clone with a history truncated to the specified number of commits"
      }
    };
  }

  get description(){
    return "Clone a repository into a new directory";
  }

  // run method has to be defined to do your biz logic here
  // supports generator `* run()` and promise `async run()`
  // arguments context and config will be passed
  async run(context, config) {
    if (config.quiet) {
      console.log("set quiet mode");
    }
    const [repository, directory] = context.argv._;
    console.log(
      "git clone %s to %s with depth %d",
      repository,
      directory,
      argv.depth
    );
  }
}

module.exports = GitClone;

// index.js => equals to package.main
'use strict';

const clone = require('./lib/clone')

module.exports = {
    clone
}

Usage for independent module

The implementation of subcommand class is the of For lub plugin developer.

But you need to run this subcommand by your self.

// bin/git-clone.js
#!/usr/bin/env node

"use strict";

const Clone = require("../lib/clone");

const gitClone = new Clone(process.argv.slice(2), { quiet: true });
gitClone.start();

API

Command

Method:

• start() - start your program, only use once in your bin file.
• run(context,config)
  • should implement this to provide command handler
  • 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/lub', foo: 'bar'}
    • rawArgv - the raw argv, [ "--foo=bar" ]
  • config is passed from .lubrc.js if used in lub-plugin
• showHelp() - print usage message to console.
• options= - a setter, shortcut for yargs.options
• usage= - a setter, shortcut for yargs.usage
• version= - a setter, set the version of you command

Properties:

• description - {String} a getter, shortcut for yargs.command(cmd, desc, [module]) only show this description when it's a sub command in help console
• yargs - {Object} yargs instance for advanced custom usage
• helper - {Object} helper instance exported from const { helper } = require('lub-command');

tips: lub-command will read version from your npm package's package.json

You can define options by set this.options

this.options = {
  baseDir: {
    alias: 'b',
    demandOption: true,
    description: 'the target directory',
    coerce: str => path.resolve(prcess.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 set this.version

this.version = 'v1.0.0';

You can define description by define description getter:

get description(){
  return 'this is description';
}

Helper

lub-command also provides some useful utils on helper when you develop your bin tool:

• 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
• * callFn(fn, args, thisArg) - call fn, support gernerator / async / normal function return promise

how to require:

const { helper } = require('lub-command');