fix(core): improve run-commands dx for ready-when (#6448)

Author: leosvelperez

docs/angular/api-workspace/executors/run-commands.md

@@ -106,14 +106,18 @@ that sets the `forwardAllArgs` option to `false` as shown below:
 
 ##### Custom **done** conditions
 
-Normally, `run-commands` considers the commands done when all of them have finished running. If you don't need to wait until they're all done, you can set a special string, that considers the command finished the moment the string appears in `stdout` or `stderr`:
+Normally, `run-commands` considers the commands done when all of them have finished running. If you don't need to wait until they're all done, you can set a special string that considers the commands finished the moment the string appears in `stdout` or `stderr`:
 
 ```json
 "finish-when-ready": {
     "builder": "@nrwl/workspace:run-commands",
     "options": {
-        "command": "echo 'READY' && sleep 5 && echo 'FINISHED'",
-        "readyWhen": "READY"
+        "commands": [
+            "sleep 5 && echo 'FINISHED'",
+            "echo 'READY'"
+        ],
+        "readyWhen": "READY",
+        "parallel": true
     }
 }
 ```
@@ -122,7 +126,7 @@ Normally, `run-commands` considers the commands done when all of them have finis
 nx run frontend:finish-when-ready
 ```
 
-The above command will finish immediately, instead of waiting for 5 seconds.
+The above commands will finish immediately, instead of waiting for 5 seconds.
 
 ##### Nx Affected
 
@@ -218,4 +222,4 @@ Run commands in parallel
 
 Type: `string`
 
-String to appear in stdout or stderr that indicates that the task is done. This option can only be used when parallel is set to true. If not specified, the task is done when all the child processes complete.
+String to appear in `stdout` or `stderr` that indicates that the task is done. This option can only be used when multiple commands are run and `parallel` is set to `true`. If not specified, the task is done when all the child processes complete.

docs/node/api-workspace/executors/run-commands.md

@@ -107,14 +107,18 @@ that sets the `forwardAllArgs` option to `false` as shown below:
 
 ##### Custom **done** conditions
 
-Normally, `run-commands` considers the commands done when all of them have finished running. If you don't need to wait until they're all done, you can set a special string, that considers the command finished the moment the string appears in `stdout` or `stderr`:
+Normally, `run-commands` considers the commands done when all of them have finished running. If you don't need to wait until they're all done, you can set a special string that considers the commands finished the moment the string appears in `stdout` or `stderr`:
 
 ```json
 "finish-when-ready": {
     "builder": "@nrwl/workspace:run-commands",
     "options": {
-        "command": "echo 'READY' && sleep 5 && echo 'FINISHED'",
-        "readyWhen": "READY"
+        "commands": [
+            "sleep 5 && echo 'FINISHED'",
+            "echo 'READY'"
+        ],
+        "readyWhen": "READY",
+        "parallel": true
     }
 }
 ```
@@ -123,7 +127,7 @@ Normally, `run-commands` considers the commands done when all of them have finis
 nx run frontend:finish-when-ready
 ```
 
-The above command will finish immediately, instead of waiting for 5 seconds.
+The above commands will finish immediately, instead of waiting for 5 seconds.
 
 ##### Nx Affected
 
@@ -219,4 +223,4 @@ Run commands in parallel
 
 Type: `string`
 
-String to appear in stdout or stderr that indicates that the task is done. This option can only be used when parallel is set to true. If not specified, the task is done when all the child processes complete.
+String to appear in `stdout` or `stderr` that indicates that the task is done. This option can only be used when multiple commands are run and `parallel` is set to `true`. If not specified, the task is done when all the child processes complete.

docs/react/api-workspace/executors/run-commands.md

@@ -107,14 +107,18 @@ that sets the `forwardAllArgs` option to `false` as shown below:
 
 ##### Custom **done** conditions
 
-Normally, `run-commands` considers the commands done when all of them have finished running. If you don't need to wait until they're all done, you can set a special string, that considers the command finished the moment the string appears in `stdout` or `stderr`:
+Normally, `run-commands` considers the commands done when all of them have finished running. If you don't need to wait until they're all done, you can set a special string that considers the commands finished the moment the string appears in `stdout` or `stderr`:
 
 ```json
 "finish-when-ready": {
     "builder": "@nrwl/workspace:run-commands",
     "options": {
-        "command": "echo 'READY' && sleep 5 && echo 'FINISHED'",
-        "readyWhen": "READY"
+        "commands": [
+            "sleep 5 && echo 'FINISHED'",
+            "echo 'READY'"
+        ],
+        "readyWhen": "READY",
+        "parallel": true
     }
 }
 ```
@@ -123,7 +127,7 @@ Normally, `run-commands` considers the commands done when all of them have finis
 nx run frontend:finish-when-ready
 ```
 
-The above command will finish immediately, instead of waiting for 5 seconds.
+The above commands will finish immediately, instead of waiting for 5 seconds.
 
 ##### Nx Affected
 
@@ -219,4 +223,4 @@ Run commands in parallel
 
 Type: `string`
 
-String to appear in stdout or stderr that indicates that the task is done. This option can only be used when parallel is set to true. If not specified, the task is done when all the child processes complete.
+String to appear in `stdout` or `stderr` that indicates that the task is done. This option can only be used when multiple commands are run and `parallel` is set to `true`. If not specified, the task is done when all the child processes complete.

packages/tao/src/shared/params.ts

@@ -51,6 +51,8 @@ export async function handleErrors(isVerbose: boolean, fn: Function) {
       logger.error('The generator workflow failed. See above.');
     } else if (err.message) {
       logger.error(err.message);
+    } else {
+      logger.error(err);
     }
     if (isVerbose && err.stack) {
       logger.info(err.stack);

packages/workspace/docs/run-commands-examples.md

@@ -98,14 +98,18 @@ that sets the `forwardAllArgs` option to `false` as shown below:
 
 ##### Custom **done** conditions
 
-Normally, `run-commands` considers the commands done when all of them have finished running. If you don't need to wait until they're all done, you can set a special string, that considers the command finished the moment the string appears in `stdout` or `stderr`:
+Normally, `run-commands` considers the commands done when all of them have finished running. If you don't need to wait until they're all done, you can set a special string that considers the commands finished the moment the string appears in `stdout` or `stderr`:
 
 ```json
 "finish-when-ready": {
     "builder": "@nrwl/workspace:run-commands",
     "options": {
-        "command": "echo 'READY' && sleep 5 && echo 'FINISHED'",
-        "readyWhen": "READY"
+        "commands": [
+            "sleep 5 && echo 'FINISHED'",
+            "echo 'READY'"
+        ],
+        "readyWhen": "READY",
+        "parallel": true
     }
 }
 ```
@@ -114,7 +118,7 @@ Normally, `run-commands` considers the commands done when all of them have finis
 <%= cli %> run frontend:finish-when-ready
 ```
 
-The above command will finish immediately, instead of waiting for 5 seconds.
+The above commands will finish immediately, instead of waiting for 5 seconds.
 
 ##### Nx Affected
 

packages/workspace/src/executors/run-commands/run-commands.impl.spec.ts

@@ -13,6 +13,10 @@ function readFile(f: string) {
 describe('Command Runner Builder', () => {
   const context = {} as any;
 
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
   it('should run one command', async () => {
     const f = fileSync().name;
     const result = await runCommands({ command: `echo 1 >> ${f}` }, context);
@@ -67,15 +71,20 @@ describe('Command Runner Builder', () => {
 
     await runCommands(
       {
-        commands: [{ command: 'echo' }],
+        commands: [{ command: 'echo' }, { command: 'echo foo' }],
         parallel: true,
         a: 123,
         b: 456,
       },
       context
     );
 
-    expect(exec).toHaveBeenCalledWith('echo --a=123 --b=456', {
+    expect(exec).toHaveBeenCalledTimes(2);
+    expect(exec).toHaveBeenNthCalledWith(1, 'echo --a=123 --b=456', {
+      maxBuffer: LARGE_BUFFER,
+      env: { ...process.env },
+    });
+    expect(exec).toHaveBeenNthCalledWith(2, 'echo foo --a=123 --b=456', {
       maxBuffer: LARGE_BUFFER,
       env: { ...process.env },
     });
@@ -86,15 +95,23 @@ describe('Command Runner Builder', () => {
 
     await runCommands(
       {
-        commands: [{ command: 'echo', forwardAllArgs: true }],
+        commands: [
+          { command: 'echo', forwardAllArgs: true },
+          { command: 'echo foo', forwardAllArgs: true },
+        ],
         parallel: true,
         a: 123,
         b: 456,
       },
       context
     );
 
-    expect(exec).toHaveBeenCalledWith('echo --a=123 --b=456', {
+    expect(exec).toHaveBeenCalledTimes(2);
+    expect(exec).toHaveBeenNthCalledWith(1, 'echo --a=123 --b=456', {
+      maxBuffer: LARGE_BUFFER,
+      env: { ...process.env },
+    });
+    expect(exec).toHaveBeenNthCalledWith(2, 'echo foo --a=123 --b=456', {
       maxBuffer: LARGE_BUFFER,
       env: { ...process.env },
     });
@@ -105,15 +122,23 @@ describe('Command Runner Builder', () => {
 
     await runCommands(
       {
-        commands: [{ command: 'echo', forwardAllArgs: false }],
+        commands: [
+          { command: 'echo', forwardAllArgs: false },
+          { command: 'echo foo', forwardAllArgs: false },
+        ],
         parallel: true,
         a: 123,
         b: 456,
       },
       context
     );
 
-    expect(exec).toHaveBeenCalledWith('echo', {
+    expect(exec).toHaveBeenCalledTimes(2);
+    expect(exec).toHaveBeenNthCalledWith(1, 'echo', {
+      maxBuffer: LARGE_BUFFER,
+      env: { ...process.env },
+    });
+    expect(exec).toHaveBeenNthCalledWith(2, 'echo foo', {
       maxBuffer: LARGE_BUFFER,
       env: { ...process.env },
     });
@@ -169,11 +194,41 @@ describe('Command Runner Builder', () => {
   });
 
   describe('readyWhen', () => {
+    it('should warn when command is specified instead of commands', async () => {
+      jest.spyOn(process.stderr, 'write');
+      await runCommands(
+        {
+          command: `echo 'Hello World'`,
+          readyWhen: 'READY',
+        },
+        context
+      );
+
+      expect(process.stderr.write).toHaveBeenCalledWith(
+        'Warning: "readyWhen" has no effect when a single command is run. The task will be done when the command process is completed. Ignoring.'
+      );
+    });
+
+    it('should warn when a single command is specified', async () => {
+      jest.spyOn(process.stderr, 'write');
+      await runCommands(
+        {
+          commands: [`echo 'Hello World'`],
+          readyWhen: 'READY',
+        },
+        context
+      );
+
+      expect(process.stderr.write).toHaveBeenCalledWith(
+        'Warning: "readyWhen" has no effect when a single command is run. The task will be done when the command process is completed. Ignoring.'
+      );
+    });
+
     it('should error when parallel = false', async () => {
       try {
         await runCommands(
           {
-            commands: [{ command: 'some command' }],
+            commands: [{ command: 'echo foo' }, { command: 'echo bar' }],
             parallel: false,
             readyWhen: 'READY',
           },
@@ -182,20 +237,16 @@ describe('Command Runner Builder', () => {
         fail('should throw');
       } catch (e) {
         expect(e.message).toEqual(
-          `ERROR: Bad builder config for @nrwl/run-commands - "readyWhen" can only be used when parallel=true`
+          `ERROR: Bad builder config for @nrwl/run-commands - "readyWhen" can only be used when parallel=true.`
         );
       }
     });
 
-    it('should return success true when the string specified is ready condition is found', async () => {
+    it('should return success true when the string specified as ready condition is found', async () => {
       const f = fileSync().name;
       const result = await runCommands(
         {
-          commands: [
-            {
-              command: `echo READY && sleep 0.1 && echo 1 >> ${f}`,
-            },
-          ],
+          commands: [`echo READY && sleep 0.1 && echo 1 >> ${f}`, `echo foo`],
           parallel: true,
           readyWhen: 'READY',
         },
@@ -231,17 +282,18 @@ describe('Command Runner Builder', () => {
       const exec = jest.spyOn(require('child_process'), 'exec');
       await runCommands(
         {
-          commands: [
-            {
-              command: `echo 'Hello World'`,
-            },
-          ],
+          commands: [`echo 'Hello World'`, `echo 'Hello Universe'`],
           parallel: true,
         },
         context
       );
 
-      expect(exec).toHaveBeenCalledWith(`echo 'Hello World'`, {
+      expect(exec).toHaveBeenCalledTimes(2);
+      expect(exec).toHaveBeenNthCalledWith(1, `echo 'Hello World'`, {
+        maxBuffer: LARGE_BUFFER,
+        env: { ...process.env },
+      });
+      expect(exec).toHaveBeenNthCalledWith(2, `echo 'Hello Universe'`, {
         maxBuffer: LARGE_BUFFER,
         env: { ...process.env },
       });
@@ -251,18 +303,19 @@ describe('Command Runner Builder', () => {
       const exec = jest.spyOn(require('child_process'), 'exec');
       await runCommands(
         {
-          commands: [
-            {
-              command: `echo 'Hello World'`,
-            },
-          ],
+          commands: [`echo 'Hello World'`, `echo 'Hello Universe'`],
           parallel: true,
           color: true,
         },
         context
       );
 
-      expect(exec).toHaveBeenCalledWith(`echo 'Hello World'`, {
+      expect(exec).toHaveBeenCalledTimes(2);
+      expect(exec).toHaveBeenNthCalledWith(1, `echo 'Hello World'`, {
+        maxBuffer: LARGE_BUFFER,
+        env: { ...process.env, FORCE_COLOR: `true` },
+      });
+      expect(exec).toHaveBeenNthCalledWith(2, `echo 'Hello Universe'`, {
         maxBuffer: LARGE_BUFFER,
         env: { ...process.env, FORCE_COLOR: `true` },
       });

packages/workspace/src/executors/run-commands/run-commands.impl.ts

@@ -71,9 +71,15 @@ export default async function (
   const normalized = normalizeOptions(options);
 
   if (options.readyWhen && !options.parallel) {
-    throw new Error(
-      'ERROR: Bad builder config for @nrwl/run-commands - "readyWhen" can only be used when parallel=true'
-    );
+    if (options.command || options.commands?.length === 1) {
+      process.stderr.write(
+        'Warning: "readyWhen" has no effect when a single command is run. The task will be done when the command process is completed. Ignoring.'
+      );
+    } else {
+      throw new Error(
+        'ERROR: Bad builder config for @nrwl/run-commands - "readyWhen" can only be used when parallel=true.'
+      );
+    }
   }
 
   try {
@@ -145,6 +151,9 @@ function normalizeOptions(
     options.commands = options.commands.map((c) =>
       typeof c === 'string' ? { command: c } : c
     );
+    if (options.commands.length === 1) {
+      options.parallel = false;
+    }
   }
   (options as NormalizedRunCommandsBuilderOptions).commands.forEach((c) => {
     c.command = transformCommand(

packages/workspace/src/executors/run-commands/schema.json

@@ -46,7 +46,7 @@
     },
     "readyWhen": {
       "type": "string",
-      "description": "String to appear in stdout or stderr that indicates that the task is done. This option can only be used when parallel is set to true. If not specified, the task is done when all the child processes complete."
+      "description": "String to appear in `stdout` or `stderr` that indicates that the task is done. This option can only be used when multiple commands are run and `parallel` is set to `true`. If not specified, the task is done when all the child processes complete."
     },
     "args": {
       "type": "string",