exec subcommand

docs/changelog-fragments.d/526.feature.md

@@ -0,0 +1,9 @@
+Added the ability to run ad-hoc commands directly within an execution
+environment using mode `stdout`.
+
+Here is an example invocation:
+```bash
+ansible-navigator exec --mode stdout
+```
+
+-- by {user}`cidrblock`

src/ansible_navigator/actions/_actions.py

@@ -3,6 +3,7 @@
 
 import functools
 import importlib
+import logging
 import re
 from collections import namedtuple
 
@@ -19,6 +20,8 @@
     import importlib_resources as resources  # type: ignore[import, no-redef]
 
 
+logger = logging.getLogger(__name__)
+
 # Basic structure for storing information about one action
 ActionT = namedtuple("ActionT", ("name", "cls", "kegex"))
 
@@ -95,7 +98,12 @@ def run_interactive(package: str, action: str, *args: Any, **_kwargs: Any) -> An
     """Call the given action's run"""
     action_cls = get(package, action)
     app, interaction = args
-    return action_cls(app.args).run(app=app, interaction=interaction)
+    app_action = action_cls(app.args)
+    supports_interactive = hasattr(app_action, "run")
+    if not supports_interactive:
+        logger.error("Subcommand '%s' does not support mode interactive", action)
+    run_action = app_action.run if supports_interactive else app_action.no_interactive_mode
+    return run_action(app=app, interaction=interaction)
 
 
 def run_interactive_factory(package: str) -> Callable:

src/ansible_navigator/actions/exec.py

@@ -0,0 +1,116 @@
+"""Run the :exec subcommand."""
+import os
+import shlex
+
+from typing import List
+from typing import Optional
+from typing import Tuple
+from typing import Union
+
+from . import _actions as actions
+from ..app import App
+from ..configuration_subsystem import ApplicationConfiguration
+from ..configuration_subsystem.definitions import Constants
+from ..runner import Command
+
+GeneratedCommand = Tuple[str, Optional[List[str]]]
+
+
+def _generate_command(exec_command: str, exec_shell: bool) -> GeneratedCommand:
+    """Generate the command and args.
+
+    :param exec_command: The command to run
+    :param exec_shell: Should the command be wrapped in a shell
+    :returns: The command and any pass through arguments
+    """
+    pass_through_args = None
+    if exec_shell and exec_command:
+        command = "/bin/bash"
+        pass_through_args = ["-c", exec_command]
+    else:
+        parts = shlex.split(exec_command)
+        command = parts[0]
+        if len(parts) > 1:
+            pass_through_args = parts[1:]
+    return (command, pass_through_args)
+
+
+@actions.register
+class Action(App):
+    """Run the :exec subcommand."""
+
+    # pylint: disable=too-few-public-methods
+
+    KEGEX = "^e(?:xec)?$"
+
+    def __init__(self, args: ApplicationConfiguration):
+        """Initialize the action.
+
+        :param args: The current application configuration.
+        """
+        super().__init__(args=args, logger_name=__name__, name="exec")
+
+    def run_stdout(self) -> Union[None, int]:
+        """Run in mode stdout.
+
+        :returns: The return code or None
+        """
+        self._logger.debug("exec requested in stdout mode")
+        response = self._run_runner()
+        if response:
+            _, _, ret_code = response
+            return ret_code
+        return None
+
+    def _run_runner(self) -> Optional[Tuple]:
+        # pylint: disable=too-many-branches
+        # pylint: disable=too-many-statements
+        """Spin up runner.
+
+        :return: The stdout, stderr and return code from runner
+        """
+        if isinstance(self._args.set_environment_variable, dict):
+            envvars_to_set = self._args.set_environment_variable.copy()
+        elif isinstance(self._args.set_environment_variable, Constants):
+            envvars_to_set = {}
+        else:
+            log_message = (
+                "The setting 'set_environment_variable' was neither a dictionary"
+                " or Constants, please raise an issue. No environment variables will be set."
+            )
+            self._logger.error(
+                "%s The current value was found to be '%s'",
+                log_message,
+                self._args.set_environment_variable,
+            )
+        envvars_to_set = {}
+
+        if self._args.display_color is False:
+            envvars_to_set["ANSIBLE_NOCOLOR"] = "1"
+
+        kwargs = {
+            "container_engine": self._args.container_engine,
+            "host_cwd": os.getcwd(),
+            "execution_environment_image": self._args.execution_environment_image,
+            "execution_environment": self._args.execution_environment,
+            "navigator_mode": self._args.mode,
+            "pass_environment_variable": self._args.pass_environment_variable,
+            "set_environment_variable": envvars_to_set,
+            "timeout": self._args.ansible_runner_timeout,
+        }
+
+        if isinstance(self._args.execution_environment_volume_mounts, list):
+            kwargs["container_volume_mounts"] = self._args.execution_environment_volume_mounts
+
+        if isinstance(self._args.container_options, list):
+            kwargs["container_options"] = self._args.container_options
+
+        command, pass_through_args = _generate_command(
+            exec_command=self._args.exec_command,
+            exec_shell=self._args.exec_shell,
+        )
+        if isinstance(pass_through_args, list):
+            kwargs["cmdline"] = pass_through_args
+
+        runner = Command(executable_cmd=command, **kwargs)
+        return runner.run()

src/ansible_navigator/app.py

@@ -20,6 +20,7 @@
 
 from .ui_framework import Interaction
 from .ui_framework import ui
+from .ui_framework import warning_notification
 
 from .utils import LogMessage
 from .utils import ExitMessage
@@ -83,6 +84,19 @@ def app(self) -> AppPublic:
             )
         raise AttributeError("app passed without args initialized")
 
+    def no_interactive_mode(self, interaction: Interaction, app: AppPublic) -> None:
+        # pylint: disable=unused-argument
+        """Show a warning notification that the user interactive mode is not supported."""
+        warning = warning_notification(
+            messages=[
+                f"The '{self._name}' subcommand is not available while using interactive mode.",
+                "[HINT] Start an additional instance of ansible-navigator"
+                + " in a new terminal with mode 'stdout'.",
+                f"      e.g. 'ansible-navigator {self._name} --mode stdout",
+            ]
+        )
+        interaction.ui.show(warning)
+
     @staticmethod
     def _copy_args(args: ApplicationConfiguration) -> ApplicationConfiguration:
         """Deepcopy the args.

src/ansible_navigator/configuration_subsystem/navigator_configuration.py

@@ -116,6 +116,16 @@ class Internals(SimpleNamespace):
             " 'ansible-navigator doc --help-doc --mode stdout'"
         ),
     ),
+    SubCommand(
+        name="exec",
+        description="Run a command within an execution environment",
+        epilog=(
+            "Note: During development, it may become necessary to interact"
+            " directly with the execution environment to review and confirm"
+            " its build and behavior. All navigator settings will be applied"
+            " when starting the execution environment."
+        ),
+    ),
     SubCommand(
         name="images",
         description="Explore execution environment images",
@@ -246,6 +256,23 @@ class Internals(SimpleNamespace):
             short_description="Specify if the editor is console based",
             value=EntryValue(default=True),
         ),
+        Entry(
+            name="exec_command",
+            cli_parameters=CliParameters(short="--excmd"),
+            settings_file_path_override="exec.command",
+            short_description="Specify the command to run within the execution environment",
+            subcommands=["exec"],
+            value=EntryValue(default="/bin/bash"),
+        ),
+        Entry(
+            name="exec_shell",
+            choices=[True, False],
+            cli_parameters=CliParameters(short="--exshell"),
+            settings_file_path_override="exec.shell",
+            short_description="Specify the exec command should be run in a shell.",
+            subcommands=["exec"],
+            value=EntryValue(default=True),
+        ),
         Entry(
             name="execution_environment",
             choices=[True, False],

src/ansible_navigator/configuration_subsystem/navigator_post_processor.py

@@ -208,6 +208,16 @@ def execution_environment(self, entry, config) -> PostProcessorReturn:
             new_messages, new_exit_messages = check_for_ansible()
             messages.extend(new_messages)
             exit_messages.extend(new_exit_messages)
+
+            if config.app == "exec":
+                exit_msg = "The 'exec' subcommand requires execution environment support."
+                exit_messages.append(ExitMessage(message=exit_msg))
+                hint = (
+                    f"Try again with '{entry.cli_parameters.short} true'"
+                    " to enable the use of an execution environment."
+                )
+                exit_messages.append(ExitMessage(message=hint, prefix=ExitPrefix.HINT))
+
         return messages, exit_messages
 
     @staticmethod
@@ -310,6 +320,17 @@ def container_options(entry: Entry, config: ApplicationConfiguration) -> PostPro
             entry.value.current = flatten_list(entry.value.current)
         return messages, exit_messages
 
+    @_post_processor
+    def exec_shell(self, entry: Entry, config: ApplicationConfiguration) -> PostProcessorReturn:
+        # pylint: disable=unused-argument
+        """Post process ``exec_shell``.
+
+        :param entry: The current settings entry
+        :param config: The full application configuration
+        :return: An instance of the standard post process return object
+        """
+        return self._true_or_false(entry, config)
+
     @_post_processor
     def help_config(self, entry: Entry, config: ApplicationConfiguration) -> PostProcessorReturn:
         # pylint: disable=unused-argument

tests/fixtures/integration/actions/exec/ansible-navigator.yaml

@@ -0,0 +1,4 @@
+ansible-navigator:
+  exec:
+    command: echo test_data_from_config
+    shell: False

tests/fixtures/integration/actions/exec/test_stdout_config_cli.py/test/0.json

@@ -0,0 +1,19 @@
+{
+    "name": "test[exec echo with ee  clear && ansible-navigator exec --excmd 'echo test_data_from_cli' --ee True --ll debug --mode stdout]",
+    "index": 0,
+    "comment": "exec echo with ee",
+    "additional_information": {
+        "look_fors": [
+            "bash",
+            "test_data_from_cli"
+        ],
+        "look_nots": [
+            "ERROR"
+        ],
+        "compared_fixture": false
+    },
+    "output": [
+        "test_data_from_cli",
+        "(venv) bash-5.1$"
+    ]
+}

tests/fixtures/integration/actions/exec/test_stdout_config_cli.py/test/1.json

@@ -0,0 +1,23 @@
+{
+    "name": "test[exec echo without ee  clear && ansible-navigator exec --excmd 'echo test_data_from_cli' --ee False --ll debug --mode stdout]",
+    "index": 1,
+    "comment": "exec echo without ee",
+    "additional_information": {
+        "look_fors": [
+            "bash",
+            "test_data_from_cli",
+            "ERROR",
+            "requires execution environment support"
+        ],
+        "look_nots": [],
+        "compared_fixture": false
+    },
+    "output": [
+        "[ERROR]: Command provided: 'exec --excmd 'echo test_data_from_cli' --ee False --ll debug --mode stdout'",
+        "[ERROR]: The 'exec' subcommand requires execution environment support.",
+        " [HINT]: Try again with '--ee true' to enable the use of an execution environment.",
+        "[ERROR]: Configuration failed, using default log file location: /home/user/github/ansible-navigator/ansible-navigator.log. Log level set to debug",
+        " [HINT]: Review the hints and log file to see what went wrong: /home/user/github/ansible-navigator/ansible-navigator.log",
+        "(venv) bash-5.1$"
+    ]
+}

tests/fixtures/integration/actions/exec/test_stdout_config_cli.py/test/2.json

@@ -0,0 +1,16 @@
+{
+    "name": "test[exec echo check path via shell  clear && ansible-navigator exec --excmd 'echo $PATH' --ee True --ll debug --mode stdout]",
+    "index": 2,
+    "comment": "exec echo check path via shell",
+    "additional_information": {
+        "look_fors": [
+            "/sbin"
+        ],
+        "look_nots": [],
+        "compared_fixture": false
+    },
+    "output": [
+        "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+        "(venv) bash-5.1$"
+    ]
+}

tests/fixtures/integration/actions/exec/test_stdout_config_cli.py/test/3.json

@@ -0,0 +1,16 @@
+{
+    "name": "test[exec echo check no path via shell  clear && ansible-navigator exec --excmd 'echo $PATH' --exshell false --ee True --ll debug --mode stdout]",
+    "index": 3,
+    "comment": "exec echo check no path via shell",
+    "additional_information": {
+        "look_fors": [
+            "$PATH"
+        ],
+        "look_nots": [],
+        "compared_fixture": false
+    },
+    "output": [
+        "$PATH",
+        "(venv) bash-5.1$"
+    ]
+}

tests/fixtures/integration/actions/exec/test_stdout_config_file.py/test/0.json

@@ -0,0 +1,19 @@
+{
+    "name": "test[exec echo with ee  clear && ansible-navigator exec --ee True --ll debug --mode stdout]",
+    "index": 0,
+    "comment": "exec echo with ee",
+    "additional_information": {
+        "look_fors": [
+            "bash",
+            "test_data_from_config"
+        ],
+        "look_nots": [
+            "ERROR"
+        ],
+        "compared_fixture": false
+    },
+    "output": [
+        "test_data_from_config",
+        "(venv) bash-5.1$"
+    ]
+}

tests/fixtures/integration/actions/exec/test_stdout_config_file.py/test/1.json

@@ -0,0 +1,16 @@
+{
+    "name": "test[exec echo check no path via shell  clear && ansible-navigator exec --excmd '/usr/bin/echo $PATH' --ee True --ll debug --mode stdout]",
+    "index": 1,
+    "comment": "exec echo check no path via shell",
+    "additional_information": {
+        "look_fors": [],
+        "look_nots": [
+            "/sbin"
+        ],
+        "compared_fixture": false
+    },
+    "output": [
+        "$PATH",
+        "(venv) bash-5.1$"
+    ]
+}