shell - deprecates the wrap_for_exec API (#85782)

Deprecates the function `wrap_for_exec` on shell plugins. This is to
simplify the API and remove unecessary components that should live
elsewhere or have a better and more flexible API.

changelogs/fragments/shell-wrap_for_exec_deprecation.yml

@@ -0,0 +1,5 @@
+deprecated_features:
+  - >-
+    Deprecated the shell plugin's ``wrap_for_exec`` function. This API is not used in Ansible or any known collection
+    and is being removed to simplify the plugin API. Plugin authors should wrap their command to execute within an
+    explicit shell or other known executable.

lib/ansible/plugins/action/script.py

@@ -139,8 +139,6 @@ class ActionModule(ActionBase):
             else:
                 script_cmd = ' '.join([env_string, target_command])
 
-            script_cmd = self._connection._shell.wrap_for_exec(script_cmd)
-
             exec_data = None
             # PowerShell runs the script in a special wrapper to enable things
             # like become and environment args
@@ -149,7 +147,7 @@ class ActionModule(ActionBase):
                 pc = self._task
                 exec_data = ps_manifest._create_powershell_wrapper(
                     name=f"ansible.builtin.script.{pathlib.Path(source).stem}",
-                    module_data=to_bytes(script_cmd),
+                    module_data=to_bytes(f"& {script_cmd}; exit $LASTEXITCODE"),
                     module_path=source,
                     module_args={},
                     environment=env_dict,

lib/ansible/plugins/shell/__init__.py

@@ -27,6 +27,9 @@ import time
 from ansible.errors import AnsibleError
 from ansible.module_utils.common.text.converters import to_native
 from ansible.plugins import AnsiblePlugin
+from ansible.utils.display import Display
+
+display = Display()
 
 _USER_HOME_PATH_RE = re.compile(r'^~[_.A-Za-z0-9][-_.A-Za-z0-9]*$')
 
@@ -269,6 +272,11 @@ class ShellBase(AnsiblePlugin):
 
     def wrap_for_exec(self, cmd):
         """wrap script execution with any necessary decoration (eg '&' for quoted powershell script paths)"""
+        display.deprecated(
+            msg='The Shell.wrap_for_exec method is deprecated.',
+            help_text="Contact plugin author to update their plugin to not use this method.",
+            version='2.24',
+        )
         return cmd
 
     def quote(self, cmd):

lib/ansible/plugins/shell/powershell.py

@@ -428,6 +428,7 @@ class ShellModule(ShellBase):
         return self._encode_script(script, preserve_rc=False)
 
     def wrap_for_exec(self, cmd):
+        super().wrap_for_exec(cmd)
         return '& %s; exit $LASTEXITCODE' % cmd
 
     def _unquote(self, value):