oh v0.2.1-2

oh

In-development PoC of a tiny, development and CI-friendly task-runner.

To do

• tests!
• autocomplete task names
• allow multiple manifests (oh.compile.js => oh compile.css, oh.test.js => oh test.app)

Features

• small, simple API
• verbose by default
• fails visibly then kills the process on error, so that any errors cannot go unnoticed e.g. on a CI

Why?

• make really just wants to make things, and can be too restrictive e.g. it's hard to pass args or use modules from npm
• npm scripts can be too terse
• gulp/grunt et al are complex and often rely on 3rd party plugins

Usage

Install oh: npm i -g oh or yarn global add oh.

Then create a task manifest called oh.js, for example this one:

// oh.js

module.exports = {
    __before() {
        this.log('this happens before the tasks start');
    },

    main() {
        return this.run('logOpts').then(() => this.run('other'));
    },

    other() {
        return this.run(['other2', 'ls']).then(() => this.log('ran others'));
    },

    other2() {
        return new Promise(resolve => {
            setTimeout(resolve, 2000);
        });
    },

    ls() {
        return this.exec('ls');
    },

    logOpts() {
        this.log(this.args);
    },

    __after() {
        this.log('this happens after the tasks end');
    }
};

Now you can run oh main, oh ls etc.

You can also run multiple tasks e.g. oh other other2. They will run in series.

Oh provides some options:

  -h, --help       output usage information            [boolean]
  -v, --version    output the version number           [boolean]
  -q, --quiet      only log error output from tasks    [boolean]
  --oh             path to an oh.js manifest            [string]

Any other arguments you provide are passed directly through to your tasks e.g.

> oh main --dev # this.args.dev === true
> oh logOpts --greeting 'hi there' # this.args.greeting === 'hi there'

API

Any function that you export from oh.js becomes a task.

The following helpers are available:

this.run(String|Array)

Run other tasks defined in oh.js. An array of task names will run in parallel.

Returns a promise that resolves once the task(s) completes.

this.exec(String)

Executes a string as a terminal command, using local binaries if they're available (like npm scripts).

Returns a promise that resolves once the command completes.

this.args

An object representing any options in the command, except h, help, v and version.

this.log(anything, anything)

Tell yourself something about whats going on.

this.info(anything, anything)

Tell yourself something about what you've done or should do now.

this.error(anything, anything)

Stop everything, with an explanation. As with all errors, this will kill the process to prevent errors going unnoticed.

Built-in tasks

Two optional setup/teardown-style tasks are available:

this.__before(function)

Do something before the tasks start e.g. check the version of node your running in, npm i etc.

this.__after(function)

Do something after the tasks end e.g. clean up artefacts, restore previous state etc.

Development

• yarn install
• yarn link to add the local binary to your path (you need yarn@^0.19.0 for link to work)
• only tried with Node 6 so far

Files

• oh.js task manifest – this is the file you'd expect to see in a project root
• index.js the application that runs the tasks in oh.js
• bin the script oh ... runs on the command line