drudgeon v0.2.0

Roy: They have no respect for us up there. No respect whatsoever. We're all just drudgeons to them.

Moss: Yes. If there were such a thing as a drudgeon, that is what we would be to them.

IT Crowd, Episode 1.1 "Yesterday's Jam"

drudgeon

Drudgeon is state-machine-driven shell command runner that can alter the commands run based on platform. There is nothing fancy going on here, tell it what to do and then toss it aside like yesterday's jam.

It will:

• Run shell commands in order
• Determine command success based on a 0 exit code
• Stop running commands and reject the promise if a command fails
• Capture output from stdout & stderr
• Event stdout (via when's progress callback )

API

drudgeon( commandSet, config )

commandSet should be an object literal following the command set format explained below.

The optional config object current has the following three properties:

• platform - defaults to the result of os module's platform call
• relativePath - top-level path for all commands (default: process's working directory)
• inheritIO - causes child processes to pipe their IO to the parent's (default: false )

var drudgeon = require( 'drudgeon' );
var set = { ... } // your command set goes here
drudgeon( set )
	.progress( function( data ) {
		// data.step - the name of the step
		// data.stderr - data written to stderr
		// data.stdout - data written to stdout
	} )
	.then( function( output ) {
		// output is a hash of all data written to stdout or stderr keyed by step name
	} )
	.then( null, function( output ) {
		// output.failedStep will be the name of the step that failed
		// output is a hash of all data written to stdout or stderr keyed by step name
	} );

Events

Each step emits the following events:

• starting.stepName - emitted before the step is called
• finished.stepName - emitted after the step completes without error
• stepName.output - emitted for each write stdout receives from a step
• commands.complete - emitted when all steps have completed successfully
• commands.failed - emitted when a step fails with an error

Note: the output events will not be emitted if inheritIO was used.

Command Set

Steps are defined from a object literal that has a number of supported formats for defining how to execute a step.

A step consists of 3 primary pieces of information:

• a command
• arguments
• working path

There are two different "styles" for defining a step:

strings

"[workingPath]:[command] arg1 arg2 ..."

This style works best when the arguments you're providing do not contain spaces.

	step: "./workingDir/:node index.js"

hashes

Hashes separate the information into properties. This style works well when the arguments contain spaces.

	step: {
		cwd: './',
		cmd: 'node',
		args: [ 'index.js' ]
	}

Note: hash and string styles are not exclusive - you can use both in the same command set.

Adapting commands to support multiple platforms

Drudgeon provides a number of ways for adapting steps for specific platforms. The three most common platforms you will encounter are 'win32', 'darwin' and 'linux'. More often than not, steps will only differ for Windows. In those cases you can target Windows with win32 and the other two platforms with '*'.

filtering

You can attach a platform filter to any setting in order to specify that it only applies to that platform.

// string style
{
	stepOne: {
		win32: './src/:node.cmd index.js',
		'*': './src/:node index.js'
	},
	stepTwo: './spec/:gulp test'
}

// hash style - note, this allows a more targeted approach
{
	stepOne: {
		cwd: './src/',
		cmd: {
			win32: 'node.cmd',
			'*': 'node'
		},
		args: [ 'index.js' ]
	},
	stepTwo: {
		cwd: './spec/',
		cmd: 'gulp',
		args: [ 'test' ]
	}
}

revisions

You can provide a list of platform specific revisions to previous commands.

// string style
{
	stepOne: './src/:node index.js',
	stepTwo: './spec/:gulp test',
	_revisions: {
		win32: {
			stepOne: {
				cmd: 'node.cmd'
			}
		}
	}
}

// hash style
{
	stepOne: {
		cwd: './src/',
		cmd: 'node',
		args: [ 'index.js' ]
	},
	stepTwo: {
		cwd: './spec/',
		cmd: 'gulp',
		args: [ 'test' ]
	},
	_revisions: {
		win32: {
			stepOne: {
				cmd: 'node.cmd'
			}
		}
	}
}

platform subsets

There may be times when the set of commands you need to express for a platform is so different from the others that it should be defined entirely separate. In those cases, the set of commands should be under platforms.[platform]:

{
	platforms:
		win32: {
			command: { ... },
			...
		},
		'*': {
			command: { ... },
			...
		}
}