arch-ops-server 0.1.3__py3-none-any.whl → 3.0.0__py3-none-any.whl

arch_ops_server/pacman.py

@@ -318,3 +318,988 @@ def _parse_checkupdates_output(output: str) -> List[Dict[str, str]]:
     
     return updates
 
+
+async def remove_package(
+    package_name: str,
+    remove_dependencies: bool = False,
+    force: bool = False
+) -> Dict[str, Any]:
+    """
+    Remove a single package from the system.
+
+    Args:
+        package_name: Name of package to remove
+        remove_dependencies: If True, remove unneeded dependencies (pacman -Rs)
+        force: If True, force removal ignoring dependencies (pacman -Rdd)
+
+    Returns:
+        Dict with removal status and information
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Package removal is only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    logger.info(f"Removing package: {package_name} (deps={remove_dependencies}, force={force})")
+
+    # Build command based on options
+    cmd = ["sudo", "pacman"]
+
+    if force:
+        cmd.extend(["-Rdd"])  # Force remove, skip dependency checks
+    elif remove_dependencies:
+        cmd.extend(["-Rs"])  # Remove with unused dependencies
+    else:
+        cmd.extend(["-R"])  # Basic removal
+
+    cmd.extend(["--noconfirm", package_name])
+
+    try:
+        exit_code, stdout, stderr = await run_command(
+            cmd,
+            timeout=60,  # Longer timeout for removal
+            check=False,
+            skip_sudo_check=True  # We're using sudo in the command
+        )
+
+        if exit_code != 0:
+            logger.error(f"Package removal failed: {stderr}")
+            return create_error_response(
+                "RemovalError",
+                f"Failed to remove {package_name}: {stderr}",
+                f"Exit code: {exit_code}"
+            )
+
+        logger.info(f"Successfully removed {package_name}")
+
+        return {
+            "success": True,
+            "package": package_name,
+            "removed_dependencies": remove_dependencies,
+            "output": stdout
+        }
+
+    except Exception as e:
+        logger.error(f"Package removal failed with exception: {e}")
+        return create_error_response(
+            "RemovalError",
+            f"Failed to remove {package_name}: {str(e)}"
+        )
+
+
+async def remove_packages_batch(
+    package_names: List[str],
+    remove_dependencies: bool = False
+) -> Dict[str, Any]:
+    """
+    Remove multiple packages in a single transaction.
+
+    Args:
+        package_names: List of package names to remove
+        remove_dependencies: If True, remove unneeded dependencies
+
+    Returns:
+        Dict with removal status
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Package removal is only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    if not package_names:
+        return create_error_response(
+            "ValidationError",
+            "No packages specified for removal"
+        )
+
+    logger.info(f"Batch removing {len(package_names)} packages (deps={remove_dependencies})")
+
+    # Build command
+    cmd = ["sudo", "pacman"]
+
+    if remove_dependencies:
+        cmd.extend(["-Rs"])
+    else:
+        cmd.extend(["-R"])
+
+    cmd.extend(["--noconfirm"] + package_names)
+
+    try:
+        exit_code, stdout, stderr = await run_command(
+            cmd,
+            timeout=120,  # Longer timeout for batch removal
+            check=False,
+            skip_sudo_check=True
+        )
+
+        if exit_code != 0:
+            logger.error(f"Batch removal failed: {stderr}")
+            return create_error_response(
+                "RemovalError",
+                f"Failed to remove packages: {stderr}",
+                f"Exit code: {exit_code}"
+            )
+
+        logger.info(f"Successfully removed {len(package_names)} packages")
+
+        return {
+            "success": True,
+            "package_count": len(package_names),
+            "packages": package_names,
+            "removed_dependencies": remove_dependencies,
+            "output": stdout
+        }
+
+    except Exception as e:
+        logger.error(f"Batch removal failed with exception: {e}")
+        return create_error_response(
+            "RemovalError",
+            f"Failed to remove packages: {str(e)}"
+        )
+
+
+async def list_orphan_packages() -> Dict[str, Any]:
+    """
+    List all orphaned packages (dependencies no longer required).
+
+    Returns:
+        Dict with list of orphan packages
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Orphan package detection is only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    logger.info("Listing orphan packages")
+
+    try:
+        exit_code, stdout, stderr = await run_command(
+            ["pacman", "-Qtdq"],
+            timeout=10,
+            check=False
+        )
+
+        # Exit code 1 with no output means no orphans
+        if exit_code == 1 and not stdout.strip():
+            logger.info("No orphan packages found")
+            return {
+                "orphan_count": 0,
+                "orphans": []
+            }
+
+        if exit_code != 0:
+            logger.error(f"Failed to list orphans: {stderr}")
+            return create_error_response(
+                "CommandError",
+                f"Failed to list orphan packages: {stderr}",
+                f"Exit code: {exit_code}"
+            )
+
+        # Parse output - one package per line
+        orphans = [pkg.strip() for pkg in stdout.strip().split('\n') if pkg.strip()]
+
+        logger.info(f"Found {len(orphans)} orphan packages")
+
+        return {
+            "orphan_count": len(orphans),
+            "orphans": orphans
+        }
+
+    except Exception as e:
+        logger.error(f"Orphan listing failed with exception: {e}")
+        return create_error_response(
+            "CommandError",
+            f"Failed to list orphan packages: {str(e)}"
+        )
+
+
+async def remove_orphans(dry_run: bool = True, exclude: Optional[List[str]] = None) -> Dict[str, Any]:
+    """
+    Remove all orphaned packages.
+
+    Args:
+        dry_run: If True, show what would be removed without actually removing
+        exclude: List of packages to exclude from removal
+
+    Returns:
+        Dict with removal status
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Orphan removal is only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    # First, get list of orphans
+    orphans_result = await list_orphan_packages()
+
+    if orphans_result.get("error"):
+        return orphans_result
+
+    orphans = orphans_result.get("orphans", [])
+
+    if not orphans:
+        return {
+            "removed_count": 0,
+            "packages": [],
+            "message": "No orphan packages to remove"
+        }
+
+    # Apply exclusions if provided
+    if exclude:
+        orphans = [pkg for pkg in orphans if pkg not in exclude]
+        if not orphans:
+            return {
+                "removed_count": 0,
+                "packages": [],
+                "message": "All orphan packages are in exclusion list"
+            }
+
+    logger.info(f"Removing {len(orphans)} orphan packages (dry_run={dry_run})")
+
+    if dry_run:
+        return {
+            "dry_run": True,
+            "would_remove_count": len(orphans),
+            "packages": orphans,
+            "message": "This is a dry run. No packages were removed."
+        }
+
+    try:
+        # Remove orphans using pacman -Rns
+        cmd = ["sudo", "pacman", "-Rns", "--noconfirm"] + orphans
+
+        exit_code, stdout, stderr = await run_command(
+            cmd,
+            timeout=120,
+            check=False,
+            skip_sudo_check=True
+        )
+
+        if exit_code != 0:
+            logger.error(f"Orphan removal failed: {stderr}")
+            return create_error_response(
+                "RemovalError",
+                f"Failed to remove orphan packages: {stderr}",
+                f"Exit code: {exit_code}"
+            )
+
+        logger.info(f"Successfully removed {len(orphans)} orphan packages")
+
+        return {
+            "success": True,
+            "removed_count": len(orphans),
+            "packages": orphans,
+            "output": stdout
+        }
+
+    except Exception as e:
+        logger.error(f"Orphan removal failed with exception: {e}")
+        return create_error_response(
+            "RemovalError",
+            f"Failed to remove orphan packages: {str(e)}"
+        )
+
+
+async def find_package_owner(file_path: str) -> Dict[str, Any]:
+    """
+    Find which package owns a specific file.
+
+    Args:
+        file_path: Absolute path to file
+
+    Returns:
+        Dict with package owner information
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Package ownership queries are only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    logger.info(f"Finding owner of file: {file_path}")
+
+    try:
+        exit_code, stdout, stderr = await run_command(
+            ["pacman", "-Qo", file_path],
+            timeout=5,
+            check=False
+        )
+
+        if exit_code != 0:
+            logger.info(f"No package owns {file_path}")
+            return create_error_response(
+                "NotFound",
+                f"No package owns this file: {file_path}",
+                stderr
+            )
+
+        # Parse output: "/path/to/file is owned by package 1.0-1"
+        match = re.search(r'is owned by (\S+)\s+(\S+)', stdout)
+        if match:
+            package_name = match.group(1)
+            version = match.group(2)
+
+            logger.info(f"File {file_path} is owned by {package_name} {version}")
+
+            return {
+                "file": file_path,
+                "package": package_name,
+                "version": version
+            }
+
+        return create_error_response(
+            "ParseError",
+            f"Could not parse pacman output: {stdout}"
+        )
+
+    except Exception as e:
+        logger.error(f"Package ownership query failed: {e}")
+        return create_error_response(
+            "CommandError",
+            f"Failed to find package owner: {str(e)}"
+        )
+
+
+async def list_package_files(package_name: str, filter_pattern: Optional[str] = None) -> Dict[str, Any]:
+    """
+    List all files owned by a package.
+
+    Args:
+        package_name: Name of package
+        filter_pattern: Optional regex pattern to filter files
+
+    Returns:
+        Dict with list of files
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Package file listing is only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    logger.info(f"Listing files for package: {package_name}")
+
+    try:
+        exit_code, stdout, stderr = await run_command(
+            ["pacman", "-Ql", package_name],
+            timeout=10,
+            check=False
+        )
+
+        if exit_code != 0:
+            logger.error(f"Failed to list files for {package_name}: {stderr}")
+            return create_error_response(
+                "NotFound",
+                f"Package not found or no files: {package_name}",
+                stderr
+            )
+
+        # Parse output: "package /path/to/file"
+        files = []
+        for line in stdout.strip().split('\n'):
+            if not line.strip():
+                continue
+
+            parts = line.split(maxsplit=1)
+            if len(parts) == 2:
+                file_path = parts[1]
+
+                # Apply filter if provided
+                if filter_pattern:
+                    if re.search(filter_pattern, file_path):
+                        files.append(file_path)
+                else:
+                    files.append(file_path)
+
+        logger.info(f"Found {len(files)} files for {package_name}")
+
+        return {
+            "package": package_name,
+            "file_count": len(files),
+            "files": files,
+            "filter_applied": filter_pattern is not None
+        }
+
+    except Exception as e:
+        logger.error(f"File listing failed: {e}")
+        return create_error_response(
+            "CommandError",
+            f"Failed to list package files: {str(e)}"
+        )
+
+
+async def search_package_files(filename_pattern: str) -> Dict[str, Any]:
+    """
+    Search for files across all packages.
+
+    Args:
+        filename_pattern: Filename pattern to search for
+
+    Returns:
+        Dict with matching files and packages
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Package file search is only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    logger.info(f"Searching for files matching: {filename_pattern}")
+
+    try:
+        # First check if file database is synced
+        exit_code, stdout, stderr = await run_command(
+            ["pacman", "-F", filename_pattern],
+            timeout=30,
+            check=False
+        )
+
+        if exit_code == 1 and "database" in stderr.lower():
+            return create_error_response(
+                "DatabaseNotSynced",
+                "Package file database not synced. Run 'sudo pacman -Fy' first.",
+                "File database needs to be synchronized before searching"
+            )
+
+        if exit_code != 0 and not stdout.strip():
+            logger.info(f"No files found matching {filename_pattern}")
+            return {
+                "pattern": filename_pattern,
+                "match_count": 0,
+                "matches": []
+            }
+
+        # Parse output: "repository/package version\n    path/to/file"
+        matches = []
+        current_package = None
+
+        for line in stdout.strip().split('\n'):
+            if not line.strip():
+                continue
+
+            if line.startswith(' '):
+                # This is a file path
+                if current_package:
+                    file_path = line.strip()
+                    matches.append({
+                        "package": current_package["package"],
+                        "repository": current_package["repository"],
+                        "version": current_package["version"],
+                        "file": file_path
+                    })
+            else:
+                # This is a package line: "repository/package version"
+                parts = line.split()
+                if len(parts) >= 2:
+                    repo_pkg = parts[0].split('/')
+                    if len(repo_pkg) == 2:
+                        current_package = {
+                            "repository": repo_pkg[0],
+                            "package": repo_pkg[1],
+                            "version": parts[1]
+                        }
+
+        logger.info(f"Found {len(matches)} files matching {filename_pattern}")
+
+        return {
+            "pattern": filename_pattern,
+            "match_count": len(matches),
+            "matches": matches
+        }
+
+    except Exception as e:
+        logger.error(f"File search failed: {e}")
+        return create_error_response(
+            "CommandError",
+            f"Failed to search package files: {str(e)}"
+        )
+
+
+async def verify_package_integrity(package_name: str, thorough: bool = False) -> Dict[str, Any]:
+    """
+    Verify integrity of an installed package.
+
+    Args:
+        package_name: Name of package to verify
+        thorough: If True, perform thorough check (pacman -Qkk)
+
+    Returns:
+        Dict with verification results
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Package verification is only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    logger.info(f"Verifying package integrity: {package_name} (thorough={thorough})")
+
+    try:
+        cmd = ["pacman", "-Qkk" if thorough else "-Qk", package_name]
+
+        exit_code, stdout, stderr = await run_command(
+            cmd,
+            timeout=30,
+            check=False
+        )
+
+        if exit_code != 0 and "was not found" in stderr:
+            return create_error_response(
+                "NotFound",
+                f"Package not installed: {package_name}"
+            )
+
+        # Parse verification output
+        issues = []
+        for line in stdout.strip().split('\n'):
+            if "warning" in line.lower() or "missing" in line.lower():
+                issues.append(line.strip())
+
+        logger.info(f"Found {len(issues)} issues for {package_name}")
+
+        return {
+            "package": package_name,
+            "thorough": thorough,
+            "issues_found": len(issues),
+            "issues": issues,
+            "all_ok": len(issues) == 0
+        }
+
+    except Exception as e:
+        logger.error(f"Package verification failed: {e}")
+        return create_error_response(
+            "CommandError",
+            f"Failed to verify package: {str(e)}"
+        )
+
+
+async def list_package_groups() -> Dict[str, Any]:
+    """
+    List all available package groups.
+
+    Returns:
+        Dict with list of groups
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Package groups are only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    logger.info("Listing package groups")
+
+    try:
+        exit_code, stdout, stderr = await run_command(
+            ["pacman", "-Sg"],
+            timeout=10,
+            check=False
+        )
+
+        if exit_code != 0:
+            return create_error_response(
+                "CommandError",
+                f"Failed to list groups: {stderr}"
+            )
+
+        # Parse output - format: "group package"
+        groups = set()
+        for line in stdout.strip().split('\n'):
+            if line.strip():
+                parts = line.split()
+                if parts:
+                    groups.add(parts[0])
+
+        groups_list = sorted(list(groups))
+
+        logger.info(f"Found {len(groups_list)} package groups")
+
+        return {
+            "group_count": len(groups_list),
+            "groups": groups_list
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to list groups: {e}")
+        return create_error_response(
+            "CommandError",
+            f"Failed to list package groups: {str(e)}"
+        )
+
+
+async def list_group_packages(group_name: str) -> Dict[str, Any]:
+    """
+    List packages in a specific group.
+
+    Args:
+        group_name: Name of the group
+
+    Returns:
+        Dict with packages in the group
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Package groups are only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    logger.info(f"Listing packages in group: {group_name}")
+
+    try:
+        exit_code, stdout, stderr = await run_command(
+            ["pacman", "-Sg", group_name],
+            timeout=10,
+            check=False
+        )
+
+        if exit_code != 0:
+            return create_error_response(
+                "NotFound",
+                f"Group not found: {group_name}"
+            )
+
+        # Parse output - format: "group package"
+        packages = []
+        for line in stdout.strip().split('\n'):
+            if line.strip():
+                parts = line.split()
+                if len(parts) >= 2:
+                    packages.append(parts[1])
+
+        logger.info(f"Found {len(packages)} packages in {group_name}")
+
+        return {
+            "group": group_name,
+            "package_count": len(packages),
+            "packages": packages
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to list group packages: {e}")
+        return create_error_response(
+            "CommandError",
+            f"Failed to list packages in group: {str(e)}"
+        )
+
+
+async def list_explicit_packages() -> Dict[str, Any]:
+    """
+    List explicitly installed packages.
+
+    Returns:
+        Dict with list of explicit packages
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Package install reason queries are only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    logger.info("Listing explicitly installed packages")
+
+    try:
+        exit_code, stdout, stderr = await run_command(
+            ["pacman", "-Qe"],
+            timeout=15,
+            check=False
+        )
+
+        if exit_code != 0:
+            return create_error_response(
+                "CommandError",
+                f"Failed to list explicit packages: {stderr}"
+            )
+
+        # Parse output - format: "package version"
+        packages = []
+        for line in stdout.strip().split('\n'):
+            if line.strip():
+                parts = line.split()
+                if len(parts) >= 2:
+                    packages.append({
+                        "name": parts[0],
+                        "version": parts[1]
+                    })
+
+        logger.info(f"Found {len(packages)} explicitly installed packages")
+
+        return {
+            "package_count": len(packages),
+            "packages": packages
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to list explicit packages: {e}")
+        return create_error_response(
+            "CommandError",
+            f"Failed to list explicit packages: {str(e)}"
+        )
+
+
+async def mark_as_explicit(package_name: str) -> Dict[str, Any]:
+    """
+    Mark a package as explicitly installed.
+
+    Args:
+        package_name: Name of package to mark
+
+    Returns:
+        Dict with operation status
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Package marking is only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    logger.info(f"Marking {package_name} as explicitly installed")
+
+    try:
+        exit_code, stdout, stderr = await run_command(
+            ["sudo", "pacman", "-D", "--asexplicit", package_name],
+            timeout=10,
+            check=False,
+            skip_sudo_check=True
+        )
+
+        if exit_code != 0:
+            return create_error_response(
+                "CommandError",
+                f"Failed to mark package as explicit: {stderr}"
+            )
+
+        logger.info(f"Successfully marked {package_name} as explicit")
+
+        return {
+            "success": True,
+            "package": package_name,
+            "marked_as": "explicit"
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to mark package: {e}")
+        return create_error_response(
+            "CommandError",
+            f"Failed to mark package as explicit: {str(e)}"
+        )
+
+
+async def mark_as_dependency(package_name: str) -> Dict[str, Any]:
+    """
+    Mark a package as a dependency.
+
+    Args:
+        package_name: Name of package to mark
+
+    Returns:
+        Dict with operation status
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Package marking is only available on Arch Linux"
+        )
+
+    if not check_command_exists("pacman"):
+        return create_error_response(
+            "CommandNotFound",
+            "pacman command not found"
+        )
+
+    logger.info(f"Marking {package_name} as dependency")
+
+    try:
+        exit_code, stdout, stderr = await run_command(
+            ["sudo", "pacman", "-D", "--asdeps", package_name],
+            timeout=10,
+            check=False,
+            skip_sudo_check=True
+        )
+
+        if exit_code != 0:
+            return create_error_response(
+                "CommandError",
+                f"Failed to mark package as dependency: {stderr}"
+            )
+
+        logger.info(f"Successfully marked {package_name} as dependency")
+
+        return {
+            "success": True,
+            "package": package_name,
+            "marked_as": "dependency"
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to mark package: {e}")
+        return create_error_response(
+            "CommandError",
+            f"Failed to mark package as dependency: {str(e)}"
+        )
+
+
+async def check_database_freshness() -> Dict[str, Any]:
+    """
+    Check when package databases were last synchronized.
+
+    Returns:
+        Dict with database sync timestamps per repository
+    """
+    if not IS_ARCH:
+        return create_error_response(
+            "NotSupported",
+            "Database freshness check is only available on Arch Linux"
+        )
+
+    logger.info("Checking database freshness")
+
+    try:
+        from pathlib import Path
+        from datetime import datetime, timedelta
+
+        sync_dir = Path("/var/lib/pacman/sync")
+
+        if not sync_dir.exists():
+            return create_error_response(
+                "NotFound",
+                "Pacman sync directory not found"
+            )
+
+        # Get all .db files
+        db_files = list(sync_dir.glob("*.db"))
+
+        if not db_files:
+            return create_error_response(
+                "NotFound",
+                "No database files found"
+            )
+
+        databases = []
+        now = datetime.now()
+        oldest_db = None
+        oldest_age = timedelta(0)
+
+        for db_file in db_files:
+            mtime = datetime.fromtimestamp(db_file.stat().st_mtime)
+            age = now - mtime
+            hours_old = age.total_seconds() / 3600
+
+            db_info = {
+                "repository": db_file.stem,  # Remove .db extension
+                "last_sync": mtime.isoformat(),
+                "hours_old": round(hours_old, 1)
+            }
+
+            # Warn if older than 24 hours
+            if hours_old > 24:
+                db_info["warning"] = f"Database is {hours_old:.0f} hours old (> 24h)"
+
+            databases.append(db_info)
+
+            # Track oldest
+            if oldest_db is None or age > oldest_age:
+                oldest_db = db_info["repository"]
+                oldest_age = age
+
+        # Sort by hours_old descending (oldest first)
+        databases.sort(key=lambda x: x["hours_old"], reverse=True)
+
+        logger.info(f"Checked {len(databases)} databases, oldest: {oldest_age.total_seconds() / 3600:.1f}h")
+
+        recommendations = []
+        if oldest_age.total_seconds() / 3600 > 24:
+            recommendations.append("Databases are stale (> 24h). Run 'sudo pacman -Sy' to synchronize.")
+        if oldest_age.total_seconds() / 3600 > 168:  # 1 week
+            recommendations.append("Databases are very stale (> 1 week). Consider full system update.")
+
+        return {
+            "database_count": len(databases),
+            "databases": databases,
+            "oldest_database": oldest_db,
+            "oldest_age_hours": round(oldest_age.total_seconds() / 3600, 1),
+            "recommendations": recommendations,
+            "needs_sync": oldest_age.total_seconds() / 3600 > 24
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to check database freshness: {e}")
+        return create_error_response(
+            "CheckError",
+            f"Failed to check database freshness: {str(e)}"
+        )
+