mcp-coder-utils 0.1.2__py3-none-any.whl

mcp_coder_utils/__init__.py

@@ -0,0 +1 @@
+"""Shared low-level Python helpers for the mcp-coder family of repos."""

mcp_coder_utils/subprocess_runner.py

@@ -0,0 +1,754 @@
+"""Subprocess execution utilities with process isolation support.
+
+This module provides functions for executing command-line tools with proper
+timeout handling and STDIO isolation for Python commands.
+"""
+
+import logging
+import os
+import shlex
+import signal
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Re-export for external use (allows catching without direct subprocess import)
+from subprocess import CalledProcessError, SubprocessError, TimeoutExpired
+
+logger = logging.getLogger(__name__)
+
+MAX_STDERR_IN_ERROR: int = 500
+
+__all__ = [
+    "CommandResult",
+    "CommandOptions",
+    "MAX_STDERR_IN_ERROR",
+    "check_tool_missing_error",
+    "execute_command",
+    "execute_subprocess",
+    "launch_process",
+    "format_command",
+    "prepare_env",
+    "truncate_stderr",
+    # Re-exported exceptions
+    "CalledProcessError",
+    "SubprocessError",
+    "TimeoutExpired",
+]
+
+
+def check_tool_missing_error(
+    stderr: str, tool_name: str, python_path: str
+) -> str | None:
+    """Check if stderr indicates the tool is not installed.
+
+    Returns:
+        Error message string if the tool is missing, or None if no issue detected.
+    """
+    if f"No module named {tool_name}" in stderr:
+        return (
+            f"{tool_name} is not installed in the Python environment "
+            f"at {python_path}."
+        )
+    return None
+
+
+def truncate_stderr(stderr: str, max_len: int = MAX_STDERR_IN_ERROR) -> str:
+    """Truncate stderr to a maximum length.
+
+    Returns:
+        The original stderr if within max_len, otherwise truncated with ellipsis.
+    """
+    if len(stderr) > max_len:
+        return stderr[:max_len] + "..."
+    return stderr
+
+
+def format_command(command: list[str]) -> str:
+    """Format a command list as a platform-aware shell string.
+
+    Uses shlex.join() on Unix, subprocess.list2cmdline() on Windows.
+    Truncates at 200 characters with '...' suffix.
+
+    Returns:
+        The formatted command string, truncated if longer than 200 characters.
+    """
+    if os.name == "nt":
+        full = subprocess.list2cmdline(command)
+    else:
+        full = shlex.join(command)
+    if len(full) > 200:
+        return full[:200] + "..."
+    return full
+
+
+@dataclass
+class CommandResult:
+    """Represents the result of a command execution."""
+
+    return_code: int
+    stdout: str
+    stderr: str
+    timed_out: bool
+    execution_error: str | None = None
+    command: list[str] | None = field(default=None)
+    runner_type: str | None = field(default=None)
+    execution_time_ms: int | None = field(default=None)
+
+
+@dataclass
+class CommandOptions:
+    """Configuration options for command execution.
+
+    Attributes:
+        cwd: Working directory for the subprocess
+        timeout_seconds: Maximum time to wait for process completion
+        env: Environment variables for the subprocess. May contain internal
+             testing flags prefixed with underscore (e.g., _DISABLE_STDIO_ISOLATION)
+             that should NEVER be used in production code.
+        env_remove: List of environment variable names to remove after merging
+        capture_output: Whether to capture stdout and stderr
+        text: Whether to decode output as text
+        check: Whether to raise exception on non-zero exit code
+        shell: Whether to execute through shell
+        input_data: Data to send to subprocess stdin
+
+    Warning:
+        Environment variables starting with underscore (_) are internal testing
+        flags that bypass safety mechanisms. They must not be used in production.
+    """
+
+    cwd: str | None = None
+    timeout_seconds: int = 120
+    env: dict[str, str] | None = None
+    capture_output: bool = True
+    text: bool = True
+    check: bool = False
+    shell: bool = False
+    input_data: str | None = None
+    env_remove: list[str] | None = None
+
+
+def is_python_command(command: list[str]) -> bool:
+    """Check if a command is a Python execution command.
+
+    Returns:
+        True if the command runs a Python interpreter.
+    """
+    if not command:
+        return False
+
+    executable = Path(command[0]).name.lower()
+    return (
+        executable in ["python", "python3", "python.exe", "python3.exe"]
+        or command[0] == sys.executable
+    )
+
+
+def get_python_isolation_env() -> dict[str, str]:
+    """Get environment variables for Python subprocess isolation.
+
+    Returns:
+        Dict of environment variables with MCP isolation settings.
+    """
+    env = os.environ.copy()
+
+    # Python-specific settings to prevent MCP STDIO conflicts
+    env.update(
+        {
+            "PYTHONUNBUFFERED": "1",
+            "PYTHONDONTWRITEBYTECODE": "1",
+            "PYTHONIOENCODING": "utf-8",
+            "PYTHONNOUSERSITE": "1",
+            "PYTHONHASHSEED": "0",
+            "PYTHONSTARTUP": "",
+        }
+    )
+
+    # Remove MCP-specific variables
+    for var in ["MCP_STDIO_TRANSPORT", "MCP_SERVER_NAME", "MCP_CLIENT_PARAMS"]:
+        env.pop(var, None)
+
+    return env
+
+
+def get_utf8_env() -> dict[str, str]:
+    """Get environment variables for UTF-8 encoding support on all subprocess types.
+
+    Returns:
+        Dict of environment variables with UTF-8 encoding settings.
+    """
+    env = os.environ.copy()
+
+    # Set UTF-8 encoding for all subprocess types
+    env.update(
+        {
+            "PYTHONIOENCODING": "utf-8",
+            "PYTHONUTF8": "1",
+        }
+    )
+
+    # On Windows, also set legacy encoding variables
+    if os.name == "nt":
+        env.update(
+            {
+                "PYTHONLEGACYWINDOWSFSENCODING": "utf-8",
+            }
+        )
+    else:
+        # On Unix systems, set locale for UTF-8
+        env.update(
+            {
+                "LC_ALL": "C.UTF-8",
+            }
+        )
+
+    return env
+
+
+def prepare_env(
+    command: list[str] | str,
+    env: dict[str, str] | None,
+    env_remove: list[str] | None,
+) -> dict[str, str]:
+    """Build a complete environment dict for subprocess execution.
+
+    Starts from os.environ, applies Python isolation or UTF-8 settings
+    based on command type, merges caller-provided env on top, then
+    removes any keys listed in env_remove.
+
+    Args:
+        command: Command as list or string. String commands are always
+            treated as non-Python (shell=True implies unknown executable).
+        env: Optional caller-provided environment variables to merge.
+        env_remove: Optional list of environment variable names to remove.
+
+    Returns:
+        Complete environment dict ready for subprocess.Popen.
+    """
+    if isinstance(command, list) and is_python_command(command):
+        result = get_python_isolation_env()
+    else:
+        result = get_utf8_env()
+
+    if env:
+        result.update(env)
+
+    for key in env_remove or []:
+        result.pop(key, None)
+
+    return result
+
+
+def _kill_process(
+    process: subprocess.Popen[str], logger_instance: logging.Logger
+) -> None:
+    """Kill a subprocess and its children, platform-aware.
+
+    On Unix, sends SIGTERM to the process group, waits briefly, then
+    SIGKILL if the process is still alive.  On Windows, uses
+    ``taskkill /F /T``.  Falls back to ``process.kill()`` on failure.
+
+    Args:
+        process: The subprocess to kill.
+        logger_instance: Logger used for debug messages on fallback paths.
+    """
+    if os.name == "nt":
+        try:
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(process.pid)],
+                capture_output=True,
+                timeout=5,
+                check=False,
+            )
+        except (subprocess.SubprocessError, OSError) as exc:
+            logger_instance.debug(
+                "Taskkill failed, using fallback",
+                extra={"error": str(exc), "pid": process.pid},
+            )
+            process.kill()
+    else:
+        try:
+            if (
+                hasattr(os, "killpg")
+                and hasattr(os, "getpgid")
+                and hasattr(signal, "SIGTERM")
+                and hasattr(signal, "SIGKILL")
+            ):
+                os.killpg(  # type: ignore[attr-defined,unused-ignore]
+                    os.getpgid(process.pid),  # type: ignore[attr-defined,unused-ignore]
+                    signal.SIGTERM,  # type: ignore[attr-defined,unused-ignore]
+                )
+                time.sleep(0.5)
+                if process.poll() is None:
+                    os.killpg(  # type: ignore[attr-defined,unused-ignore]
+                        os.getpgid(process.pid),  # type: ignore[attr-defined,unused-ignore]
+                        signal.SIGKILL,  # type: ignore[attr-defined,unused-ignore]
+                    )
+            else:
+                process.kill()
+        except (OSError, ProcessLookupError, AttributeError) as exc:
+            logger_instance.debug(
+                "Process group kill failed, using fallback",
+                extra={"error": str(exc), "pid": process.pid},
+            )
+            process.kill()
+
+    try:
+        process.wait(timeout=2)
+    except subprocess.TimeoutExpired:
+        pass
+
+
+def _run_subprocess(  # pylint: disable=too-many-statements
+    command: list[str], options: CommandOptions, use_stdio_isolation: bool = False
+) -> subprocess.CompletedProcess[str]:
+    """Run subprocess with or without STDIO isolation.
+
+    Args:
+        command: Command to execute
+        options: Execution options
+        use_stdio_isolation: Whether to use file-based STDIO isolation
+
+    Returns:
+        CompletedProcess with execution results
+
+    Raises:
+        TimeoutExpired: If the subprocess exceeds the configured timeout.
+    """
+    # Track start time for timeout logging
+    subprocess_start_time = time.time()
+    env = prepare_env(command, options.env, options.env_remove)
+
+    # Handle input data and stdin
+    stdin_value = subprocess.DEVNULL if options.input_data is None else None
+
+    # Use start_new_session for process isolation (thread-safe alternative to preexec_fn)
+    start_new_session = os.name != "nt"  # True on Unix, False on Windows
+
+    # Use file-based STDIO for Python commands if needed
+    if use_stdio_isolation and options.capture_output:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            stdout_file = Path(temp_dir) / "stdout.txt"
+            stderr_file = Path(temp_dir) / "stderr.txt"
+
+            process = None
+            stdout_f = None
+            stderr_f = None
+
+            try:
+                # Open files
+                stdout_f = open(stdout_file, "w", encoding="utf-8")
+                stderr_f = open(stderr_file, "w", encoding="utf-8")
+
+                # Use Popen for better process control
+                popen_proc = None
+                try:
+                    popen_proc = subprocess.Popen(
+                        command,
+                        stdout=stdout_f,
+                        stderr=stderr_f,
+                        stdin=(
+                            stdin_value
+                            if options.input_data is None
+                            else subprocess.PIPE
+                        ),
+                        cwd=options.cwd,
+                        text=options.text,
+                        encoding="utf-8" if options.text else None,
+                        errors="replace",  # Replace invalid characters instead of crashing
+                        env=env,
+                        shell=options.shell,
+                        start_new_session=start_new_session,
+                    )
+
+                    # Communicate with timeout
+                    try:
+                        _, _ = popen_proc.communicate(
+                            input=options.input_data, timeout=options.timeout_seconds
+                        )
+                        process = subprocess.CompletedProcess(
+                            args=command,
+                            returncode=popen_proc.returncode,
+                            stdout="",  # Will be read from file
+                            stderr="",  # Will be read from file
+                        )
+                    except subprocess.TimeoutExpired:
+                        # Kill the process and all children
+                        if popen_proc:
+                            elapsed_time = time.time() - subprocess_start_time
+                            logger.warning(
+                                "Killing timed out process",
+                                extra={
+                                    "mode": "stdio_isolation",
+                                    "pid": popen_proc.pid,
+                                    "command": format_command(command),
+                                    "timeout_seconds": options.timeout_seconds,
+                                    "elapsed_seconds": round(elapsed_time, 1),
+                                    "cwd": options.cwd or "current",
+                                },
+                            )
+                            _kill_process(popen_proc, logger)
+
+                        # Re-raise the timeout exception
+                        raise
+
+                except subprocess.TimeoutExpired:
+                    # Close files before re-raising to prevent Windows file locking
+                    # This cleanup is necessary before re-raising the timeout exception
+                    if stdout_f:
+                        stdout_f.flush()
+                        stdout_f.close()
+                    if stderr_f:
+                        stderr_f.flush()
+                        stderr_f.close()
+
+                    # On Windows, add a small delay to help with file handle cleanup
+                    if os.name == "nt":
+                        time.sleep(0.1)
+
+                    # Re-raise to be handled by the caller
+                    raise  # pylint: disable=try-except-raise
+                finally:
+                    # Ensure files are closed
+                    if stdout_f and not stdout_f.closed:
+                        stdout_f.close()
+                    if stderr_f and not stderr_f.closed:
+                        stderr_f.close()
+            except subprocess.TimeoutExpired:  # pylint: disable=try-except-raise
+                raise
+            except Exception:  # pylint: disable=try-except-raise
+                # Let any other exceptions propagate after cleanup in finally block
+                raise
+
+            # Read output files after process completes
+            # Use a small delay on Windows to avoid file locking issues
+            if os.name == "nt":
+                time.sleep(0.2)
+
+            # Read output files, handling potential errors
+            stdout = ""
+            stderr = ""
+
+            try:
+                if stdout_file.exists():
+                    stdout = stdout_file.read_text(encoding="utf-8")
+            except (OSError, PermissionError) as exc:
+                logger.debug("Could not read stdout file", extra={"error": str(exc)})
+
+            try:
+                if stderr_file.exists():
+                    stderr = stderr_file.read_text(encoding="utf-8")
+            except (OSError, PermissionError) as exc:
+                logger.debug("Could not read stderr file", extra={"error": str(exc)})
+
+            # Update the process with the actual output read from files
+            return subprocess.CompletedProcess(
+                args=command,
+                returncode=process.returncode if process else 1,
+                stdout=stdout,
+                stderr=stderr,
+            )
+    else:
+        # Regular execution with better process cleanup
+        popen_proc = None
+        try:
+            if options.capture_output:
+                popen_proc = subprocess.Popen(
+                    command,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    stdin=(
+                        stdin_value if options.input_data is None else subprocess.PIPE
+                    ),
+                    cwd=options.cwd,
+                    text=options.text,
+                    encoding="utf-8" if options.text else None,
+                    errors="replace",  # Replace invalid characters instead of crashing
+                    env=env,
+                    shell=options.shell,
+                    start_new_session=start_new_session,
+                )
+
+                try:
+                    stdout, stderr = popen_proc.communicate(
+                        input=options.input_data, timeout=options.timeout_seconds
+                    )
+                    return subprocess.CompletedProcess(
+                        args=command,
+                        returncode=popen_proc.returncode,
+                        stdout=stdout or "",
+                        stderr=stderr or "",
+                    )
+                except subprocess.TimeoutExpired:
+                    # Kill the process tree on timeout
+                    if popen_proc:
+                        elapsed_time = time.time() - subprocess_start_time
+                        logger.warning(
+                            "Killing timed out process",
+                            extra={
+                                "mode": "regular_execution",
+                                "pid": popen_proc.pid,
+                                "command": format_command(command),
+                                "timeout_seconds": options.timeout_seconds,
+                                "elapsed_seconds": round(elapsed_time, 1),
+                                "cwd": options.cwd or "current",
+                            },
+                        )
+                        _kill_process(popen_proc, logger)
+                    raise
+            else:
+                # No output capture needed
+                return subprocess.run(
+                    command,
+                    capture_output=False,
+                    cwd=options.cwd,
+                    text=options.text,
+                    encoding="utf-8" if options.text else None,
+                    errors="replace",  # Replace invalid characters instead of crashing
+                    timeout=options.timeout_seconds,
+                    env=env,
+                    shell=options.shell,
+                    stdin=stdin_value,
+                    input=options.input_data,
+                    start_new_session=start_new_session,
+                    check=False,
+                )
+        except subprocess.TimeoutExpired:  # pylint: disable=try-except-raise
+            raise
+        except Exception:  # pylint: disable=try-except-raise
+            # Re-raise any other exceptions (this catch-all is needed for cleanup)
+            raise
+
+
+def _run_heartbeat(
+    stop_event: threading.Event,
+    interval: int,
+    message: str,
+    start_time: float,
+) -> None:
+    """Heartbeat loop — runs in a daemon thread, logs at regular intervals."""
+    while not stop_event.wait(interval):
+        elapsed = time.time() - start_time
+        minutes, seconds = divmod(int(elapsed), 60)
+        logger.info("%s (elapsed: %dm %ds)", message, minutes, seconds)
+
+
+def execute_subprocess(
+    command: list[str],
+    options: CommandOptions | None = None,
+    heartbeat_interval_seconds: int | None = None,
+    heartbeat_message: str = "",
+) -> CommandResult:
+    """Execute a command with automatic STDIO isolation for Python commands.
+
+    Args:
+        command: Command and arguments as a list
+        options: Execution options
+        heartbeat_interval_seconds: If set and > 0, log a heartbeat message
+            at this interval (in seconds) while the subprocess is running.
+        heartbeat_message: Message to include in heartbeat log entries.
+
+    Returns:
+        CommandResult with execution details
+
+    Raises:
+        TypeError: If command is None.
+        ValueError: If command is empty.
+        CalledProcessError: If check is True and the process returns non-zero exit code.
+    """
+    if command is None:
+        raise TypeError("Command cannot be None")
+
+    if not command:
+        raise ValueError("Command cannot be empty")
+
+    if options is None:
+        options = CommandOptions()
+
+    start_time = time.time()
+
+    # Determine if we need STDIO isolation
+    disable_isolation = (
+        options.env and options.env.get("_DISABLE_STDIO_ISOLATION") == "1"
+    )
+    use_isolation = is_python_command(command) and not disable_isolation
+
+    logger.debug(
+        "Starting subprocess execution",
+        extra={
+            "command": command[:3] if command else None,
+            "cwd": options.cwd,
+            "timeout_seconds": options.timeout_seconds,
+            "use_isolation": use_isolation,
+        },
+    )
+
+    stop_event = None
+    heartbeat_thread = None
+
+    if heartbeat_interval_seconds and heartbeat_interval_seconds > 0:
+        stop_event = threading.Event()
+        heartbeat_thread = threading.Thread(
+            target=_run_heartbeat,
+            args=(
+                stop_event,
+                heartbeat_interval_seconds,
+                heartbeat_message,
+                start_time,
+            ),
+            daemon=True,
+        )
+        heartbeat_thread.start()
+
+    try:
+        process = _run_subprocess(command, options, use_isolation)
+
+        # Handle check parameter
+        if options.check and process.returncode != 0:
+            raise subprocess.CalledProcessError(
+                process.returncode, command, process.stdout, process.stderr
+            )
+
+        execution_time_ms = int((time.time() - start_time) * 1000)
+
+        return CommandResult(
+            return_code=process.returncode,
+            stdout=process.stdout or "",
+            stderr=process.stderr or "",
+            timed_out=False,
+            command=command,
+            runner_type="subprocess",
+            execution_time_ms=execution_time_ms,
+        )
+
+    except subprocess.TimeoutExpired:
+        execution_time_ms = int((time.time() - start_time) * 1000)
+        return CommandResult(
+            return_code=1,
+            stdout="",
+            stderr="",
+            timed_out=True,
+            execution_error=f"Process timed out after {options.timeout_seconds} seconds",
+            command=command,
+            runner_type="subprocess",
+            execution_time_ms=execution_time_ms,
+        )
+
+    except subprocess.CalledProcessError as e:
+        if options.check:
+            raise
+        execution_time_ms = int((time.time() - start_time) * 1000)
+        return CommandResult(
+            return_code=e.returncode,
+            stdout=getattr(e, "stdout", "") or "",
+            stderr=getattr(e, "stderr", "") or "",
+            timed_out=False,
+            command=command,
+            runner_type="subprocess",
+            execution_time_ms=execution_time_ms,
+        )
+
+    except (FileNotFoundError, PermissionError, OSError) as e:
+        # Handle file system and permission errors
+        execution_time_ms = int((time.time() - start_time) * 1000)
+        logger.error(
+            "Subprocess execution failed",
+            extra={
+                "error": str(e),
+                "error_type": type(e).__name__,
+                "command_preview": command[:3] if command else None,
+            },
+        )
+        return CommandResult(
+            return_code=1,
+            stdout="",
+            stderr="",
+            timed_out=False,
+            execution_error=f"{type(e).__name__}: {e}",
+            command=command,
+            runner_type="subprocess",
+            execution_time_ms=execution_time_ms,
+        )
+
+    finally:
+        if stop_event is not None:
+            stop_event.set()
+        if heartbeat_thread is not None:
+            heartbeat_thread.join(timeout=2)
+
+
+def execute_command(
+    command: list[str],
+    cwd: str | None = None,
+    timeout_seconds: int = 120,
+    env: dict[str, str] | None = None,
+) -> CommandResult:
+    """Execute a command with automatic STDIO isolation for Python commands.
+
+    Args:
+        command: Complete command as list (e.g., ["python", "-m", "pylint", "src"])
+        cwd: Working directory for subprocess
+        timeout_seconds: Timeout in seconds
+        env: Optional environment variables
+
+    Returns:
+        CommandResult with execution details and output
+    """
+    options = CommandOptions(
+        cwd=cwd,
+        timeout_seconds=timeout_seconds,
+        env=env,
+    )
+    return execute_subprocess(command, options)
+
+
+def launch_process(
+    command: list[str] | str,
+    cwd: str | Path | None = None,
+    shell: bool = False,
+    env: dict[str, str] | None = None,
+    env_remove: list[str] | None = None,
+) -> int:
+    """Launch a process without waiting for it to complete.
+
+    This is for fire-and-forget process launching where you need the PID
+    but don't need to wait for completion or capture output.
+
+    Environment variables are always inherited from the parent process
+    via prepare_env(). The ``env`` parameter merges on top of the parent
+    environment rather than replacing it entirely.
+
+    Args:
+        command: Command as list or string (string requires shell=True)
+        cwd: Working directory for the process
+        shell: Whether to execute through shell (required for string commands)
+        env: Extra environment variables merged on top of the parent env
+        env_remove: Environment variable names to remove after merging
+
+    Returns:
+        Process ID (PID) of the launched process
+
+    Example:
+        # Launch VSCode — parent env is inherited automatically
+        pid = launch_process(["code", "myfile.txt"])
+
+        # Launch with extra env vars (no need for os.environ.copy())
+        pid = launch_process(["code", "myfile.txt"], env={"CUSTOM_VAR": "value"})
+    """
+    cwd_str = str(cwd) if cwd else None
+    prepared_env = prepare_env(command, env, env_remove)
+
+    process = subprocess.Popen(
+        command,
+        cwd=cwd_str,
+        shell=shell,
+        env=prepared_env,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    return process.pid

mcp_coder_utils/subprocess_streaming.py

@@ -0,0 +1,185 @@
+"""Subprocess streaming utilities with inactivity watchdog support.
+
+Provides real-time line-by-line stdout streaming from subprocesses,
+with an optional inactivity watchdog that kills hung processes.
+"""
+
+import logging
+import os
+import subprocess
+import threading
+import time
+from collections.abc import Generator
+
+from mcp_coder_utils.subprocess_runner import (
+    CommandOptions,
+    CommandResult,
+    _kill_process,
+    prepare_env,
+)
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "StreamResult",
+    "stream_subprocess",
+]
+
+
+class StreamResult:
+    """Iterator wrapper that yields stdout lines and holds the final CommandResult.
+
+    Consume all lines before accessing ``.result`` — the result is only
+    available after the generator is exhausted or the process terminates.
+    """
+
+    def __init__(self, lines: Generator[str, None, None]) -> None:
+        self._lines = lines
+        self._result: CommandResult | None = None
+
+    def __iter__(self) -> "StreamResult":
+        """Return the iterator object itself."""
+        return self
+
+    def __next__(self) -> str:
+        """Return the next stdout line from the stream."""
+        return next(self._lines)
+
+    @property
+    def result(self) -> CommandResult:
+        """Return the final CommandResult after the stream is consumed.
+
+        Raises:
+            RuntimeError: If the iterator has not been fully consumed yet.
+        """
+        if self._result is None:
+            raise RuntimeError("Result not available yet — consume all lines first.")
+        return self._result
+
+
+def stream_subprocess(
+    command: list[str],
+    options: CommandOptions | None = None,
+    inactivity_timeout_seconds: float | None = None,
+) -> StreamResult:
+    """Stream stdout lines from a subprocess with optional inactivity watchdog.
+
+    Yields one line at a time (with trailing newline stripped). When the
+    iterator is exhausted the caller can access the final
+    :class:`CommandResult` via ``stream_result.result``.
+
+    Args:
+        command: Command and arguments as a list.
+        options: Execution options (timeout_seconds in options is *not*
+            used — use *inactivity_timeout_seconds* for watchdog control).
+        inactivity_timeout_seconds: Kill the process if no stdout line is
+            received for this many seconds.  ``None`` disables the watchdog.
+
+    Returns:
+        A :class:`StreamResult` that yields ``str`` lines and exposes
+        ``.result`` after iteration.
+
+    Raises:
+        TypeError: If command is None.
+        ValueError: If command is empty.
+    """
+    if command is None:
+        raise TypeError("Command cannot be None")
+    if not command:
+        raise ValueError("Command cannot be empty")
+
+    if options is None:
+        options = CommandOptions()
+
+    def _generate() -> Generator[str, None, None]:
+        env = prepare_env(command, options.env, options.env_remove)
+        start_new_session = os.name != "nt"
+        start_time = time.time()
+
+        process = subprocess.Popen(
+            command,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            cwd=options.cwd,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            env=env,
+            shell=options.shell,
+            start_new_session=start_new_session,
+        )
+
+        last_activity = time.time()
+        watchdog_triggered = False
+        stop_watchdog = threading.Event()
+
+        def _watchdog() -> None:
+            nonlocal watchdog_triggered
+            while not stop_watchdog.is_set():
+                if (time.time() - last_activity) > (inactivity_timeout_seconds or 0):
+                    watchdog_triggered = True
+                    logger.warning(
+                        "Inactivity watchdog triggered",
+                        extra={
+                            "pid": process.pid,
+                            "inactivity_timeout_seconds": inactivity_timeout_seconds,
+                        },
+                    )
+                    _kill_process(process, logger)
+                    return
+                stop_watchdog.wait(0.5)
+
+        # Collect stderr in a background thread to avoid pipe-buffer deadlock
+        stderr_chunks: list[str] = []
+
+        def _drain_stderr() -> None:
+            assert process.stderr is not None
+            for line in process.stderr:
+                stderr_chunks.append(line)
+
+        stderr_thread = threading.Thread(target=_drain_stderr, daemon=True)
+        stderr_thread.start()
+
+        watchdog_thread: threading.Thread | None = None
+        if inactivity_timeout_seconds is not None:
+            watchdog_thread = threading.Thread(target=_watchdog, daemon=True)
+            watchdog_thread.start()
+
+        try:
+            assert process.stdout is not None  # guaranteed by PIPE
+            for raw_line in process.stdout:
+                last_activity = time.time()
+                yield raw_line.rstrip("\n").rstrip("\r")
+
+            process.wait()
+
+        finally:
+            stop_watchdog.set()
+            if watchdog_thread is not None:
+                watchdog_thread.join(timeout=2)
+            stderr_thread.join(timeout=5.0)
+
+            stderr = "".join(stderr_chunks)
+
+            execution_time_ms = int((time.time() - start_time) * 1000)
+
+            stream_result._result = CommandResult(  # noqa: W0212
+                return_code=(
+                    process.returncode if process.returncode is not None else 1
+                ),
+                stdout="",  # stdout was streamed line-by-line
+                stderr=stderr,
+                timed_out=watchdog_triggered,
+                execution_error=(
+                    f"Process killed due to inactivity "
+                    f"(no output for {inactivity_timeout_seconds}s)"
+                    if watchdog_triggered
+                    else None
+                ),
+                command=command,
+                runner_type="streaming",
+                execution_time_ms=execution_time_ms,
+            )
+
+    stream_result = StreamResult(lines=_generate())
+    return stream_result

mcp_coder_utils-0.1.2.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: mcp-coder-utils
+Version: 0.1.2
+Summary: Shared low-level Python helpers (subprocess, logging, fs) for the mcp-coder family of repos
+Author-email: Marcus Jellinghaus <Marcus@Jellinghaus.ch>
+Project-URL: Homepage, https://github.com/MarcusJellinghaus/mcp-coder-utils
+Project-URL: Repository, https://github.com/MarcusJellinghaus/mcp-coder-utils
+Project-URL: Bug Tracker, https://github.com/MarcusJellinghaus/mcp-coder-utils/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: structlog>=23.2.0
+Requires-Dist: python-json-logger>=3.3.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+Provides-Extra: dev
+Requires-Dist: mcp-coder-utils[test]; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pylint>=3.0.0; extra == "dev"
+Requires-Dist: ruff>=0.9.0; extra == "dev"
+Requires-Dist: vulture>=2.14; extra == "dev"
+Requires-Dist: import-linter>=2.0; extra == "dev"
+Requires-Dist: mcp-coder; extra == "dev"
+Requires-Dist: mcp-tools-py; extra == "dev"
+Requires-Dist: mcp-workspace; extra == "dev"
+Dynamic: license-file
+
+# mcp-coder-utils
+
+Shared low-level Python helpers (subprocess, logging, fs) for the mcp-coder family of repos.
+
+Leaf library: no internal dependencies, language-agnostic, safe to import from any MCP server or client in the mcp-coder ecosystem.
+
+## Install
+
+```bash
+pip install mcp-coder-utils
+```
+
+## Development
+
+```bash
+tools\reinstall_local.bat
+```
+
+This creates a local `.venv`, installs the package in editable mode with dev dependencies, and overrides the sibling repos (`mcp-coder`, `mcp-tools-py`, `mcp-workspace`) with their latest GitHub versions.
+
+## Related repos
+
+- [mcp_coder](https://github.com/MarcusJellinghaus/mcp_coder) — CLI client and workflows
+- [mcp-tools-py](https://github.com/MarcusJellinghaus/mcp-tools-py) — MCP server: Python code checks
+- [mcp-workspace](https://github.com/MarcusJellinghaus/mcp-workspace) — MCP server: file operations
+- [mcp-config](https://github.com/MarcusJellinghaus/mcp-config) — MCP client config CLI

mcp_coder_utils-0.1.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+mcp_coder_utils/__init__.py,sha256=zIYS61fxzcuUU2plZeWwo6MSmn84BHwQHOvYmj42nOk,73
+mcp_coder_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_coder_utils/subprocess_runner.py,sha256=SJoZRJ78sFQipLj6Oo2NN7TyU8aEEmOFAczPzxI2ktA,25949
+mcp_coder_utils/subprocess_streaming.py,sha256=pIgXSVSLI7wvYmostD3cVI7jwcjAfFU_4pIF2lU21fQ,6107
+mcp_coder_utils-0.1.2.dist-info/licenses/LICENSE,sha256=hRZqBWHdMOHKnst3xDIqKmPhe-pzCwlBEI9nQHABRkU,1075
+mcp_coder_utils-0.1.2.dist-info/METADATA,sha256=rF-vcqgwkcsftNdZJ5d-Wc9wtgmBQlXtpiVsn8Z8ofw,2418
+mcp_coder_utils-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mcp_coder_utils-0.1.2.dist-info/top_level.txt,sha256=mQ8w7ACfLD2rnarBYUVjYwW1yWqVXFHhzsA46O3PWIg,16
+mcp_coder_utils-0.1.2.dist-info/RECORD,,

mcp_coder_utils-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcp_coder_utils-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcus Jellinghaus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_coder_utils-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcp_coder_utils