illusion-code 0.1.0__py3-none-any.whl

illusion/utils/ripgrep.py

@@ -0,0 +1,299 @@
+"""
+ripgrep (rg) 二进制的发现、下载、缓存和执行模块。
+
+核心原则：让 rg 去碰文件系统，Python 只处理结果。
+"""
+
+import os
+import platform
+import shutil
+import sys
+from pathlib import Path
+
+
+class RipgrepNotFoundError(Exception):
+    """rg 不可用时抛出"""
+    pass
+
+
+class RipgrepError(Exception):
+    """rg 执行失败时抛出"""
+    pass
+
+# 平台映射表：平台键 -> (rg 目标三元组, 归档格式)
+PLATFORM_MAP = {
+    "x64-win32": ("x86_64-pc-windows-msvc", "zip"),
+    "arm64-win32": ("aarch64-pc-windows-msvc", "zip"),
+    "x64-darwin": ("x86_64-apple-darwin", "tar.gz"),
+    "arm64-darwin": ("aarch64-apple-darwin", "tar.gz"),
+    "x64-linux": ("x86_64-unknown-linux-musl", "tar.gz"),
+    "arm64-linux": ("aarch64-unknown-linux-gnu", "tar.gz"),
+}
+
+
+def get_platform_key() -> str:
+    """
+    获取当前平台的键名。
+
+    Returns:
+        平台键，如 "x64-win32"、"arm64-darwin"
+    """
+    machine = platform.machine().lower()
+    plat = sys.platform
+
+    # 标准化架构名称
+    if machine in ("x86_64", "amd64"):
+        arch = "x64"
+    elif machine in ("aarch64", "arm64"):
+        arch = "arm64"
+    else:
+        arch = machine
+
+    return f"{arch}-{plat}"
+
+
+def get_rg_binary_name(platform_key: str) -> str:
+    """
+    获取 rg 二进制文件名。
+
+    Args:
+        platform_key: 平台键
+
+    Returns:
+        二进制文件名，Windows 上为 "rg.exe"，其他为 "rg"
+    """
+    if platform_key.endswith("-win32"):
+        return "rg.exe"
+    return "rg"
+
+
+def get_cache_dir() -> str:
+    """
+    获取 rg 缓存目录路径。
+
+    Returns:
+        缓存目录路径：~/.illusion/ripgrep/
+    """
+    return os.path.join(str(Path.home()), ".illusion", "ripgrep")
+
+
+def find_rg_path() -> str:
+    """
+    查找 rg 二进制路径。
+
+    优先级：
+    1. 环境变量 ILLUSION_RIPGREP_PATH
+    2. 本地缓存 ~/.illusion/ripgrep/rg
+    3. 系统 PATH
+
+    Returns:
+        rg 二进制路径
+
+    Raises:
+        RipgrepNotFoundError: rg 不可用时
+    """
+    # 1. 检查环境变量
+    env_path = os.environ.get("ILLUSION_RIPGREP_PATH")
+    if env_path and os.path.exists(env_path):
+        return env_path
+
+    # 2. 检查本地缓存
+    cache_dir = get_cache_dir()
+    platform_key = get_platform_key()
+    binary_name = get_rg_binary_name(platform_key)
+    cache_path = os.path.join(cache_dir, binary_name)
+    if os.path.exists(cache_path):
+        return cache_path
+
+    # 3. 检查系统 PATH
+    system_path = shutil.which("rg")
+    if system_path:
+        return system_path
+
+    # 4. 以上均不可用
+    raise RipgrepNotFoundError(
+        "ripgrep (rg) 不可用。请手动安装 rg 或设置环境变量 ILLUSION_RIPGREP_PATH。"
+        "下载地址：https://github.com/BurntSushi/ripgrep/releases"
+    )
+
+
+# GitHub Releases 下载地址模板
+RG_DOWNLOAD_URL = "https://github.com/BurntSushi/ripgrep/releases/download/14.1.1/{archive}"
+
+
+def extract_zip(zip_path: str, extract_dir: str) -> None:
+    """
+    解压 ZIP 文件到指定目录。
+
+    Args:
+        zip_path: ZIP 文件路径
+        extract_dir: 解压目标目录
+    """
+    import zipfile
+    with zipfile.ZipFile(zip_path, "r") as zf:
+        # 查找 rg.exe 文件
+        for name in zf.namelist():
+            if name.endswith("rg.exe"):
+                # 提取到目标目录
+                zf.extract(name, extract_dir)
+                # 移动到目标目录根目录
+                extracted = os.path.join(extract_dir, name)
+                target = os.path.join(extract_dir, "rg.exe")
+                if extracted != target:
+                    os.rename(extracted, target)
+                break
+
+
+def extract_tar(tar_path: str, extract_dir: str) -> None:
+    """
+    解压 TAR.GZ 文件到指定目录。
+
+    Args:
+        tar_path: TAR.GZ 文件路径
+        extract_dir: 解压目标目录
+    """
+    import tarfile
+    with tarfile.open(tar_path, "r:gz") as tf:
+        # 查找 rg 文件
+        for member in tf.getmembers():
+            if member.name.endswith("/rg") or member.name == "rg":
+                # 提取到目标目录
+                tf.extract(member, extract_dir)
+                # 移动到目标目录根目录
+                extracted = os.path.join(extract_dir, member.name)
+                target = os.path.join(extract_dir, "rg")
+                if extracted != target:
+                    os.rename(extracted, target)
+                break
+
+
+def download_rg() -> str:
+    """
+    下载 rg 二进制到缓存目录。
+
+    Returns:
+        下载后的 rg 二进制路径
+
+    Raises:
+        RipgrepNotFoundError: 下载失败时
+    """
+    import tempfile
+    import urllib.request
+
+    platform_key = get_platform_key()
+    if platform_key not in PLATFORM_MAP:
+        raise RipgrepNotFoundError(f"不支持的平台: {platform_key}")
+
+    target_triple, archive_format = PLATFORM_MAP[platform_key]
+    binary_name = get_rg_binary_name(platform_key)
+    cache_dir = get_cache_dir()
+
+    # 创建缓存目录
+    os.makedirs(cache_dir, exist_ok=True)
+
+    # 构建下载 URL
+    if archive_format == "zip":
+        archive_name = f"ripgrep-14.1.1-{target_triple}.zip"
+    else:
+        archive_name = f"ripgrep-14.1.1-{target_triple}.tar.gz"
+    url = RG_DOWNLOAD_URL.format(archive=archive_name)
+
+    # 下载文件
+    try:
+        with tempfile.NamedTemporaryFile(delete=False, suffix=f".{archive_format}") as tmp:
+            tmp_path = tmp.name
+            urllib.request.urlretrieve(url, tmp_path)
+    except Exception as e:
+        raise RipgrepNotFoundError(f"下载 rg 失败: {e}")
+
+    try:
+        # 解压文件
+        if archive_format == "zip":
+            extract_zip(tmp_path, cache_dir)
+        else:
+            extract_tar(tmp_path, cache_dir)
+
+        # 设置权限（非 Windows）
+        rg_path = os.path.join(cache_dir, binary_name)
+        if sys.platform != "win32":
+            os.chmod(rg_path, 0o755)
+
+        return rg_path
+    finally:
+        # 清理临时文件
+        if os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+
+
+async def ensure_ripgrep() -> str:
+    """
+    确保 rg 可用，返回二进制路径。
+
+    优先级：env > cache > PATH > download
+
+    Returns:
+        rg 二进制路径
+
+    Raises:
+        RipgrepNotFoundError: rg 不可用时
+    """
+    try:
+        return find_rg_path()
+    except RipgrepNotFoundError:
+        # 尝试下载
+        return download_rg()
+
+
+async def run_rg(args: list[str], cwd: str | None = None,
+                 timeout: float = 20.0) -> tuple[str, str, int]:
+    """
+    执行 rg 命令。
+
+    Args:
+        args: rg 命令行参数
+        cwd: 工作目录
+        timeout: 超时时间（秒）
+
+    Returns:
+        (stdout, stderr, returncode) 元组
+
+    Raises:
+        RipgrepError: 执行失败或超时时
+    """
+    import asyncio
+    import subprocess
+
+    rg_path = await ensure_ripgrep()
+
+    # 构建完整命令
+    cmd = [rg_path] + args
+
+    try:
+        # 创建子进程
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd,
+            # Windows 特殊处理
+            creationflags=subprocess.CREATE_NO_WINDOW if sys.platform == "win32" else 0,
+        )
+
+        # 等待完成，带超时
+        try:
+            stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                process.communicate(), timeout=timeout
+            )
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.wait()
+            raise RipgrepError(f"rg 执行超时（{timeout}秒）")
+
+        stdout = stdout_bytes.decode("utf-8", errors="replace")
+        stderr = stderr_bytes.decode("utf-8", errors="replace")
+        return stdout, stderr, process.returncode
+
+    except RipgrepError:
+        raise
+    except Exception as e:
+        raise RipgrepError(f"rg 执行失败: {e}")

illusion/utils/shell.py

@@ -0,0 +1,248 @@
+"""
+Shell 和子进程辅助函数模块
+=====================
+
+本模块提供 shell 命令执行和子进程创建的跨平台支持功能。
+
+主要功能：
+    - 解析适合当前平台的最佳 shell 命令
+    - 创建带有沙箱支持的异步子进程
+    - 在 Windows 上智能查找可用的 bash 可执行文件
+
+函数说明：
+    - resolve_shell_command: 返回当前平台的最佳 shell 命令 argv
+    - create_shell_subprocess: 创建带有沙箱支持的 shell 子进程
+    - _resolve_windows_bash: 解析 Windows 上可用的 bash 可执行文件
+
+使用示例：
+    >>> from illusion.utils import resolve_shell_command
+    
+    >>> # 获取当前平台的 shell 命令
+    >>> argv = resolve_shell_command("echo hello")
+    >>> print(argv)  # ['bash', '-lc', 'echo hello']
+    
+    >>> # 创建子进程
+    >>> process = await create_shell_subprocess("ls", cwd="/tmp")
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import subprocess
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+
+from illusion.config import Settings, load_settings
+from illusion.platforms import PlatformName, get_platform
+from illusion.sandbox import wrap_command_for_sandbox
+
+
+def resolve_shell_command(
+    command: str,
+    *,
+    platform_name: PlatformName | None = None,
+) -> list[str]:
+    """
+    解析适合当前平台的最佳 shell 命令
+    
+    根据平台类型自动选择最优的 shell 解释器：
+    - Windows: 优先 WSL bash，其次 PowerShell，最后 cmd.exe
+    - Unix/Linux/macOS: 优先 bash，其次 sh
+    
+    Args:
+        command: 要执行的 shell 命令字符串
+        platform_name: 指定平台名称，默认自动检测
+    
+    Returns:
+        list[str]: shell 命令的 argv 列表，第一个元素为可执行文件路径
+    
+    使用示例：
+        >>> argv = resolve_shell_command("ls -la")
+        >>> argv  # ['bash', '-lc', 'ls -la']
+    """
+    resolved_platform = platform_name or get_platform()
+    # Windows 平台优先尝试 WSL bash
+    if resolved_platform == "windows":
+        bash = _resolve_windows_bash()
+        if bash:
+            return [bash, "-lc", command]
+        powershell = shutil.which("pwsh") or shutil.which("powershell")
+        if powershell:
+            return [powershell, "-NoLogo", "-NoProfile", "-Command", command]
+        return [shutil.which("cmd.exe") or "cmd.exe", "/d", "/s", "/c", command]
+
+    # Unix 系统优先使用 bash
+    bash = shutil.which("bash")
+    if bash:
+        return [bash, "-lc", command]
+    shell = shutil.which("sh") or os.environ.get("SHELL") or "/bin/sh"
+    return [shell, "-lc", command]
+
+
+async def create_shell_subprocess(
+    command: str,
+    *,
+    cwd: str | Path,
+    settings: Settings | None = None,
+    disable_sandbox: bool = False,
+    stdin: int | None = None,
+    stdout: int | None = None,
+    stderr: int | None = None,
+    env: Mapping[str, str] | None = None,
+) -> asyncio.subprocess.Process:
+    """
+    创建带有平台感知和沙箱支持的 shell 子进程
+    
+    自动解析适合平台的 shell 命令，并应用沙箱包装（如果启用）。
+    
+    Args:
+        command: 要执行的 shell 命令
+        cwd: 工作目录
+        settings: 配置对象，默认自动加载
+        disable_sandbox: 是否绕过沙箱包装
+        stdin: 标准输入文件描述符
+        stdout: 标准输出文件描述符
+        stderr: 标准错误文件描述符
+        environment: 环境变量映射
+    
+    Returns:
+        asyncio.subprocess.Process: 异步子进程对象
+    
+    使用示例：
+        >>> process = await create_shell_subprocess("ls", cwd="/tmp")
+        >>> await process.wait()
+    """
+    resolved_settings = settings or load_settings()
+    argv = resolve_shell_command(command)
+    # 使用沙箱包装命令（如果配置启用且未显式禁用）
+    if disable_sandbox:
+        cleanup_path = None
+    else:
+        argv, cleanup_path = wrap_command_for_sandbox(argv, settings=resolved_settings)
+
+    try:
+        kwargs: dict = {}
+        if sys.platform == "win32":
+            kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
+        process = await asyncio.create_subprocess_exec(
+            *argv,
+            cwd=str(Path(cwd).resolve()),
+            stdin=stdin,
+            stdout=stdout,
+            stderr=stderr,
+            env=dict(env) if env is not None else None,
+            **kwargs,
+        )
+    except Exception:
+        # 发生异常时清理沙箱临时文件
+        if cleanup_path is not None:
+            cleanup_path.unlink(missing_ok=True)
+        raise
+
+    # 进程结束后异步清理沙箱临时文件
+    if cleanup_path is not None:
+        asyncio.create_task(_cleanup_after_exit(process, cleanup_path))
+    return process
+
+
+async def _cleanup_after_exit(process: asyncio.subprocess.Process, cleanup_path: Path) -> None:
+    """
+    进程退出后清理沙箱临时文件
+    
+    Args:
+        process: 要监控的子进程
+        cleanup_path: 需要清理的文件路径
+    """
+    try:
+        await process.wait()
+    finally:
+        cleanup_path.unlink(missing_ok=True)
+
+
+def _resolve_windows_bash() -> str | None:
+    """
+    解析 Windows 上可用的 bash 可执行文件
+    
+    忽略传统的 Windows 系统 shim（C:\\Windows\\System32\\bash.exe），
+    该位置可能在未配置 WSL 的机器上失败或输出无法读取的内容。
+    
+    解析优先级：
+        1. ILLUSION_CODE_GIT_BASH_PATH 环境变量覆盖
+        2. 通过 PATH 找到的 bash（排除 system32 shim）
+        3. 从 git 可执行文件位置解析 bash
+        4. 在已知的 Git for Windows 安装路径中查找
+    
+    Returns:
+        str | None: bash 可执行文件路径，未找到则返回 None
+    """
+    # 1. 通过环境变量显式指定
+    env_bash = os.environ.get("ILLUSION_CODE_GIT_BASH_PATH")
+    if env_bash and Path(env_bash).exists():
+        return env_bash
+
+    # 2. PATH 上的 bash（跳过传统的 system32 shim）
+    bash = shutil.which("bash")
+    if bash and not _is_windows_bash_shim(bash):
+        return bash
+
+    # 3. 从 git 可执行文件位置解析 bash
+    git_path = shutil.which("git")
+    if git_path:
+        # git.exe 通常位于 <Git-Root>\cmd\git.exe 或 <Git-Root>\bin\git.exe
+        # bash.exe 位于 <Git-Root>\bin\bash.exe
+        git_root = Path(git_path).resolve().parent.parent
+        bash_via_git = git_root / "bin" / "bash.exe"
+        if bash_via_git.exists():
+            return str(bash_via_git)
+
+    # 4. 在已知的 Git for Windows 安装路径中搜索
+    for candidate in _windows_git_bash_candidates():
+        if candidate.exists():
+            return str(candidate)
+
+    return None
+
+
+def _windows_git_bash_candidates() -> list[Path]:
+    """
+    生成已知的 Git for Windows 安装路径候选列表
+    
+    在常见的 Program Files 目录中查找 Git 安装路径。
+    
+    Returns:
+        list[Path]: 可能的 bash.exe 路径列表
+    """
+    roots: list[str] = []
+    for key in ("ProgramFiles", "ProgramFiles(x86)", "LocalAppData"):
+        value = os.environ.get(key)
+        if value:
+            roots.append(value)
+
+    candidates: list[Path] = []
+    for root in roots:
+        base = Path(root)
+        candidates.append(base / "Git" / "bin" / "bash.exe")
+        candidates.append(base / "Git" / "usr" / "bin" / "bash.exe")
+        candidates.append(base / "Programs" / "Git" / "bin" / "bash.exe")
+        candidates.append(base / "Programs" / "Git" / "usr" / "bin" / "bash.exe")
+    return candidates
+
+
+def _is_windows_bash_shim(path: str) -> bool:
+    """
+    检查路径是否为 Windows system32 bash shim
+    
+    判断给定路径是否为传统的 Windows system32 bash 替身（shim），
+    这是一个空壳程序，不提供真正的 bash 功能。
+    
+    Args:
+        path: 要检查的可执行文件路径
+    
+    Returns:
+        bool: 是否为 system32 shim
+    """
+    normalized = path.replace("/", "\\").lower()
+    return normalized.endswith("\\windows\\system32\\bash.exe")