initial commit

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+npm-debug.log
+tmp

.jshintrc

@@ -0,0 +1,14 @@
+{
+  "curly": true,
+  "eqeqeq": true,
+  "immed": true,
+  "latedef": true,
+  "newcap": true,
+  "noarg": true,
+  "sub": true,
+  "undef": true,
+  "boss": true,
+  "eqnull": true,
+  "node": true,
+  "quotmark": "single"
+}

Gruntfile.js

@@ -0,0 +1,32 @@
+/*
+ * grunt-run
+ * https://github.com/spenceralger/grunt-run
+ *
+ * Copyright (c) 2013 Spencer Alger
+ * Licensed under the MIT license.
+ */
+
+'use strict';
+
+module.exports = function(grunt) {
+
+  // Project configuration.
+  grunt.initConfig({
+    jshint: {
+      all: [
+        'Gruntfile.js',
+        'tasks/*.js'
+      ],
+      options: {
+        jshintrc: '.jshintrc',
+      },
+    }
+  });
+
+  // These plugins provide necessary tasks.
+  grunt.loadNpmTasks('grunt-contrib-jshint');
+
+  // By default, lint
+  grunt.registerTask('default', ['jshint']);
+
+};

LICENSE-MIT

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Spencer Alger
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,157 @@
+# grunt-run
+
+> Invite external commands into your grunt process with three tasks `run`, `wait` and `stop`.
+
+## Getting Started
+This plugin requires Grunt `~0.4.1`
+
+If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
+
+```shell
+npm install grunt-run --save-dev
+```
+
+Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
+
+```js
+grunt.loadNpmTasks('grunt-run');
+```
+
+## The "run" task
+
+### Overview
+In your project's Gruntfile, add a section named `run` to the data object passed into `grunt.initConfig()`.
+
+```js
+grunt.initConfig({
+  run: {
+    options: {
+      // Task-specific options go here.
+    },
+    your_target: {
+      cmd: 'executable',
+      args: [
+        'arg1',
+        'arg2'
+      ]
+    }
+  }
+})
+```
+
+### Src/files/etc
+
+Since this task doesn't operate on "files" it also doesn't use the standard src/files options. Instead, specify a `cmd` and `args` key to your test's config (see examples). `cmd` defaults to `"node"`.
+
+
+### Options
+
+#### options.wait
+Type: `Boolean`
+Default value: `true`
+
+Should this task wait until the script exits before finishing?
+
+#### options.ready
+Type: `RegExp`, `Number`, or `false`
+Default value: 1000
+
+If we are **not** waiting for the process to complete, then how do we know the process is ready?
+
+A RegExp will test the lines from StdOut and complete the task once the test succeeds, a Number will just set a timeout, and false will consider it ready as soon as it's started
+
+#### options.failOnError
+Type: `Boolean`
+Default value: `false`
+
+If the process outputs anything on stderr then the process will be killed. If wait is `true` it will cause the task to fail as well.
+
+### Usage Examples
+
+#### Default
+Want to just run some command line tool? With this config calling `grunt run:tool` will run that tool, and once it exits use an exit code of 0 to mean success and any other to mean failure.
+
+```js
+grunt.initConfig({
+  run: {
+    tool: {
+      cmd: 'some-bash-script',
+    }
+  }
+});
+
+grunt.loadNpmTasks('grunt-run');
+```
+
+#### `wait`ing
+In this example, we are starting a small server that will serve our mocha tests to a browser. We will then open that page in the browser and tell grunt to wait until the process is exited, which probablt won't happen so the process will just run until the user kills grunt with `ctrl + c`.
+
+```js
+grunt.initConfig({
+  run: {
+    integration_server: {
+      options: {
+        wait: false
+      },
+      // cmd: "node", // but that's the default
+      args: [
+        'text/integration_server.js'
+      ]
+    }
+  },
+  open: {
+    integration_suite: {
+      // https://github.com/jsoverson/grunt-open
+      path: 'http://localhost:8888',
+      app: 'Google Chrome'
+    }
+
+  }
+});
+
+grunt.loadNpmTasks('grunt-run');
+grunt.loadNpmTasks('grunt-open');
+
+grunt.registerTask('test', [
+  'run:integration_server',
+  'open:integration_tests',
+  'wait:integration_server'
+]);
+```
+
+#### `stop`ing
+We can do something similar using grunt-mocha to run the tests inside phantomjs, but instead of waiting for the process we will just stop it once mocha is done.
+
+```js
+grunt.initConfig({
+  run: {
+    integration_server: {
+      options: {
+        wait: false
+      },
+      args: [
+        'text/integration_server.js'
+      ]
+    }
+  },
+  mocha: {
+    integration_suite: {
+      // https://github.com/kmiyashiro/grunt-mocha
+      urls: 'http://localhost:8888',
+      app: 'Google Chrome'
+    }
+  }
+});
+
+grunt.loadNpmTasks('grunt-run');
+grunt.loadNpmTasks('grunt-mocha');
+
+grunt.registerTask('test', [
+  'run:integration_server',
+  'mocha:integration_suite',
+  'stop:integration_server'
+]);
+```
+
+## Contributing
+In lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code using [Grunt](http://gruntjs.com/).

package.json

@@ -0,0 +1,37 @@
+{
+  "name": "grunt-run",
+  "description": "Invite external commands into your grunt process with three tasks `run`, `wait` and `stop`.",
+  "version": "0.1.0",
+  "homepage": "https://github.com/spenceralger/grunt-run",
+  "author": {
+    "name": "Spencer Alger",
+    "email": "[email protected]"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/spenceralger/grunt-run.git"
+  },
+  "bugs": {
+    "url": "https://github.com/spenceralger/grunt-run/issues"
+  },
+  "licenses": [
+    {
+      "type": "MIT",
+      "url": "https://github.com/spenceralger/grunt-run/blob/master/LICENSE-MIT"
+    }
+  ],
+  "main": "Gruntfile.js",
+  "engines": {
+    "node": ">= 0.8.0"
+  },
+  "devDependencies": {
+    "grunt-contrib-jshint": "~0.7",
+    "grunt": "~0.4"
+  },
+  "peerDependencies": {
+    "grunt": "~0.4"
+  },
+  "keywords": [
+    "gruntplugin", "child_process", "run", "exec"
+  ]
+}

tasks/run.js

@@ -0,0 +1,107 @@
+/*
+ * grunt-run
+ * https://github.com/spenceralger/grunt-run
+ *
+ * Copyright (c) 2013 Spencer Alger
+ * Licensed under the MIT license.
+ */
+
+'use strict';
+
+module.exports = function(grunt) {
+
+  var runningProcs = [];
+  var _ = require('lodash');
+  var child_process = require('child_process');
+
+  process.on('exit', function () {
+    _.each(runningProcs, function (proc) {
+      proc.kill();
+    });
+  });
+
+  grunt.task.registerMultiTask('run', 'used to start external processes (like servers)', function () {
+    var self = this;
+    var name = this.target;
+    var opts = this.options({
+      wait: true,
+      failOnError: true,
+      ready: 1000
+    });
+
+    console.log(opts);
+
+    var proc = child_process.spawn(
+      self.data.cmd || 'node',
+      self.data.args,
+      {
+        stdio: ['ignore', 'pipe', 'pipe']
+      }
+    );
+
+    proc.stdout.on('data', grunt.log.write);
+
+    var done = this.async();
+    var timeoutId = null;
+
+    proc.stderr.on('data', function (chunk) {
+      grunt.log.error(chunk);
+      if (opts.failOnError) {
+        proc.kill();
+        done(new Error('Error output received'));
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+      }
+    });
+
+    proc.on('close', function () {
+      var i;
+      if ((i = runningProcs.indexOf(proc)) !== -1) {
+        runningProcs.splice(i, 1);
+      }
+      grunt.log.debug('Process ' + name + ' closed.');
+    });
+
+    if (opts.wait) {
+      proc.on('close', function (exitCode) {
+        done(!exitCode);
+      });
+    } else {
+      grunt.config.set('stop.' + name + '._pid', proc.pid);
+      grunt.config.set('wait.' + name + '._pid', proc.pid);
+      runningProcs.push(proc);
+      if (opts.ready instanceof RegExp) {
+        process.stdout.on('data', function (chunk) {
+          if (opts.ready.test(chunk)) {
+            done();
+          }
+        });
+      } else if (opts.ready) {
+        timeoutId = setTimeout(done, opts.ready);
+      } else {
+        process.nextTick(done);
+      }
+    }
+  });
+
+  grunt.task.registerMultiTask('stop', 'stop a process started with "run" ' +
+    '(only works for tasks that use wait:false)', function () {
+    var pid = this.data._pid;
+    child_process.kill(pid);
+  });
+
+  grunt.task.registerMultiTask('wait', 'wait for a process started with "run" to close ' +
+    '(only works for tasks that use wait:false)', function () {
+
+    var pid = this.data._pid;
+    var proc = _.find(runningProcs, { pid: pid });
+    if (proc) {
+      proc.on('close', this.async());
+    } else {
+      grunt.log.writeLn('process already closed');
+    }
+  });
+
+};