cmdbox-cli 1.0.0__py3-none-any.whl

cmdbox/runtime/executor.py

@@ -0,0 +1,454 @@
+import logging
+import os
+import sys
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from typing import Mapping
+
+import typer
+
+from cmdbox.runtime.results import ExecutionResult
+from cmdbox.runtime.shell import build_shell_command
+from cmdbox.logging_setup.log_decorators import log_action
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class RunContext:
+    """
+    Represents the execution context for a runnable process.
+
+    This class defines the environment and settings under which a process is
+    executed. It includes attributes such as the current working directory,
+    environment variables, and capture settings. Being a frozen dataclass, the
+    RunContext instances are immutable.
+
+    Attributes:
+        cwd (str | None): The current working directory for the process. If None,
+            the process will inherit the working directory from the parent process.
+        env (Mapping[str, str] | None): Environment variables to set for the
+            process. If None, the process will inherit the environment from the
+            parent process.
+        capture (bool): Whether the process's output streams should be captured.
+            If False, the output streams will inherit those of the parent process.
+        shell (str | None): The shell to use for executing the command. If None,
+            the system default shell will be used.
+        timeout (int | None): The maximum time in seconds to wait for the command
+            to complete. If None, the command will run indefinitely. Defaults to None.
+        emit (bool): Whether to emit the command template.  If True, the command
+            template is emitted to the current terminal window to be evaluated
+            in the current session.  If False, the command is executed in a
+            different session using a subprocess.  Defaults to False.
+        verbose (bool): Whether to output additional information alongside the
+            command output. Defaults to False.
+    """
+
+    cwd: str | None = None
+    env: Mapping[str, str] | None = None
+    capture: bool = False
+    shell: str | None = None
+    timeout: int | None = None
+    emit: bool = False
+    verbose: bool = False
+
+
+class Executor:
+
+    @log_action(__name__, "run_executor_run")
+    def run(self, command: str, ctx: RunContext | None = None) -> ExecutionResult:
+        """
+        Executes a shell command in a subprocess, capturing the output and exit code.
+
+        This method takes a shell command as a string and runs it in a subprocess. It
+        allows the caller to specify the working directory, environment variables, and
+        whether or not to capture the output through the provided context. The result
+        of the execution is returned encapsulated in an `ExecutionResult`.
+
+        Args:
+            command (str): The shell command to be executed.
+            ctx (RunContext, optional): An instance of `RunContext` that provides
+                additional execution context such as the working directory,
+                environment variables, and capture preferences. Defaults to a new
+                `RunContext()` instance.
+
+        Returns:
+            ExecutionResult: An object containing the executed command, the exit code,
+                and the captured standard output and error streams.
+        """
+        if not ctx:
+            ctx = RunContext()
+        log.info(
+            "Executing command: mode=%s, multiline=%s, capture=%s, shell=%s, cmd_len=%s, cwd_set=%s, env_override=%s, timeout=%s",
+            "emit" if ctx.emit else "subprocess",
+            self.is_multiline(command),
+            ctx.capture,
+            ctx.shell,
+            len(command),
+            ctx.cwd is not None,
+            ctx.env is not None,
+            ctx.timeout,
+        )
+
+        if ctx.emit:
+            self.emit_command(command)
+            return None  # Just a safeguard, this should not return if emit is True
+
+        env = os.environ.copy()
+        if ctx.env:
+            env.update(dict(ctx.env))
+
+        if self.is_multiline(command):
+            return self.run_multiline_as_script(command, ctx=ctx, env=env)
+
+        popen_args = build_shell_command(command, preferred_shell=ctx.shell)
+        return self.execute_command(
+            command,
+            popen_args=popen_args,
+            cwd=ctx.cwd,
+            env=env,
+            capture_output=ctx.capture,
+            timeout=ctx.timeout,
+        )
+
+    @log_action(__name__, "run_executor_run_multiline_as_script")
+    def run_multiline_as_script(
+        self, command: str, ctx: RunContext, env: dict[str, str]
+    ) -> ExecutionResult:
+        """
+        Executes a multiline command as a script in the context of a specified shell environment.
+
+        This method creates a temporary script file containing the provided multiline command and
+        executes it using subprocess. The command is normalized for consistent behavior across
+        platforms, and an optional shell-specific header is prepended based on the execution context.
+
+        Args:
+            command (str): The multiline command to execute as a script.
+            ctx (RunContext): Context about the execution, including shell type, working directory,
+                and whether to capture output.
+            env (dict[str, str]): A dictionary of environment variables to set during script execution.
+
+        Returns:
+            ExecutionResult: An object containing the executed command, its exit code, and captured
+            standard output and error streams.
+        """
+        shell = (ctx.shell or "default").lower()
+        suffix = self.script_suffix_for_shell(shell)
+        script_path = None
+
+        if shell == "default":
+            log.debug("exec multiline as default shell, suffix=%s", suffix)
+        else:
+            log.debug("exec multiline as shell=%s, suffix=%s", shell, suffix)
+
+        # Normalize newlines so contents is consistent across platforms
+        script_body = command.replace("\r\n", "\n").rstrip("\n") + "\n"
+
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w",
+                encoding="utf-8",
+                delete=False,
+                suffix=suffix,
+            ) as file:
+                script_path = file.name
+                header = self.script_header_for_shell(shell)
+                if header:
+                    file.write(header)
+                file.write(script_body)
+
+            popen_args = self.build_script_exec_args(script_path, shell=shell)
+            log.debug(
+                "exec multiline args_count=%s header=%s", len(popen_args), bool(header)
+            )
+
+            return self.execute_command(
+                command,
+                popen_args=popen_args,
+                cwd=ctx.cwd,
+                env=env,
+                capture_output=ctx.capture,
+                timeout=ctx.timeout,
+            )
+
+        finally:
+            if script_path:
+                try:
+                    os.remove(script_path)
+                except OSError:
+                    pass
+
+    def execute_command(
+        self,
+        command: str,
+        *,
+        popen_args: list[str],
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+        capture_output: bool = False,
+        timeout: int | None = None,
+    ) -> ExecutionResult:
+        """
+        Executes a command using the appropriate subprocess strategy based on
+        whether a timeout is set. When no timeout is provided, uses subprocess.run
+        for simplicity. When a timeout is provided, uses subprocess.Popen with
+        process tree cleanup to prevent orphaned child processes on timeout.
+
+        Args:
+            command (str): The original command string, used for logging and the
+                returned ExecutionResult.
+            popen_args (list[str]): The fully resolved argument list to pass to
+                the subprocess.
+            cwd (str | None): Working directory for the process.
+            env (dict[str, str] | None): Environment variables for the process.
+            capture_output (bool): Whether to capture stdout and stderr.
+            timeout (int | None): Maximum seconds to wait before killing the
+                process tree. If None, the command runs indefinitely.
+
+        Returns:
+            ExecutionResult: The result of the execution including exit code and
+                any captured output.
+        """
+        if timeout is not None:
+            # If timeout is provided, use _run_subprocess method to handle timeout
+            try:
+                completed = self._run_subprocess(
+                    popen_args,
+                    cwd=cwd,
+                    env=env,
+                    capture_output=capture_output,
+                    timeout=timeout,
+                )
+            except subprocess.TimeoutExpired:
+                log.warning("Command timed out after %s seconds", timeout)
+                return ExecutionResult(
+                    command=command,
+                    exit_code=124,
+                    stdout="",
+                    stderr=f"Command timed out after {timeout} seconds",
+                )
+        else:
+            completed = subprocess.run(
+                popen_args,
+                cwd=cwd,
+                text=True,
+                env=env,
+                capture_output=capture_output,
+            )
+
+        log.info("Command completed with exit code: %s", completed.returncode)
+
+        return ExecutionResult(
+            command=command,
+            exit_code=completed.returncode,
+            stdout=completed.stdout or "",
+            stderr=completed.stderr or "",
+        )
+
+    def _run_subprocess(
+        self,
+        popen_args: list[str],
+        *,
+        cwd: str | None,
+        env: dict[str, str] | None,
+        capture_output: bool,
+        timeout: int | None,
+    ) -> subprocess.CompletedProcess:
+        """
+        Runs a subprocess with proper process tree cleanup on timeout. On timeout,
+        the entire process tree is killed rather than just the direct child, which
+        prevents orphaned processes from continuing to run after the timeout expires.
+
+        Args:
+            popen_args (list[str]): The command and arguments to run.
+            cwd (str | None): Working directory for the process.
+            env (dict[str, str]): Environment variables for the process.
+            capture_output (bool): Whether to capture stdout and stderr.
+            timeout (int | None): Maximum seconds to wait before killing the process tree.
+
+        Returns:
+            subprocess.CompletedProcess: The result of the process.
+
+        Raises:
+            subprocess.TimeoutExpired: If the process exceeds the timeout.
+        """
+        kwargs = dict(
+            cwd=cwd,
+            text=True,
+            env=env,
+            stdout=subprocess.PIPE if capture_output else None,
+            stderr=subprocess.PIPE if capture_output else None,
+        )
+
+        if sys.platform != "win32":
+            kwargs["start_new_session"] = True
+
+        with subprocess.Popen(popen_args, **kwargs) as proc:
+            try:
+                stdout, stderr = proc.communicate(timeout=timeout)
+                return subprocess.CompletedProcess(
+                    popen_args, proc.returncode, stdout, stderr
+                )
+            except (subprocess.TimeoutExpired, KeyboardInterrupt):
+                self._kill_process_tree(proc)
+                proc.wait()
+                raise
+
+    @staticmethod
+    def _kill_process_tree(proc: subprocess.Popen) -> None:
+        """
+        Kills a process and all of its children. On Windows, uses taskkill to
+        terminate the entire process tree. On Linux, sends SIGTERM to the process
+        group created by start_new_session=True.
+
+        Args:
+            proc (subprocess.Popen): The process whose tree should be killed.
+        """
+        if sys.platform == "win32":
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                capture_output=True,
+            )
+        else:
+            import signal
+
+            try:
+                os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+            except ProcessLookupError:
+                proc.kill()
+
+    @staticmethod
+    def emit_command(command: str) -> None:
+        """
+        Emits a formatted command to standard output and terminates the process
+        with a success exit code.
+
+        This method takes a string command as input, appends a newline character,
+        and writes it to the standard output. It ensures the command is formatted
+        with a single trailing newline before being emitted. Once executed, the
+        method forcefully exits the process with an exit code of 0.
+
+        Args:
+            command (str): The input command that needs to be written to standard
+                output. It should be a valid string representation of the command
+                to execute.
+        """
+        cmd = command.strip("\n") + "\n"
+        sys.stdout.write(cmd)
+        raise typer.Exit(code=0)
+
+    @staticmethod
+    def is_multiline(command: str) -> bool:
+        """
+        Determines if the given command is multiline. A command is considered multiline
+        if it contains at least one newline character after stripping leading and trailing
+        newlines.
+
+        Args:
+            command (str): The command string to check.
+
+        Returns:
+            bool: True if the command contains at least one newline character after
+            trimming leading and trailing newline characters, False otherwise.
+        """
+        return "\n" in command.strip("\n")
+
+    @staticmethod
+    def script_suffix_for_shell(shell: str) -> str:
+        """
+        Determines the appropriate script file suffix for a given shell.
+
+        This function inspects the input shell name or its characteristics and returns
+        the corresponding script file suffix based on the shell's type.
+
+        Args:
+            shell (str): The name of the shell or its identifier.
+
+        Returns:
+            str: The appropriate script file suffix for the given shell.
+        """
+        if shell == "default":
+            return ".cmd" if sys.platform == "win32" else ".sh"
+        if "cmd" in shell or shell == "cmd.exe":
+            return ".cmd"
+        if "powershell" in shell or shell == "pwsh":
+            return ".ps1"
+        if "fish" in shell:
+            return ".fish"
+        # Default to bash
+        return ".sh"
+
+    @staticmethod
+    def script_header_for_shell(shell: str) -> str:
+        """
+        Generates a script header for the given shell type.
+
+        This method determines the appropriate script header based on the
+        specified shell string. Supported shells include bash, zsh, and fish.
+        If the shell type isn't recognized or no header is required, it returns
+        an empty string.
+
+        Args:
+            shell (str): The name of the shell for which the script header is
+                to be generated.
+
+        Returns:
+            str: The script header string corresponding to the provided shell,
+                or an empty string if no header is required.
+        """
+        if "bash" in shell:
+            return "#!/usr/bin/env bash\n"
+        if "zsh" in shell:
+            return "#!/usr/bin/env zsh\n"
+        if "fish" in shell:
+            return "#!/usr/bin/env fish\n"
+        # Other types do not require a header
+        return ""
+
+    @staticmethod
+    def build_script_exec_args(script_path: str, shell: str) -> list[str]:
+        """
+        Assembles a list of arguments to execute a given script based on the specified shell.
+
+        This method generates the appropriate command and arguments to execute
+        a script, tailored to the shell type provided. It ensures compatibility with
+        various shell environments such as cmd, PowerShell, bash, zsh, and fish.
+
+        Args:
+            script_path (str): The file path to the script that needs to be executed.
+            shell (str): The name or identifier of the shell environment used for script execution.
+
+        Returns:
+            list[str]: A list of arguments that, when executed, run the specified script in the given shell.
+        """
+        if shell == "default":
+            if sys.platform == "win32":
+                return ["cmd.exe", "/d", "/s", "/c", script_path]
+            return ["sh", script_path]
+
+        if "cmd" in shell or shell == "cmd.exe":
+            return ["cmd.exe", "/d", "/s", "/c", script_path]
+
+        if "powershell" in shell or shell == "pwsh":
+            exe = "pwsh" if "pwsh" in shell else "powershell"
+            return [
+                exe,
+                "-NoProfile",
+                "-NonInteractive",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                script_path,
+            ]
+
+        if "fish" in shell:
+            return ["fish", script_path]
+
+        if "zsh" in shell:
+            return ["zsh", script_path]
+
+        if "bash" in shell:
+            return ["bash", script_path]
+
+        return ["sh", script_path]

cmdbox/runtime/results.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ExecutionResult:
+    """
+    Represents the result of a command execution.
+
+    This class is a data container that holds details of a command execution
+    outcome, including the executed command, its exit status, and associated
+    standard output and error streams. It is designed to provide a structured
+    result of running an external command in a consistent and immutable format.
+
+    Attributes:
+        command (str): The actual command that was executed. Extrapolated
+            from the Command.template.
+        exit_code (int): The exit code returned by the command.
+        stdout (str): The standard output produced by the command.
+        stderr (str): The standard error output produced by the command.
+    """
+
+    command: str
+    exit_code: int
+    stdout: str
+    stderr: str

cmdbox/runtime/shell.py

@@ -0,0 +1,90 @@
+import os
+import sys
+from shutil import which
+
+
+def build_shell_command(command: str, preferred_shell: str | None = None) -> list[str]:
+    """
+    Builds a shell command list based on the provided command and preferred shell, with fallback mechanisms for
+    platform compatibility and environment-specific configurations.
+
+    This function determines the appropriate shell and constructs a command list for execution. It handles both
+    Windows and Unix-like environments, prioritizing the specified preferred shell or defaulting to environment
+    variables and standard fallback options. If no suitable shell is found, it raises a RuntimeError.
+
+    Args:
+        command (str): The shell command to execute.
+        preferred_shell (str | None): The preferred shell to use for executing the command. If None, the function
+            attempts to determine an appropriate shell based on the platform, environment, and fallback defaults.
+
+    Returns:
+        list[str]: A list containing the shell command and its arguments.
+
+    Raises:
+        RuntimeError: If no usable shell is found for the current system.
+    """
+    candidates: list[tuple[str, list[str]]] = []
+
+    # Windows options
+    if sys.platform.startswith("win"):
+        if preferred_shell:
+            candidates.append(
+                (preferred_shell, _windows_shell_args(preferred_shell, command))
+            )
+
+        env_shell = os.environ.get("CMDBOX_SHELL")
+        if env_shell:
+            candidates.append((env_shell, _windows_shell_args(env_shell, command)))
+
+        # Known good fallbacks
+        candidates.extend(
+            [
+                ("pwsh", ["pwsh", "-NoProfile", "-Command", command]),
+                ("powershell", ["powershell", "-NoProfile", "-Command", command]),
+                ("cmd.exe", ["cmd.exe", "/C", command]),
+            ]
+        )
+
+        for exe, args in candidates:
+            if which(exe):
+                return args
+
+        # Last resort option
+        return ["cmd.exe", "/C", command]
+
+    # Unix options
+    if preferred_shell:
+        candidates.append((preferred_shell, [preferred_shell, "-lc", command]))
+
+    env_shell = os.environ.get("SHELL")
+    if env_shell:
+        candidates.append((env_shell, [env_shell, "-lc", command]))
+
+    candidates.extend(
+        [
+            ("/bin/bash", ["/bin/bash", "-lc", command]),
+            ("/bin/sh", ["/bin/sh", "-lc", command]),
+        ]
+    )
+
+    for exe, args in candidates:
+        if os.path.isabs(exe):
+            if os.path.exists(exe):
+                return args
+        elif which(exe):
+            return args
+
+    raise RuntimeError("No usable shell found for this system")
+
+
+def _windows_shell_args(shell: str, command: str) -> list[str]:
+    shell = shell.lower()
+
+    if shell in ("pwsh", "powershell"):
+        return [shell, "-NoProfile", "-Command", command]
+
+    if shell in ("cmd", "cmd.exe"):
+        return ["cmd.exe", "/C", command]
+
+    # Treat unknown shell as executable
+    return [shell, command]