refactor(engine): Abstract subprocess execution into pluggable command runner

Add engine abstraction to support multiple tmux command execution backends
(subprocess now, control mode in future) while maintaining 100% backward
compatibility.

New files:
- src/libtmux/_internal/command_runner.py: Protocol definitions for
  CommandRunner and CommandResult interfaces
- src/libtmux/_internal/engines/: Engine implementations
  - subprocess_engine.py: SubprocessCommandRunner wraps existing tmux_cmd
- src/libtmux/pytest_plugin.py: Add command_runner fixture for DI in tests

Modified files:
- src/libtmux/server.py:
  - Add optional command_runner parameter to Server.__init__()
  - Add command_runner property with lazy initialization
  - Modify Server.cmd() to use self.command_runner.run()
- src/libtmux/pytest_plugin.py:
  - Add command_runner fixture (returns None by default)
  - Update server and TestServer fixtures to accept command_runner

Key design decisions:
- Protocol-based design (structural typing, no inheritance required)
- Optional parameter with lazy initialization (backward compatible)
- All existing code works unchanged
- SubprocessCommandRunner wraps existing tmux_cmd for compatibility

Passes all quality checks:
- mypy (strict mode): ✓
- ruff (linting): ✓
- All 409 existing tests pass unchanged

Author: tony

src/libtmux/_internal/command_runner.py

@@ -0,0 +1,80 @@
+"""Command runner protocols for tmux execution engines."""
+
+from __future__ import annotations
+
+import typing as t
+from typing import Protocol
+
+if t.TYPE_CHECKING:
+    from libtmux.common import tmux_cmd
+
+
+class CommandResult(Protocol):
+    """Protocol for command execution results.
+
+    Any object conforming to this protocol can be returned by a CommandRunner.
+    The existing tmux_cmd class automatically conforms to this protocol.
+
+    Attributes
+    ----------
+    stdout : list[str]
+        Command standard output, split by lines
+    stderr : list[str]
+        Command standard error, split by lines
+    returncode : int
+        Command return code
+    cmd : list[str]
+        The command that was executed (for debugging)
+    """
+
+    @property
+    def stdout(self) -> list[str]:
+        """Command standard output, split by lines."""
+        ...
+
+    @property
+    def stderr(self) -> list[str]:
+        """Command standard error, split by lines."""
+        ...
+
+    @property
+    def returncode(self) -> int:
+        """Command return code."""
+        ...
+
+    @property
+    def cmd(self) -> list[str]:
+        """The command that was executed (for debugging)."""
+        ...
+
+
+class CommandRunner(Protocol):
+    """Protocol for tmux command execution engines.
+
+    Implementations must provide a run() method that executes tmux commands
+    and returns a CommandResult.
+
+    Examples
+    --------
+    >>> from libtmux._internal.engines import SubprocessCommandRunner
+    >>> runner = SubprocessCommandRunner()
+    >>> result = runner.run("-V")
+    >>> assert hasattr(result, 'stdout')
+    >>> assert hasattr(result, 'stderr')
+    >>> assert hasattr(result, 'returncode')
+    """
+
+    def run(self, *args: str) -> tmux_cmd:
+        """Execute a tmux command.
+
+        Parameters
+        ----------
+        *args : str
+            Command arguments to pass to tmux binary
+
+        Returns
+        -------
+        CommandResult
+            Object with stdout, stderr, returncode, cmd attributes
+        """
+        ...

src/libtmux/_internal/engines/__init__.py

@@ -0,0 +1,7 @@
+"""Command execution engines for libtmux."""
+
+from __future__ import annotations
+
+__all__ = ("SubprocessCommandRunner",)
+
+from libtmux._internal.engines.subprocess_engine import SubprocessCommandRunner

src/libtmux/_internal/engines/subprocess_engine.py

@@ -0,0 +1,41 @@
+"""Subprocess-based command execution engine."""
+
+from __future__ import annotations
+
+import typing as t
+
+if t.TYPE_CHECKING:
+    from libtmux.common import tmux_cmd
+
+
+class SubprocessCommandRunner:
+    """Command runner that uses subprocess to execute tmux binary.
+
+    This is the default command runner and wraps the existing tmux_cmd
+    implementation for backward compatibility.
+
+    Examples
+    --------
+    >>> runner = SubprocessCommandRunner()
+    >>> result = runner.run("-V")
+    >>> assert hasattr(result, 'stdout')
+    >>> assert hasattr(result, 'stderr')
+    >>> assert hasattr(result, 'returncode')
+    """
+
+    def run(self, *args: str) -> tmux_cmd:
+        """Execute tmux command via subprocess.
+
+        Parameters
+        ----------
+        *args : str
+            Arguments to pass to tmux binary
+
+        Returns
+        -------
+        tmux_cmd
+            Command result with stdout, stderr, returncode
+        """
+        from libtmux.common import tmux_cmd
+
+        return tmux_cmd(*args)

src/libtmux/pytest_plugin.py

@@ -19,6 +19,7 @@
 if t.TYPE_CHECKING:
     import pathlib
 
+    from libtmux._internal.command_runner import CommandRunner
     from libtmux.session import Session
 
 logger = logging.getLogger(__name__)
@@ -110,11 +111,38 @@ def clear_env(monkeypatch: pytest.MonkeyPatch) -> None:
             monkeypatch.delenv(k)
 
 
+@pytest.fixture
+def command_runner() -> CommandRunner | None:
+    """Command runner for tests.
+
+    Override this fixture in conftest.py to provide a custom command runner
+    for all tests.
+
+    Returns
+    -------
+    CommandRunner or None
+        Custom command runner, or None to use default subprocess runner
+
+    Examples
+    --------
+    >>> def test_with_default(command_runner):
+    ...     assert command_runner is None  # Default uses subprocess
+
+    To use a custom runner:
+
+    >>> @pytest.fixture
+    ... def command_runner():
+    ...     return MyCustomRunner()
+    """
+    return None
+
+
 @pytest.fixture
 def server(
     request: pytest.FixtureRequest,
     monkeypatch: pytest.MonkeyPatch,
     config_file: pathlib.Path,
+    command_runner: CommandRunner | None,
 ) -> Server:
     """Return new, temporary :class:`libtmux.Server`.
 
@@ -141,7 +169,10 @@ def server(
 
         >>> result.assert_outcomes(passed=1)
     """
-    server = Server(socket_name=f"libtmux_test{next(namer)}")
+    server = Server(
+        socket_name=f"libtmux_test{next(namer)}",
+        command_runner=command_runner,
+    )
 
     def fin() -> None:
         server.kill()
@@ -263,6 +294,7 @@ def session(
 @pytest.fixture
 def TestServer(
     request: pytest.FixtureRequest,
+    command_runner: CommandRunner | None,
 ) -> type[Server]:
     """Create a temporary tmux server that cleans up after itself.
 
@@ -309,6 +341,7 @@ def fin() -> None:
         "type[Server]",
         functools.partial(
             Server,
+            command_runner=command_runner,
             on_init=on_init,
             socket_name_factory=socket_name_factory,
         ),

src/libtmux/server.py

@@ -38,6 +38,7 @@
 
     from typing_extensions import Self
 
+    from libtmux._internal.command_runner import CommandRunner
     from libtmux._internal.types import StrPath
 
     DashLiteral: TypeAlias = t.Literal["-"]
@@ -64,6 +65,8 @@ class Server(EnvironmentMixin):
     socket_path : str, optional
     config_file : str, optional
     colors : str, optional
+    command_runner : CommandRunner, optional
+        Custom command execution engine. Defaults to subprocess-based runner.
     on_init : callable, optional
     socket_name_factory : callable, optional
 
@@ -124,13 +127,15 @@ def __init__(
         socket_path: str | pathlib.Path | None = None,
         config_file: str | None = None,
         colors: int | None = None,
+        command_runner: CommandRunner | None = None,
         on_init: t.Callable[[Server], None] | None = None,
         socket_name_factory: t.Callable[[], str] | None = None,
         **kwargs: t.Any,
     ) -> None:
         EnvironmentMixin.__init__(self, "-g")
         self._windows: list[WindowDict] = []
         self._panes: list[PaneDict] = []
+        self._command_runner = command_runner
 
         if socket_path is not None:
             self.socket_path = socket_path
@@ -188,6 +193,39 @@ def __exit__(
         if self.is_alive():
             self.kill()
 
+    @property
+    def command_runner(self) -> CommandRunner:
+        """Get or lazily initialize the command runner.
+
+        Returns
+        -------
+        CommandRunner
+            The command execution engine for this server
+
+        Examples
+        --------
+        >>> server = Server(socket_name="default")
+        >>> assert server.command_runner is not None
+        >>> type(server.command_runner).__name__
+        'SubprocessCommandRunner'
+        """
+        if self._command_runner is None:
+            from libtmux._internal.engines import SubprocessCommandRunner
+
+            self._command_runner = SubprocessCommandRunner()
+        return self._command_runner
+
+    @command_runner.setter
+    def command_runner(self, value: CommandRunner) -> None:
+        """Set the command runner.
+
+        Parameters
+        ----------
+        value : CommandRunner
+            New command execution engine
+        """
+        self._command_runner = value
+
     def is_alive(self) -> bool:
         """Return True if tmux server alive.
 
@@ -298,7 +336,9 @@ def cmd(
 
         cmd_args = ["-t", str(target), *args] if target is not None else [*args]
 
-        return tmux_cmd(*svr_args, *cmd_args)
+        # Convert all arguments to strings for the command runner
+        all_args = [str(arg) for arg in [*svr_args, *cmd_args]]
+        return self.command_runner.run(*all_args)
 
     @property
     def attached_sessions(self) -> list[Session]: