feat(plugin): support deprecating plugins

src/common.js

@@ -4,6 +4,7 @@
 
 var os = require('os');
 var fs = require('fs');
+var util = require('util');
 var glob = require('glob');
 var shell = require('..');
 
@@ -312,7 +313,7 @@ exports.randomFileName = randomFileName;
 // command-logging, and other nice things
 function wrap(cmd, fn, options) {
   options = options || {};
-  return function () {
+  var fun = function () {
     var retValue = null;
 
     state.currentCmd = cmd;
@@ -409,6 +410,11 @@ function wrap(cmd, fn, options) {
     state.currentCmd = 'shell.js';
     return retValue;
   };
+  if (options.deprecated) {
+    var msg = options.deprecated; // This is the deprecation message.
+    fun = util.deprecate(fun, msg);
+  }
+  return fun;
 } // wrap
 exports.wrap = wrap;
 
@@ -427,6 +433,7 @@ var DEFAULT_WRAP_OPTIONS = {
   pipeOnly: false,
   wrapOutput: true,
   unix: true,
+  deprecated: '',
 };
 
 // This is populated during plugin registration

test/plugin.js

@@ -165,3 +165,37 @@ test('Cannot overwrite an existing command', t => {
   }, 'Command `cat` already exists');
   t.is(shell.cat, oldCat);
 });
+
+test('Deprecated command', t => {
+  process.throwDeprecation = true;
+  const oldThrowDep = process.throwDeprecation;
+  try {
+    plugin.register('dep', function dep(opt, arg) { return arg; }, {
+      cmdOptions: null,
+      deprecated: 'Use the foo method instead',
+    });
+
+    t.throws(() => {
+      shell.dep('bar');
+    }, /Use the foo method instead/);
+  } finally {
+    process.throwDeprecation = oldThrowDep;
+  }
+});
+
+test('Deprecated command in pipe', t => {
+  process.throwDeprecation = true;
+  plugin.register('depPipe', function depPipe(opt, arg) { return arg; }, {
+    cmdOptions: null,
+    deprecated: 'Use the foo pipe instead',
+    canReceivePipe: true,
+  });
+  const oldThrowDep = process.throwDeprecation;
+  try {
+    t.throws(() => {
+      shell.cat('./package.json').depPipe('bar');
+    }, /Use the foo pipe instead/);
+  } finally {
+    process.throwDeprecation = oldThrowDep;
+  }
+});