isabella232 / drudgeon

Drudgeon is state-machine-driven shell command runner for Node.js

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( [platform], commandSet, [relativePath] )

Platform defaults to the value returned from the os module's platform call. commandSet should be an object literal following the command set format explained below. The relativePath arguments sets a top-level relative path that all commands will run relative to (this defaults to the processes working directory).

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

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: { ... },
			...
		}
}