pkgwise 0.1.0__py3-none-any.whl

pkgwise/core/priority.py

@@ -0,0 +1,199 @@
+"""Transparent, conservative update-priority scoring.
+
+PkgWise never claims it can tell how "important" an update is. Instead it
+collects *observable facts* about a package (security metadata, whether it is
+a kernel, a core system component or a system library) and maps those facts to
+a category through a small, documented scoring table.
+
+The scoring is deliberately conservative: facts that are not available add no
+points and surface as "Security status: Unknown" rather than guesses.
+
+Points table
+------------
+================  ====
+fact              pts
+================  ====
+security update     4
+kernel/likely      3
+reboot
+core system         2
+component
+system library      2
+small utility      -1
+================  ====
+
+Thresholds
+----------
+====  ========  ========
+pts   category  reason shown
+====  ========  ========
+>=4   CRITICAL  security-related update
+>=3   HIGH      kernel/reboot, core component
+>=1   MEDIUM    system library / core component
+0     MEDIUM    default (no facts)
+<0    LOW       small utility
+====  ========  ========
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, List, Tuple
+
+from pkgwise.core.models import PackageUpdate, Priority
+
+#: Facts fixed by name pattern. These are *system properties* of well-known
+#: base packages (a kernel update requires a reboot, glibc underpins the
+#: system), not an opinion about whether the update matters to the user.
+KERNEL_PREFIXES = (
+    "linux",
+    "kernel",
+    "linux-image",
+    "linux-headers",
+    "linux-modules",
+)
+CORE_COMPONENT_PREFIXES = (
+    "systemd",
+    "bash",
+    "coreutils",
+    "binutils",
+    "util-linux",
+    "udev",
+    "dbus",
+    "pam",
+    "iproute2",
+    "glibc",
+    "busybox",
+    "initramfs",
+    "shim",
+    "grub",
+    "grub2",
+)
+LIBRARY_PREFIXES = (
+    "lib",
+    "libc",
+    "libssl",
+    "openssl",
+    "gnutls",
+    "zlib",
+    "ssl",
+    "ncurses",
+    "readline",
+    "python3",
+    "openssl",
+    "perl",
+)
+
+#: Rough retry-too-low threshold for the "small utility" heuristic.
+_SMALL_UTILITY_BYTES = 15 * 1024 * 1024
+
+
+def analyze_priority(update: PackageUpdate) -> Tuple[Priority, List[str]]:
+    """Score one update and return ``(priority, human_reasons)``.
+
+    The reasons are the *only* justification for the category; the UI displays
+    them verbatim so nothing is labeled important without explanation.
+    """
+    facts = _collect_facts(update)
+    return _score(facts)
+
+
+def _collect_facts(update: PackageUpdate) -> List[str]:
+    """Return the list of fact labels that apply to this update."""
+    facts: List[str] = []
+    name = update.name or ""
+
+    if update.security_update is True:
+        facts.append("security-update")
+    if _is_kernel(name):
+        facts.append("kernel")
+    if _is_core_component(name):
+        facts.append("core-component")
+    elif _is_system_library(name):
+        facts.append("system-library")
+    elif _is_small_utility(update):
+        facts.append("small-utility")
+
+    if update.installed_size is None and update.download_size is None:
+        facts.append("unknown-metadata")
+    return facts
+
+
+def _score(facts: Iterable[str]) -> Tuple[Priority, List[str]]:
+    points = 0
+    reasons: List[str] = []
+    fact_set = set(facts)
+
+    if "security-update" in fact_set:
+        points += 4
+        reasons.append("Security-related update")
+    if "kernel" in fact_set:
+        points += 3
+        reasons.append("Kernel package — likely requires rebooting")
+    if "core-component" in fact_set:
+        points += 2
+        reasons.append("Core system component")
+    elif "system-library" in fact_set:
+        points += 2
+        reasons.append("System library")
+    if "small-utility" in fact_set:
+        points -= 1
+
+    if points >= 4:
+        priority = Priority.CRITICAL
+    elif points >= 3:
+        priority = Priority.HIGH
+    elif points >= 1:
+        priority = Priority.MEDIUM
+    elif points == 0:
+        priority = Priority.MEDIUM
+    else:
+        priority = Priority.LOW
+        reasons.append("Small utility — low overall impact")
+
+    if not reasons:
+        reasons.append("No security or system-critical metadata was detected.")
+    return priority, reasons
+
+
+# -- fact helpers ------------------------------------------------------------
+
+
+def _is_kernel(name: str) -> bool:
+    """True for kernel packages (linux, linux-lts, linux-zen, ...)."""
+    return name.startswith(KERNEL_PREFIXES)
+
+
+def _is_core_component(name: str) -> bool:
+    """True for base system components such as systemd, bash or grub."""
+    return name.startswith(CORE_COMPONENT_PREFIXES)
+
+
+def _is_system_library(name: str) -> bool:
+    """True for shared libraries and language runtimes (libc, libssl, ...)."""
+    if name.startswith(LIBRARY_PREFIXES):
+        return True
+    # Versioned runtime names like libc6, libssl3, python3.11
+    return bool(re.match(r"^(lib|c|python\d)(\d|[a-z])", name))
+
+
+def _is_small_utility(update: PackageUpdate) -> bool:
+    """True when an update is small and not part of the base system.
+
+    Uses only the sizes we actually measured; unknown sizes never score here.
+    """
+    if _is_kernel(update.name or "") or _is_core_component(update.name or "") or _is_system_library(update.name or ""):
+        return False
+    size = update.download_size if update.download_size is not None else update.installed_size
+    return size is not None and size < _SMALL_UTILITY_BYTES
+
+
+def priority_emoji(priority: Priority) -> str:
+    """Return the colored label used across the UI for a priority."""
+    icons = {
+        Priority.CRITICAL: "🔴 CRITICAL",
+        Priority.HIGH: "🟠 HIGH",
+        Priority.MEDIUM: "🟡 MEDIUM",
+        Priority.LOW: "🟢 LOW",
+    }
+    return icons[priority]

pkgwise/core/storage.py

@@ -0,0 +1,82 @@
+"""Disk storage detection.
+
+Uses :mod:`psutil` when available for reliable cross-platform statistics.
+When psutil is not installed, degrades to the standard-library
+``shutil.disk_usage`` — 100% of the functionality with zero hard dependency.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from pkgwise.core.models import StorageInfo
+
+_ROOT_PATH = "/"
+
+
+def _psutil_partitions() -> list:
+    """psutil partitions with filesystem types, or empty list if unavailable."""
+    try:
+        import psutil  # type: ignore[import-not-found]
+
+        return psutil.disk_partitions(all=False)
+    except Exception:
+        return []
+
+
+def _psutil_usage(path: str) -> Optional[tuple]:
+    """Return (total, used, free) from psutil or ``None`` on failure."""
+    try:
+        import psutil  # type: ignore[import-not-found]
+
+        usage = psutil.disk_usage(path)
+        return (usage.total, usage.used, usage.free)
+    except Exception:
+        return None
+
+
+def get_storage_info(path: str = _ROOT_PATH) -> StorageInfo:
+    """Return ``StorageInfo`` for the filesystem containing *path*.
+
+    Resolution order:
+      1. psutil ``disk_partitions`` + ``disk_usage`` (excludes pseudo-filesystems).
+      2. psutil ``disk_usage`` directly on the path.
+      3. stdlib ``shutil.disk_usage`` on the path.
+    """
+    usage = _psutil_by_mount(path) or _psutil_usage(path) or _shutil_usage(path)
+    total, used, free = usage
+    return StorageInfo(path=path, total_bytes=total, used_bytes=used, free_bytes=free)
+
+
+def _psutil_by_mount(path: str) -> Optional[tuple]:
+    """Find the mount point for *path* and read its usage via psutil."""
+    for partition in _psutil_partitions():
+        mountpoint = partition.mountpoint
+        if _is_contained(path, mountpoint):
+            usage = _psutil_usage(mountpoint)
+            if usage is not None:
+                return usage
+    return None
+
+
+def _is_contained(path: str, mountpoint: str) -> bool:
+    if not mountpoint:
+        return False
+    try:
+        real_path = os.path.realpath(path)
+        real_mount = os.path.realpath(mountpoint)
+    except (AttributeError, ValueError):  # invalid paths
+        return False
+    if real_path == real_mount:
+        return True
+    if real_mount == os.sep:
+        return real_path.startswith(os.sep)
+    return real_path.startswith(real_mount + os.sep)
+
+
+def _shutil_usage(path: str) -> tuple:
+    import shutil
+
+    usage = shutil.disk_usage(path)
+    return (usage.total, usage.used, usage.free)

pkgwise/mockdata.py

@@ -0,0 +1,43 @@
+"""Mock package updates for development and testing.
+
+The TUI can be run in ``--mock`` mode (or with ``PKGWISE_MOCK=1``) so it can be
+developed — and previewed — on any machine, without a specific Linux
+distribution or package manager. Production code never loads this module; it
+exists only for local preview, tests and screenshots.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from pkgwise.core.models import PackageUpdate
+from pkgwise.core.priority import analyze_priority
+
+_MB = 1024 * 1024
+
+
+def mock_packages() -> List[PackageUpdate]:
+    """Return a realistic set of mock updates, pre-scored by the real analyzer."""
+    rows = [
+        PackageUpdate("linux", "6.16.8", "6.16.9", 142 * _MB, 720 * _MB),
+        PackageUpdate("openssl", "3.5.2", "3.5.3", 8 * _MB, 24 * _MB, security_update=True),
+        PackageUpdate("firefox", "142.0", "142.0.1", 87 * _MB, 380 * _MB),
+        PackageUpdate("htop", "3.4", "3.5", 1 * _MB, 3 * _MB),
+        PackageUpdate("systemd", "257.1", "257.2", 12 * _MB, 45 * _MB),
+        PackageUpdate("libssl3", "3.5.2", "3.5.3", 2 * _MB, 9 * _MB, security_update=True),
+        PackageUpdate("python3", "3.14.2", "3.14.3", 34 * _MB, 160 * _MB),
+        PackageUpdate("vim", "9.1", "9.2", 4 * _MB, 20 * _MB),
+    ]
+    return [_prioritized(u) for u in rows]
+
+
+def _prioritized(update: PackageUpdate) -> PackageUpdate:
+    priority, reasons = analyze_priority(update)
+    return update.prioritized(priority, reasons)
+
+
+def enable_mock_mode() -> bool:
+    """True when a mock-mode flag is present in the environment."""
+    import os
+
+    return os.environ.get("PKGWISE_MOCK", "").strip().lower() in {"1", "true", "yes", "on"}

pkgwise/ui/__init__.py

@@ -0,0 +1 @@
+"""Textual user interface: the app, screens and reusable widgets."""

pkgwise/ui/app.py

@@ -0,0 +1,228 @@
+"""PkgWise Textual application.
+
+Assembly point: loads analysis (optionally with mock data), mounts the main
+screen, and owns the *safe* update flow (check disk space, check elevation,
+then either run the command as root or clearly show the command to run).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import List, Optional
+
+from rich.text import Text
+from textual import work
+from textual.app import App
+from textual.screen import Screen
+
+from pkgwise import __version__
+from pkgwise.core import analyzer as analyzer_mod
+from pkgwise.core.analyzer import InsufficientDiskSpace, RequiresElevation, UpdateGated
+from pkgwise.core.models import AnalysisResult, PackageUpdate
+from pkgwise.mockdata import enable_mock_mode, mock_packages
+from pkgwise.utils.formatting import format_bytes
+from pkgwise.ui.screens import (
+    BlockedScreen,
+    ErrorScreen,
+    MainScreen,
+    ResultScreen,
+)
+
+#: Mock data for local preview/tests; production never enables this.
+MOCK_UPDATE_NAME = "__pkgwise_mock__"
+
+
+class PkgWiseApp(App):
+    """Root application object for the PkgWise terminal UI."""
+
+    TITLE = "PkgWise — Smart Linux Update Analyzer"
+    SUB_TITLE = f"v{__version__}"
+
+    SCREENS = {
+        "main": MainScreen,
+        "details": "pkgwise.ui.screens.DetailsScreen",
+        "confirm": "pkgwise.ui.screens.ConfirmScreen",
+        "blocked": BlockedScreen,
+        "result": ResultScreen,
+        "error": ErrorScreen,
+    }
+
+    BINDINGS = [("q", "quit", "Quit")]
+
+    def __init__(
+        self,
+        analysis: Optional[AnalysisResult] = None,
+        mock: Optional[bool] = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._analysis = analysis
+        self._mock = enable_mock_mode() if mock is None else mock
+
+    # -- lifecycle -----------------------------------------------------------
+
+    def on_mount(self) -> None:
+        if self._analysis is not None:
+            self.push_screen(MainScreen(analysis=self._analysis))
+            return
+        if self._mock:
+            self.push_screen(
+                MainScreen(
+                    updates=mock_packages(),
+                )
+            )
+            return
+        self.run_worker(self._load_analysis, thread=True, exclusive=True)
+
+    def _load_analysis(self) -> None:
+        try:
+            self._analysis = analyzer_mod.analyze()
+            self.call_from_thread(self._show_main)
+        except Exception as exc:
+            self.call_from_thread(self._show_load_error, exc)
+
+    def _show_main(self) -> None:
+        if self._analysis is None:
+            return
+        self.push_screen(MainScreen(analysis=self._analysis))
+
+    def _show_load_error(self, exc: Exception) -> None:
+        self.push_screen(
+            ErrorScreen(
+                title="Unable to check for updates",
+                message=_friendly_error(exc),
+            )
+        )
+
+    # -- actions shared with screens --------------------------------------
+
+    def refresh_analysis(self) -> AnalysisResult:
+        """Re-analyze after refreshing the package index."""
+        if self._mock:
+            return AnalysisResult(
+                storage=self._analysis.storage if self._analysis else None,  # type: ignore[arg-type]
+                system=self._analysis.system if self._analysis else None,  # type: ignore[arg-type]
+                updates=mock_packages(),
+            )
+        assert self._analysis is not None
+        return analyzer_mod.refresh_updates(self._analysis)
+
+    def proceed_with_updates(self, updates: List[PackageUpdate]) -> None:
+        """Safety-gated entry point for actually updating packages.
+
+        Guarantees (in order): never automatic, disk-space check, elevation
+        check, and a human-visible command. When running as root the command
+        executes directly; otherwise the exact command is shown so the user
+        can run it in a terminal.
+        """
+        if self._mock:
+            self.push_screen(
+                ResultScreen(
+                    title="Mock update complete",
+                    body=(
+                        "This was mock data, so nothing was actually installed.\n"
+                        "In real mode this command would run:\n\n"
+                        "  sudo pacman -Su " + " ".join(sorted(u.name for u in updates))
+                    ),
+                )
+            )
+            return
+
+        storage = self._analysis.storage if self._analysis else None
+        try:
+            analyzer_mod.prepare_update(updates, storage=storage)
+        except InsufficientDiskSpace as exc:
+            short = exc.required - exc.available
+            self.push_screen(
+                BlockedScreen(
+                    title="⚠ INSUFFICIENT DISK SPACE",
+                    message=(
+                        f"Available: {format_bytes(exc.available)}\n"
+                        f"Required:  {format_bytes(exc.required)}\n\n"
+                        f"You need approximately {format_bytes(short)} more free space.\n\n"
+                        "PkgWise has NOT started the update.\n"
+                        "It does not delete caches or packages automatically."
+                    ),
+                )
+            )
+            return
+        except RequiresElevation as exc:
+            self.push_screen(
+                BlockedScreen(
+                    title="Elevation required",
+                    message=exc.message,
+                    detail="PkgWise does not perform privilege escalation.",
+                )
+            )
+            return
+        except UpdateGated as exc:
+            self.push_screen(ErrorScreen(title="Update blocked", message=str(exc)))
+            return
+
+        names = sorted(u.name for u in updates)
+        command = analyzer_mod.display_command(names)
+        self._execute_or_instruct(command, names)
+
+    def _execute_or_instruct(self, command: List[str], names: List[str]) -> None:
+        from pkgwise.utils.commands import is_elevated
+
+        if is_elevated():
+            self._root_update(command, names)
+            self.notify("Update started… you are running as root.")
+            return
+        body = Text()
+        body.append("PkgWise requires elevated privileges to update packages.\n\n")
+        body.append("Run this command in a terminal:\n\n", style="bold")
+        body.append("  " + " ".join(command) + "\n\n")
+        body.append("Or restart PkgWise as root.")
+        self.push_screen(ResultScreen(title="Update command ready", body=body))
+
+    @work(thread=True, exclusive=True)
+    def _root_update(self, command: List[str], names: List[str]) -> None:
+        """Stream an update to the terminal while running as root."""
+        import subprocess
+
+        from pkgwise.utils.commands import which
+
+        exe = which(command[0])
+        if exe is None:
+            self.call_from_thread(
+                self._root_update_done,
+                "The command could not be found on this system.",
+                failed=True,
+            )
+            return
+        proc = subprocess.run([exe, *command[1:]], text=True, check=False)
+        status = "succeeded" if proc.returncode == 0 else f"failed (exit {proc.returncode})"
+        summary = (
+            f"Update {status}.\n\n"
+            f"Command: {' '.join(command)}\n\n"
+            "PkgWise does not verify package-manager output beyond the exit code."
+        )
+        self.call_from_thread(self._root_update_done, summary, failed=proc.returncode != 0)
+
+    def _root_update_done(self, message: str, failed: bool) -> None:
+        title = "Update failed" if failed else "Update finished"
+        self.push_screen(ResultScreen(title=title, body=message))
+
+
+def _friendly_error(exc: Exception) -> str:
+    """Translate low-level failures into readable guidance."""
+    text = str(exc) or exc.__class__.__name__
+    lowered = text.lower()
+    if "not found" in lowered or "unavailable" in lowered or "unsupported" in lowered:
+        return (
+            f"{text}\n\n"
+            "Check that your package manager is installed and that the "
+            "distribution is supported (Arch/pacman, Debian/apt)."
+        )
+    if "network" in lowered or "could not resolve" in lowered or "e:" in lowered:
+        return (
+            "The package manager could not reach its repositories.\n\n"
+            "Check your network connection and package-manager configuration."
+        )
+    return (
+        f"{text}\n\n"
+        "The package manager returned an error.\n"
+        "Check your network connection and package-manager configuration."
+    )