[api docs] Started work on jitsu help commands.

lib/jitsu.js

@@ -81,11 +81,12 @@ jitsu.exec = function (command, callback) {
   }
 
   winston.info('Executing command ' + jitsu.commands.parse(command).splice(0,2).join(' ').magenta);
-  jitsu.commands.run(command, function (err) {
+  jitsu.commands.run(command, function (err, shallow) {
     if (err && !/403/.test(err.message)) {
       winston.error('Error running command ' + command.magenta);
       winston.error(err.message);
-      if (err.stack) {
+
+      if (err.stack && !shallow) {
         err.stack.split('\n').forEach(function (trace) {
           winston.error(trace);
         })

lib/jitsu/commands.js

@@ -1,14 +1,16 @@
 
 
-var jitsu = require('jitsu');
+var winston = require('winston'),
+    jitsu = require('jitsu');
 
 var commands = exports;
 
 // Setup the commands organized by resource
 commands.commands = {
   apps:      require('jitsu/commands/apps'),
   config:    require('jitsu/commands/config'),
-  snapshots: require('jitsu/commands/snapshots')
+  snapshots: require('jitsu/commands/snapshots'),
+  help:      require('jitsu/commands/help')
 };
 
 var requireAuth = ['apps', 'users', 'snapshots', 'logs'];
@@ -37,30 +39,60 @@ commands.run = function (command, callback) {
       action = parts.shift(),
       expected, resource;
 
+  //
+  // If we have been asked for `help` or `usage`
+  // about a particular resource, print the help 
+  // for that resource.
+  //
+  if (action === 'usage' || action === 'help') {
+    commands.commands.help.show(name);
+    return callback();
+  }
+
   if (!commands.commands[name]) {
-    return callback(new Error('Cannot run command on unknown resource: ' + name));
+    return callback(new Error('Cannot run command on unknown resource: ' + name), true);
   }
 
   resource = commands.commands[name];
   if (!resource[action]) {
-    return callback(new Error('Cannot run unknown action ' + action + ' on resource ' + name));
+    return callback(new Error('Cannot run unknown action ' + action + ' on resource ' + name), true);
   }
 
   //
-  // Append the callback to the arguments to pass the command,
-  // check the arguments length then execute the command.
+  // When the command completes, check for an error, and if 
+  // we are surpressing the err callstack (i.e. it is an **expected** error)
+  // then print the usage of the specified command.
   //
-  parts.push(callback);
-  expected = resource[action].length;
+  parts.push(function (err, shallow) {
+    if (err && shallow) {
+      winston.help('');
+      winston.help('Usage:'.bold);
+      resource[action].usage.forEach(function (line) {
+        winston.help(line);
+      });
+      winston.help('');
+    }
+
+    callback(err, shallow);
+  });
 
+  //
+  // Check the arguments length then execute the command.
+  //
+  expected = resource[action].length;
   if (parts.length > expected) {
-    return callback(new Error('Wrong number of arguments: ' + parts.length + ' for ' + expected))
+    return callback(new Error('Wrong number of arguments: ' + parts.length + ' for ' + expected), true)
   }
 
   function runCommand () {
     resource[action].apply(resource, parts);
   }
 
+  // 
+  // If this resource can only be accessed
+  // after authenticating with Nodejitsu, do so
+  // then run the specified command on the resource
+  //
   if (requireAuth.indexOf(name) !== -1) {
     return jitsu.auth(function (err) {
       if (err) {

lib/jitsu/commands/apps.js

@@ -11,6 +11,24 @@ var eyes = require('eyes'),
 
 var apps = exports;
 
+apps.usage = [
+  '`jitsu apps *` commands allow you to work with your',
+  'Applications on Nodejitsu. Valid commands are:',
+  '',
+  'jitsu apps create',
+  'jitsu apps list',
+  'jitsu apps view    <name>',
+  'jitsu apps update  <name>',
+  'jitsu apps destroy <name>',
+  'jitsu apps start   <name>',
+  'jitsu apps restart <name>',
+  'jitsu apps stop    <name>',
+  '',
+  'For commands that take a <name> parameter, if no parameter',
+  'is supplied, jitsu will attempt to read the package.json',
+  'from the current directory.'
+]
+
 //
 // ### function list (callback)
 // #### @name {string} **optional** Name of the application to create

lib/jitsu/commands/config.js

@@ -11,6 +11,16 @@ var jitsu = require('jitsu'),
 var config = exports,
     noDelete = ['root', 'remoteUri', 'userconfig', 'auth', 'tmproot', 'tar', 'gzipbin'];
 
+config.usage = [
+  '`jitsu config *` commands allow you to edit your',
+  'local jitsu configuration file. Valid commands are:',
+  '',
+  'jitsu config list',
+  'jitsu config set    <key> <value>',
+  'jitsu config get    <key>',
+  'jitsu config delete <key>',
+];
+
 //
 // ### function set (key, value, callback)
 // #### @key {string} Key to set in jitsu config.

lib/jitsu/commands/help.js

@@ -0,0 +1,46 @@
+/*
+ * help.js: Command related to jitsu help and usage
+ *
+ * (C) 2010, Nodejitsu Inc.
+ *
+ */
+
+var winston = require('winston'),
+    jitsu = require('jitsu');
+
+var help = exports;
+
+help.show = function (name, action) {
+  var usage, resource = jitsu.commands.commands[name];
+
+  if (action && !resource[action]) {
+    winston.error('No help for command ' + [name, action].join(' ').magenta);
+    return;
+  }
+
+  usage = action ? resource[action].usage : resource.usage;
+
+  if (!usage) {
+    winston.error('No help for command ' + [name, action].join(' ').magenta);
+    return;
+  }
+
+  winston.help('');
+  winston.help('Usage:'.bold);
+  usage.forEach(function (line) {
+    winston.help(line);
+  });
+  winston.help('');
+};
+
+['apps', 'snapshots', 'config'].forEach(function (resource) {
+  help[resource] = function (action, callback) {
+    if (!callback) {
+      callback = action;
+      action = null;
+    }
+
+    help.show(resource, action);
+    callback();
+  };
+});

lib/jitsu/commands/snapshots.js

@@ -10,6 +10,21 @@ var winston = require('winston'),
 
 var snapshots = exports;
 
+snapshots.usage = [
+  '`jitsu snapshots *` commands allow you to work with snapshots',
+  'for your Applications on Nodejitsu. Snapshots are images of your',
+  'Application\'s code that are deployed to the Nodejitsu Platform.',
+  'Valid commands are: ',
+  '',
+  'jitsu snapshots create',
+  'jitsu snapshots list    <name>',
+  'jitsu snapshots destroy <count>',
+  '',
+  'For commands that take a <name> parameter, if no parameter',
+  'is supplied, jitsu will attempt to read the package.json',
+  'from the current directory.'
+]
+
 //
 // ### function list (name, callback)
 // #### @name {string} **optional** Name of the application to create
@@ -29,7 +44,7 @@ snapshots.list = function (name, callback) {
   function executeList () {
     jitsu.snapshots.list(name, function (err, snapshots) {
       if (err) {
-        return callback(err);
+        return callback(err, true);
       }
 
       if (snapshots && snapshots.length > 0) {
@@ -57,6 +72,17 @@ snapshots.list = function (name, callback) {
   executeList();
 };
 
+//
+// Usage for `jitsu snapshots list [<name>]`
+//
+snapshots.list.usage = [
+  'Lists all snapshots associated with the application in the',
+  'current directory or the application with <name>, if supplied',
+  '',
+  'jitsu snapshots list',
+  'jitsu snapshots list <name>'
+];
+
 //
 // ### function create (name, callback)
 // #### @name {string} **optional** Name of the application to create

lib/jitsu/config.js

@@ -41,9 +41,10 @@ var log = config.log =  {
     prompt: 3,
     info: 4,
     data: 5,
-    warn: 6,
-    debug: 7,
-    error: 8
+    help: 6,
+    warn: 7,
+    debug: 8,
+    error: 9
   },
   colors: {
     silly: 'magenta',
@@ -52,6 +53,7 @@ var log = config.log =  {
     prompt: 'grey',
     info: 'green',
     data: 'cyan',
+    help: 'yellow',
     warn: 'yellow',
     debug: 'blue',
     error: 'red'