feat(core): allow {args} to be fully interpolated in run-commands (#31824)

## Current Behavior
Currently, there is no way for a target using `run-commands` to define
where in the command args are attached.
This is problematic in some tooling cases where args positional location
matters

## Expected Behavior
Placing `{args}` into the command should allow for interpolation of any
and all args provided.
Therefore commands can be written such as `docker run {args} imageRef`

Author: Coly010

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

@@ -11,8 +11,14 @@ function normalize(p: string) {
   return p.startsWith('/private') ? p.substring(8) : p;
 }
 
-function readFile(f: string) {
-  return readFileSync(f).toString().replace(/\s/g, '');
+function readFile(
+  f: string,
+  { preserveWhitespace }: { preserveWhitespace: boolean } = {
+    preserveWhitespace: false,
+  }
+) {
+  const fileContents = readFileSync(f).toString();
+  return preserveWhitespace ? fileContents : fileContents.replace(/\s/g, '');
 }
 
 describe('Run Commands', () => {
@@ -222,6 +228,21 @@ describe('Run Commands', () => {
     }
   );
 
+  it('should interpolate {args} to contain all provided args', async () => {
+    const f = fileSync().name;
+    const result = await runCommands(
+      {
+        command: `echo {args} >> ${f}`,
+        __unparsed__: [`--publish 8080:80`, `--expose 80`],
+      },
+      context
+    );
+    expect(result).toEqual(expect.objectContaining({ success: true }));
+    expect(readFile(f, { preserveWhitespace: true }).trim()).toEqual(
+      `--publish 8080:80 --expose 80`
+    );
+  });
+
   it('should run commands serially', async () => {
     const f = fileSync().name;
     let result = await runCommands(

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

@@ -231,23 +231,28 @@ export function interpolateArgsIntoCommand(
   >,
   forwardAllArgs: boolean
 ): string {
+  if (command.indexOf('{args.') > -1 && command.indexOf('{args}') > -1) {
+    throw new Error(
+      'Command should not contain both {args} and {args.*} values. Please choose one to use.'
+    );
+  }
   if (command.indexOf('{args.') > -1) {
     const regex = /{args\.([^}]+)}/g;
     return command.replace(regex, (_, group: string) =>
       opts.parsedArgs[group] !== undefined ? opts.parsedArgs[group] : ''
     );
+  } else if (command.indexOf('{args}') > -1) {
+    const regex = /{args}/g;
+    const args = [
+      ...unknownOptionsToArgsArray(opts),
+      ...unparsedOptionsToArgsArray(opts),
+    ];
+    const argsString = `${args.join(' ')} ${opts.args ?? ''}`;
+    return command.replace(regex, argsString);
   } else if (forwardAllArgs) {
     let args = '';
     if (Object.keys(opts.unknownOptions ?? {}).length > 0) {
-      const unknownOptionsArgs = Object.keys(opts.unknownOptions)
-        .filter(
-          (k) =>
-            typeof opts.unknownOptions[k] !== 'object' &&
-            opts.parsedArgs[k] === opts.unknownOptions[k]
-        )
-        .map((k) => `--${k}=${opts.unknownOptions[k]}`)
-        .map(wrapArgIntoQuotesIfNeeded)
-        .join(' ');
+      const unknownOptionsArgs = unknownOptionsToArgsArray(opts).join(' ');
       if (unknownOptionsArgs) {
         args += ` ${unknownOptionsArgs}`;
       }
@@ -256,14 +261,9 @@ export function interpolateArgsIntoCommand(
       args += ` ${opts.args}`;
     }
     if (opts.__unparsed__?.length > 0) {
-      const filteredParsedOptions = filterPropKeysFromUnParsedOptions(
-        opts.__unparsed__,
-        opts.parsedArgs
-      );
+      const filteredParsedOptions = unparsedOptionsToArgsArray(opts);
       if (filteredParsedOptions.length > 0) {
-        args += ` ${filteredParsedOptions
-          .map(wrapArgIntoQuotesIfNeeded)
-          .join(' ')}`;
+        args += ` ${filteredParsedOptions.join(' ')}`;
       }
     }
     return `${command}${args}`;
@@ -272,6 +272,46 @@ export function interpolateArgsIntoCommand(
   }
 }
 
+function unknownOptionsToArgsArray(
+  opts: Pick<
+    NormalizedRunCommandsOptions,
+    | 'args'
+    | 'parsedArgs'
+    | '__unparsed__'
+    | 'unknownOptions'
+    | 'unparsedCommandArgs'
+  >
+) {
+  return Object.keys(opts.unknownOptions ?? {})
+    .filter(
+      (k) =>
+        typeof opts.unknownOptions[k] !== 'object' &&
+        opts.parsedArgs[k] === opts.unknownOptions[k]
+    )
+    .map((k) => `--${k}=${opts.unknownOptions[k]}`)
+    .map(wrapArgIntoQuotesIfNeeded);
+}
+
+function unparsedOptionsToArgsArray(
+  opts: Pick<
+    NormalizedRunCommandsOptions,
+    | 'args'
+    | 'parsedArgs'
+    | '__unparsed__'
+    | 'unknownOptions'
+    | 'unparsedCommandArgs'
+  >
+) {
+  const filteredParsedOptions = filterPropKeysFromUnParsedOptions(
+    opts.__unparsed__,
+    opts.parsedArgs
+  );
+  if (filteredParsedOptions.length > 0) {
+    return filteredParsedOptions.map(wrapArgIntoQuotesIfNeeded);
+  }
+  return [];
+}
+
 function parseArgs(
   unparsedCommandArgs: { [k: string]: string },
   unknownOptions: { [k: string]: string },