"""Run a shell command and return its output."""

import subprocess


def run(command: str, *, timeout: int = 60, cwd: str | None = None) -> dict:
    """Execute a shell command and return the result.

    Args:
        command: The shell command to run.
        timeout: Maximum execution time in seconds. Default: 60.
        cwd: Working directory. Default: current directory.

    Returns:
        dict with keys: stdout, stderr, returncode, command
    """
    result = subprocess.run(
        command,
        shell=True,
        capture_output=True,
        text=True,
        timeout=timeout,
        cwd=cwd,
    )
    return {
        "stdout": result.stdout,
        "stderr": result.stderr,
        "returncode": result.returncode,
        "command": command,
    }
