Add boolean fatal option to exec() function (#961)

WesCossick · nfischer · commit 4e38240eda2f · 2019-10-01T23:43:54.000-07:00
This PR introduces a new boolean fatal option for the exec() function. Like the existing silent option, this new option allows you to override the global fatal configuration parameter on a per-command basis.
diff --git a/README.md b/README.md
@@ -308,6 +308,7 @@ Available options:
 
 + `async`: Asynchronous execution. If a callback is provided, it will be set to
   `true`, regardless of the passed value (default: `false`).
++ `fatal`: Exit upon error (default: `false`).
 + `silent`: Do not echo program output to console (default: `false`).
 + `encoding`: Character encoding to use. Affects the values returned to stdout and stderr, and
   what is written to stdout and stderr when not in silent mode (default: `'utf8'`).
diff --git a/src/common.js b/src/common.js
@@ -88,7 +88,7 @@ CommandError.prototype = Object.create(Error.prototype);
 CommandError.prototype.constructor = CommandError;
 exports.CommandError = CommandError; // visible for testing
 
-// Shows error message. Throws if config.fatal is true
+// Shows error message. Throws if fatal is true (defaults to config.fatal, overridable with options.fatal)
 function error(msg, _code, options) {
   // Validate input
   if (typeof msg !== 'string') throw new Error('msg must be a string');
@@ -98,6 +98,7 @@ function error(msg, _code, options) {
     code: 1,
     prefix: state.currentCmd + ': ',
     silent: false,
+    fatal: config.fatal,
   };
 
   if (typeof _code === 'number' && isObject(options)) {
@@ -118,7 +119,7 @@ function error(msg, _code, options) {
   state.error += logEntry;
 
   // Throw an error, or log the entry
-  if (config.fatal) throw new Error(logEntry);
+  if (options.fatal) throw new Error(logEntry);
   if (msg.length > 0 && !options.silent) log(logEntry);
 
   if (!options.continue) {
@@ -424,7 +425,7 @@ function wrap(cmd, fn, options) {
         e.name = 'ShellJSInternalError';
         throw e;
       }
-      if (config.fatal) throw e;
+      if (config.fatal || options.handlesFatalDynamically) throw e;
     }
 
     if (options.wrapOutput &&
@@ -450,6 +451,7 @@ var DEFAULT_WRAP_OPTIONS = {
   canReceivePipe: false,
   cmdOptions: null,
   globStart: 1,
+  handlesFatalDynamically: false,
   pipeOnly: false,
   wrapOutput: true,
   unix: true,
diff --git a/src/exec.js b/src/exec.js
@@ -12,13 +12,22 @@ common.register('exec', _exec, {
   unix: false,
   canReceivePipe: true,
   wrapOutput: false,
+  handlesFatalDynamically: true,
 });
 
 // We use this function to run `exec` synchronously while also providing realtime
 // output.
 function execSync(cmd, opts, pipe) {
   if (!common.config.execPath) {
-    common.error('Unable to find a path to the node binary. Please manually set config.execPath');
+    try {
+        common.error('Unable to find a path to the node binary. Please manually set config.execPath');
+    } catch (e) {
+      if (opts.fatal) {
+        throw e;
+      }
+
+      return;
+    }
   }
 
   var tempDir = _tempDir();
@@ -28,6 +37,7 @@ function execSync(cmd, opts, pipe) {
 
   opts = common.extend({
     silent: common.config.silent,
+    fatal: common.config.fatal, // TODO(nfischer): this and the line above are probably unnecessary
     cwd: _pwd().toString(),
     env: process.env,
     maxBuffer: DEFAULT_MAXBUFFER_SIZE,
@@ -99,7 +109,7 @@ function execSync(cmd, opts, pipe) {
     // Note: `silent` should be unconditionally true to avoid double-printing
     // the command's stderr, and to avoid printing any stderr when the user has
     // set `shell.config.silent`.
-    common.error(stderr, code, { continue: true, silent: true });
+    common.error(stderr, code, { continue: true, silent: true, fatal: opts.fatal });
   }
   var obj = common.ShellString(stdout, stderr, code);
   return obj;
@@ -109,6 +119,7 @@ function execSync(cmd, opts, pipe) {
 function execAsync(cmd, opts, pipe, callback) {
   opts = common.extend({
     silent: common.config.silent,
+    fatal: common.config.fatal, // TODO(nfischer): this and the line above are probably unnecessary
     cwd: _pwd().toString(),
     env: process.env,
     maxBuffer: DEFAULT_MAXBUFFER_SIZE,
@@ -146,6 +157,7 @@ function execAsync(cmd, opts, pipe, callback) {
 //@
 //@ + `async`: Asynchronous execution. If a callback is provided, it will be set to
 //@   `true`, regardless of the passed value (default: `false`).
+//@ + `fatal`: Exit upon error (default: `false`).
 //@ + `silent`: Do not echo program output to console (default: `false`).
 //@ + `encoding`: Character encoding to use. Affects the values returned to stdout and stderr, and
 //@   what is written to stdout and stderr when not in silent mode (default: `'utf8'`).
@@ -184,7 +196,6 @@ function execAsync(cmd, opts, pipe, callback) {
 //@ Guidelines](https://github.com/shelljs/shelljs/wiki/Security-guidelines).
 function _exec(command, options, callback) {
   options = options || {};
-  if (!command) common.error('must specify command');
 
   var pipe = common.readFromPipe();
 
@@ -201,9 +212,22 @@ function _exec(command, options, callback) {
 
   options = common.extend({
     silent: common.config.silent,
+    fatal: common.config.fatal,
     async: false,
   }, options);
 
+  if (!command) {
+    try {
+      common.error('must specify command');
+    } catch (e) {
+      if (options.fatal) {
+        throw e;
+      }
+
+      return;
+    }
+  }
+
   if (options.async) {
     return execAsync(command, options, pipe, callback);
   } else {
diff --git a/test/exec.js b/test/exec.js
@@ -45,6 +45,15 @@ test('config.fatal and unknown command', t => {
   shell.config.fatal = oldFatal;
 });
 
+test('options.fatal = true and unknown command', t => {
+  const oldFatal = shell.config.fatal;
+  shell.config.fatal = false;
+  t.throws(() => {
+    shell.exec('asdfasdf', { fatal: true }); // could not find command
+  }, /asdfasdf/); // name of command should be in error message
+  shell.config.fatal = oldFatal; // TODO(nfischer): this setting won't get reset if the assertion above fails
+});
+
 test('exec exits gracefully if we cannot find the execPath', t => {
   shell.config.execPath = null;
   shell.exec('echo foo');
@@ -193,6 +202,15 @@ test('encoding option works', t => {
   t.is(result.stderr.toString(), '');
 });
 
+test('options.fatal = false and unknown command', t => {
+  const oldFatal = shell.config.fatal;
+  shell.config.fatal = true;
+  const result = shell.exec('asdfasdf', { fatal: false }); // could not find command
+  shell.config.fatal = oldFatal;
+  t.truthy(shell.error());
+  t.truthy(result.code);
+});
+
 //
 // async
 //
