arch-ops-server 3.0.1__py3-none-any.whl

arch_ops_server/system.py

@@ -0,0 +1,307 @@
+# SPDX-License-Identifier: GPL-3.0-only OR MIT
+"""
+System diagnostics and information module.
+Provides system health checks, disk space monitoring, and service status.
+"""
+
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Dict, Any, List
+
+from .utils import (
+    IS_ARCH,
+    run_command,
+    create_error_response,
+    check_command_exists
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def get_system_info() -> Dict[str, Any]:
+    """
+    Get core system information.
+
+    Returns:
+        Dict with kernel, architecture, hostname, uptime, memory info
+    """
+    logger.info("Gathering system information")
+
+    info = {}
+
+    try:
+        # Kernel version
+        exit_code, stdout, _ = await run_command(["uname", "-r"], timeout=5, check=False)
+        if exit_code == 0:
+            info["kernel"] = stdout.strip()
+
+        # Architecture
+        exit_code, stdout, _ = await run_command(["uname", "-m"], timeout=5, check=False)
+        if exit_code == 0:
+            info["architecture"] = stdout.strip()
+
+        # Hostname
+        exit_code, stdout, _ = await run_command(["hostname"], timeout=5, check=False)
+        if exit_code == 0:
+            info["hostname"] = stdout.strip()
+
+        # Uptime
+        exit_code, stdout, _ = await run_command(["uptime", "-p"], timeout=5, check=False)
+        if exit_code == 0:
+            info["uptime"] = stdout.strip()
+
+        # Memory info from /proc/meminfo
+        try:
+            meminfo_path = Path("/proc/meminfo")
+            if meminfo_path.exists():
+                with open(meminfo_path, "r") as f:
+                    meminfo = f.read()
+
+                # Parse memory values
+                mem_total_match = re.search(r"MemTotal:\s+(\d+)", meminfo)
+                mem_available_match = re.search(r"MemAvailable:\s+(\d+)", meminfo)
+
+                if mem_total_match:
+                    info["memory_total_kb"] = int(mem_total_match.group(1))
+                    info["memory_total_mb"] = int(mem_total_match.group(1)) // 1024
+
+                if mem_available_match:
+                    info["memory_available_kb"] = int(mem_available_match.group(1))
+                    info["memory_available_mb"] = int(mem_available_match.group(1)) // 1024
+        except Exception as e:
+            logger.warning(f"Failed to read memory info: {e}")
+
+        info["is_arch_linux"] = IS_ARCH
+
+        logger.info("Successfully gathered system information")
+        return info
+
+    except Exception as e:
+        logger.error(f"Failed to gather system info: {e}")
+        return create_error_response(
+            "SystemInfoError",
+            f"Failed to gather system information: {str(e)}"
+        )
+
+
+async def check_disk_space() -> Dict[str, Any]:
+    """
+    Check disk space for critical paths.
+
+    Returns:
+        Dict with disk usage for /, /home, /var, /var/cache/pacman/pkg
+    """
+    logger.info("Checking disk space")
+
+    paths_to_check = ["/", "/home", "/var"]
+
+    if IS_ARCH:
+        paths_to_check.append("/var/cache/pacman/pkg")
+
+    disk_info = {}
+
+    try:
+        for path in paths_to_check:
+            if not Path(path).exists():
+                continue
+
+            exit_code, stdout, _ = await run_command(
+                ["df", "-h", path],
+                timeout=5,
+                check=False
+            )
+
+            if exit_code == 0:
+                lines = stdout.strip().split('\n')
+                if len(lines) >= 2:
+                    # Parse df output
+                    parts = lines[1].split()
+                    if len(parts) >= 5:
+                        disk_info[path] = {
+                            "size": parts[1],
+                            "used": parts[2],
+                            "available": parts[3],
+                            "use_percent": parts[4],
+                            "mounted_on": parts[5] if len(parts) > 5 else path
+                        }
+
+                        # Check if space is critically low
+                        use_pct = int(parts[4].rstrip('%'))
+                        if use_pct > 90:
+                            disk_info[path]["warning"] = "Critical: Less than 10% free"
+                        elif use_pct > 80:
+                            disk_info[path]["warning"] = "Low: Less than 20% free"
+
+        logger.info(f"Checked disk space for {len(disk_info)} paths")
+
+        return {
+            "disk_usage": disk_info,
+            "paths_checked": len(disk_info)
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to check disk space: {e}")
+        return create_error_response(
+            "DiskCheckError",
+            f"Failed to check disk space: {str(e)}"
+        )
+
+
+async def get_pacman_cache_stats() -> Dict[str, Any]:
+    """
+    Analyze pacman package cache.
+
+    Returns:
+        Dict with cache size, package count, statistics
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Pacman cache analysis is only available on Arch Linux"
+        )
+
+    logger.info("Analyzing pacman cache")
+
+    cache_dir = Path("/var/cache/pacman/pkg")
+
+    try:
+        if not cache_dir.exists():
+            return create_error_response(
+                "NotFound",
+                "Pacman cache directory not found"
+            )
+
+        # Count packages
+        pkg_files = list(cache_dir.glob("*.pkg.tar.*"))
+        pkg_count = len(pkg_files)
+
+        # Calculate total size
+        total_size = sum(f.stat().st_size for f in pkg_files)
+        total_size_mb = total_size / (1024 * 1024)
+        total_size_gb = total_size_mb / 1024
+
+        logger.info(f"Cache: {pkg_count} packages, {total_size_gb:.2f} GB")
+
+        return {
+            "cache_dir": str(cache_dir),
+            "package_count": pkg_count,
+            "total_size_bytes": total_size,
+            "total_size_mb": round(total_size_mb, 2),
+            "total_size_gb": round(total_size_gb, 2)
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to analyze cache: {e}")
+        return create_error_response(
+            "CacheAnalysisError",
+            f"Failed to analyze pacman cache: {str(e)}"
+        )
+
+
+async def check_failed_services() -> Dict[str, Any]:
+    """
+    Detect failed systemd services.
+
+    Returns:
+        Dict with list of failed services
+    """
+    if not check_command_exists("systemctl"):
+        return create_error_response(
+            "NotSupported",
+            "systemctl not available (systemd-based system required)"
+        )
+
+    logger.info("Checking for failed services")
+
+    try:
+        exit_code, stdout, _ = await run_command(
+            ["systemctl", "--failed", "--no-pager"],
+            timeout=10,
+            check=False
+        )
+
+        # Parse output
+        failed_services = []
+        lines = stdout.strip().split('\n')
+
+        for line in lines:
+            # Skip header and footer lines
+            if line.startswith('●') or line.startswith('UNIT'):
+                continue
+            if 'loaded units listed' in line.lower():
+                continue
+
+            # Parse service line
+            parts = line.split()
+            if parts and parts[0].endswith('.service'):
+                failed_services.append({
+                    "unit": parts[0],
+                    "load": parts[1] if len(parts) > 1 else "",
+                    "active": parts[2] if len(parts) > 2 else "",
+                    "sub": parts[3] if len(parts) > 3 else "",
+                })
+
+        logger.info(f"Found {len(failed_services)} failed services")
+
+        return {
+            "failed_count": len(failed_services),
+            "failed_services": failed_services,
+            "all_ok": len(failed_services) == 0
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to check services: {e}")
+        return create_error_response(
+            "ServiceCheckError",
+            f"Failed to check failed services: {str(e)}"
+        )
+
+
+async def get_boot_logs(lines: int = 100) -> Dict[str, Any]:
+    """
+    Retrieve recent boot logs.
+
+    Args:
+        lines: Number of lines to retrieve
+
+    Returns:
+        Dict with boot log contents
+    """
+    if not check_command_exists("journalctl"):
+        return create_error_response(
+            "NotSupported",
+            "journalctl not available (systemd-based system required)"
+        )
+
+    logger.info(f"Retrieving {lines} lines of boot logs")
+
+    try:
+        exit_code, stdout, stderr = await run_command(
+            ["journalctl", "-b", "-n", str(lines), "--no-pager"],
+            timeout=15,
+            check=False
+        )
+
+        if exit_code != 0:
+            return create_error_response(
+                "CommandError",
+                f"Failed to retrieve boot logs: {stderr}"
+            )
+
+        log_lines = stdout.strip().split('\n')
+
+        logger.info(f"Retrieved {len(log_lines)} lines of boot logs")
+
+        return {
+            "line_count": len(log_lines),
+            "logs": log_lines
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to get boot logs: {e}")
+        return create_error_response(
+            "LogRetrievalError",
+            f"Failed to retrieve boot logs: {str(e)}"
+        )

arch_ops_server/utils.py

@@ -0,0 +1,313 @@
+# SPDX-License-Identifier: GPL-3.0-only OR MIT
+"""
+Utility functions for Arch Linux MCP Server.
+Provides platform detection, subprocess execution, and error handling.
+"""
+
+import asyncio
+import logging
+import os
+import platform
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+# Configure logging to stderr (STDIO server requirement)
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[logging.StreamHandler()]
+)
+
+logger = logging.getLogger(__name__)
+
+
+def is_arch_linux() -> bool:
+    """
+    Detect if the current system is Arch Linux.
+    
+    Checks for:
+    1. /etc/arch-release file existence
+    2. Platform identification
+    
+    Returns:
+        bool: True if running on Arch Linux, False otherwise
+    """
+    # Check for Arch release file
+    if Path("/etc/arch-release").exists():
+        logger.info("Detected Arch Linux via /etc/arch-release")
+        return True
+    
+    # Fallback check via platform info
+    try:
+        with open("/etc/os-release", "r") as f:
+            content = f.read()
+            if "Arch Linux" in content or "ID=arch" in content:
+                logger.info("Detected Arch Linux via /etc/os-release")
+                return True
+    except FileNotFoundError:
+        pass
+    
+    logger.info("Not running on Arch Linux")
+    return False
+
+
+# Cache the result since it won't change during runtime
+IS_ARCH = is_arch_linux()
+
+
+async def run_command(
+    cmd: list[str],
+    timeout: int = 10,
+    check: bool = True,
+    skip_sudo_check: bool = False
+) -> tuple[int, str, str]:
+    """
+    Execute a command asynchronously with timeout protection.
+    
+    Note: For sudo commands, stdin is properly connected to allow password input
+    if passwordless sudo is not configured.
+    
+    Args:
+        cmd: Command and arguments as list
+        timeout: Timeout in seconds (default: 10)
+        check: If True, raise exception on non-zero exit code
+        skip_sudo_check: If True, skip the early sudo password check (for testing)
+    
+    Returns:
+        Tuple of (exit_code, stdout, stderr)
+    
+    Raises:
+        asyncio.TimeoutError: If command exceeds timeout
+        RuntimeError: If check=True and command fails
+    """
+    logger.debug(f"Executing command: {' '.join(cmd)}")
+    
+    # Check if this is a sudo command and if password is cached
+    is_sudo_command = cmd and cmd[0] == "sudo"
+    if is_sudo_command and not skip_sudo_check:
+        # Test if sudo password is cached (non-interactive mode)
+        test_cmd = ["sudo", "-n", "true"]
+        try:
+            test_process = await asyncio.create_subprocess_exec(
+                *test_cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE
+            )
+            await test_process.communicate()
+            password_cached = test_process.returncode == 0
+            logger.debug(f"Sudo password cached: {password_cached}")
+            
+            if not password_cached:
+                logger.warning("Sudo password is required but not cached. "
+                              "Please run 'sudo pacman -S <package>' manually in the terminal.")
+                return (
+                    1,
+                    "",
+                    "Sudo password required. Please configure passwordless sudo for pacman/paru, "
+                    "or run the installation command manually in your terminal."
+                )
+        except Exception as e:
+            logger.warning(f"Could not check sudo status: {e}")
+            password_cached = False
+    else:
+        password_cached = True
+    
+    try:
+        # Attach stdin to subprocess for commands that might need input
+        # Use asyncio.subprocess.PIPE to allow stdin interaction
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            stdin=asyncio.subprocess.PIPE if is_sudo_command else None
+        )
+        
+        # Communicate with the process
+        # For sudo commands, this allows password input if needed
+        stdout, stderr = await asyncio.wait_for(
+            process.communicate(),
+            timeout=timeout
+        )
+        
+        exit_code = process.returncode
+        stdout_str = stdout.decode('utf-8', errors='replace') if stdout else ""
+        stderr_str = stderr.decode('utf-8', errors='replace') if stderr else ""
+        
+        logger.debug(f"Command exit code: {exit_code}")
+        
+        if check and exit_code != 0:
+            raise RuntimeError(
+                f"Command failed with exit code {exit_code}: {stderr_str}"
+            )
+        
+        return exit_code, stdout_str, stderr_str
+        
+    except asyncio.TimeoutError:
+        logger.error(f"Command timed out after {timeout}s: {' '.join(cmd)}")
+        raise
+    except Exception as e:
+        logger.error(f"Command execution failed: {e}")
+        raise
+
+
+def add_aur_warning(data: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Wrap AUR data with prominent safety warning.
+    
+    The AUR contains user-produced content that may be outdated,
+    broken, or malicious. Always inspect PKGBUILDs before installation.
+    
+    Args:
+        data: Original AUR response data
+    
+    Returns:
+        Dict with added warning metadata
+    """
+    return {
+        "warning": (
+            "⚠️  AUR PACKAGE WARNING ⚠️\n"
+            "AUR packages are USER-PRODUCED content and are not officially supported.\n"
+            "These packages may be outdated, broken, or even malicious.\n"
+            "ALWAYS review the PKGBUILD and other files before installing.\n"
+            "Use at your own risk."
+        ),
+        "data": data
+    }
+
+
+def create_error_response(
+    error_type: str,
+    message: str,
+    details: Optional[str] = None,
+    suggest_wiki_search: bool = True
+) -> Dict[str, Any]:
+    """
+    Create a structured error response with Wiki suggestions.
+    
+    Args:
+        error_type: Type of error (e.g., "NetworkError", "NotFound")
+        message: Human-readable error message
+        details: Optional additional details
+        suggest_wiki_search: Whether to suggest related Wiki searches (default: True)
+    
+    Returns:
+        Structured error dict with Wiki suggestions
+    """
+    response = {
+        "error": True,
+        "type": error_type,
+        "message": message
+    }
+    
+    if details:
+        response["details"] = details
+    
+    # Add Wiki suggestions for common error types
+    if suggest_wiki_search:
+        wiki_suggestions = _get_wiki_suggestions_for_error(error_type, message)
+        if wiki_suggestions:
+            response["wiki_suggestions"] = wiki_suggestions
+            response["help_text"] = (
+                "💡 Search the Arch Wiki for these topics to find solutions. "
+                "Use the search_archwiki tool with these keywords."
+            )
+    
+    logger.error(f"{error_type}: {message}")
+    
+    return response
+
+
+def _get_wiki_suggestions_for_error(error_type: str, message: str) -> list[str]:
+    """
+    Generate relevant Arch Wiki search suggestions based on error type.
+    
+    Args:
+        error_type: Type of error
+        message: Error message
+    
+    Returns:
+        List of suggested Wiki search terms
+    """
+    suggestions = []
+    message_lower = message.lower()
+    
+    # Map error types to Wiki topics
+    error_wiki_map = {
+        "NotFound": ["Package management", "AUR"],
+        "TimeoutError": ["Network configuration", "Mirrors"],
+        "HTTPError": ["Network configuration", "Proxy"],
+        "CommandNotFound": ["Pacman", "System maintenance"],
+        "NotSupported": ["Installation guide", "System requirements"],
+        "RateLimitError": ["AUR", "Mirror"],
+    }
+    
+    # Add general suggestions based on error type
+    if error_type in error_wiki_map:
+        suggestions.extend(error_wiki_map[error_type])
+    
+    # Add context-specific suggestions based on message keywords
+    keyword_map = {
+        "pacman": ["Pacman", "Pacman/Rosetta"],
+        "package": ["Package management", "Official repositories"],
+        "dependency": ["Dependency", "Package management"],
+        "mirror": ["Mirrors", "Reflector"],
+        "network": ["Network configuration", "Systemd-networkd"],
+        "update": ["System maintenance", "Pacman#Upgrading packages"],
+        "gpg": ["Pacman/Package signing", "GnuPG"],
+        "disk": ["File systems", "Partitioning"],
+        "boot": ["Boot process", "Arch boot process"],
+        "kernel": ["Kernel", "Kernel modules"],
+        "driver": ["Kernel modules", "Xorg"],
+        "graphics": ["Xorg", "NVIDIA", "AMD"],
+    }
+    
+    for keyword, topics in keyword_map.items():
+        if keyword in message_lower:
+            suggestions.extend(topics)
+    
+    # Remove duplicates while preserving order
+    seen = set()
+    unique_suggestions = []
+    for suggestion in suggestions:
+        if suggestion not in seen:
+            seen.add(suggestion)
+            unique_suggestions.append(suggestion)
+    
+    return unique_suggestions[:5]  # Limit to top 5 suggestions
+
+
+def check_command_exists(command: str) -> bool:
+    """
+    Check if a command exists in the system PATH.
+    
+    Args:
+        command: Command name to check
+    
+    Returns:
+        bool: True if command exists, False otherwise
+    """
+    try:
+        result = os.system(f"which {command} > /dev/null 2>&1")
+        return result == 0
+    except Exception:
+        return False
+
+
+def get_aur_helper() -> Optional[str]:
+    """
+    Detect available AUR helper with priority: paru > yay.
+    
+    Returns:
+        str: Name of available AUR helper ('paru' or 'yay'), or None if neither exists
+    """
+    # Check in priority order
+    if check_command_exists("paru"):
+        logger.info("Found AUR helper: paru")
+        return "paru"
+    elif check_command_exists("yay"):
+        logger.info("Found AUR helper: yay")
+        return "yay"
+    else:
+        logger.warning("No AUR helper found (paru or yay)")
+        return None
+