"""Shell command execution with timeout.

Ported from net.i2p.util.ShellCommand.
"""

from __future__ import annotations

import subprocess


def shell_command(
    cmd: str, timeout: float | None = None
) -> tuple[int, str, str]:
    """Execute a shell command.

    Returns (return_code, stdout, stderr).
    On timeout, returns (-1, '', 'timeout').
    """
    try:
        result = subprocess.run(
            cmd,
            shell=True,  # nosec B602 — ported from Java ShellCommand; callers pass trusted commands
            capture_output=True,
            text=True,
            timeout=timeout,
        )
        return result.returncode, result.stdout, result.stderr
    except subprocess.TimeoutExpired:
        return -1, "", "timeout"
    except OSError as e:
        return -1, "", str(e)