pkgwise 0.1.0__py3-none-any.whl

pkgwise/ui/screens.py

@@ -0,0 +1,406 @@
+"""PkgWise TUI screens.
+
+Each screen owns one focused task:
+
+- :class:`MainScreen` — storage + update list + selection
+- :class:`DetailsScreen` — why a single update is (or isn't) important
+- :class:`ConfirmScreen` — the always-on "Continue? [y/N]" gate
+- :class:`BlockedScreen` — insufficient disk space / elevation notice
+- :class:`ResultScreen` — sit back and run the shown command
+- :class:`ErrorScreen` — human-readable failure report
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import VerticalScroll
+from textual.screen import ModalScreen, Screen
+from textual.widgets import DataTable, Footer, Header, Label, Static
+
+from pkgwise.core.models import AnalysisResult, PackageUpdate, StorageInfo
+from pkgwise.utils.formatting import format_bytes
+from pkgwise.ui.widgets import progress_text, storage_summary_text
+
+_PRIORITY_LABEL = {
+    4: "🔴 CRITICAL",
+    3: "🟠 HIGH",
+    2: "🟡 MEDIUM",
+    1: "🟢 LOW",
+}
+
+
+class MainScreen(Screen):
+    """Primary screen: overview, priority breakdown and selectable update list."""
+
+    BINDINGS = [
+        Binding("space", "toggle_select", "Select"),
+        Binding("enter", "show_details", "Details"),
+        Binding("u", "update_selected", "Update"),
+        Binding("a", "select_all", "Select all"),
+        Binding("r", "refresh", "Refresh"),
+        Binding("q", "quit", "Quit"),
+        Binding("escape", "stop", "Back"),
+    ]
+
+    def __init__(
+        self,
+        analysis: Optional[AnalysisResult] = None,
+        updates: Optional[List[PackageUpdate]] = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._analysis = analysis
+        if updates is not None:
+            self._updates = updates
+        elif analysis is not None:
+            self._updates = list(analysis.updates)
+        else:
+            self._updates = []
+        self._selected: set[str] = set()
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        with VerticalScroll(id="overview"):
+            yield Static(id="storage-block")
+            yield Static(id="summary-block")
+            yield Static(id="counts-block")
+            yield Label("", id="selection-block")
+            yield DataTable(id="updates-table")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        table = self.query_one("#updates-table", DataTable)
+        table.cursor_type = "row"
+        table.zebra_stripes = True
+        table.add_columns("", "PACKAGE", "CURRENT", "NEW", "SIZE", "PRIORITY")
+        self._rebuild_all()
+
+    def _rebuild_all(self) -> None:
+        self._render_storage()
+        self._render_summary()
+        self._render_counts()
+        self._render_selection()
+        self._render_table()
+
+    def _render_storage(self) -> None:
+        widget = self.query_one("#storage-block", Static)
+        storage: Optional[StorageInfo] = None
+        if self._analysis is not None:
+            storage = self._analysis.storage
+        if storage is None:
+            widget.update(Text("STORAGE\nUnknown", style="dim"))
+            return
+        bar_width = max(self.size.width - 6, 10)
+        widget.update(storage_summary_text(storage, bar_width))
+
+    def _render_summary(self) -> None:
+        widget = self.query_one("#summary-block", Static)
+        if not self._updates:
+            widget.update("")
+            return
+        download = sum(u.download_size for u in self._updates if u.download_size)
+        install = sum(u.installed_size for u in self._updates if u.installed_size)
+        line = (
+            f"{len(self._updates)} available updates"
+        )
+        if download:
+            line += f"   {format_bytes(download)} download"
+        if install:
+            line += f"   {format_bytes(install)} install"
+        widget.update(line)
+
+    def _render_counts(self) -> None:
+        widget = self.query_one("#counts-block", Static)
+        counts = {p: 0 for p in (4, 3, 2, 1)}
+        for update in self._updates:
+            counts[update.priority.value] += 1
+        text = Text()
+        for value in (4, 3, 2, 1):
+            if counts[value]:
+                text.append(f"{_PRIORITY_LABEL[value]:<10} {counts[value]}\n")
+        widget.update(text)
+
+    def _render_selection(self) -> None:
+        widget = self.query_one("#selection-block", Label)
+        if not self._selected:
+            widget.update("")
+            return
+        chosen = [u for u in self._updates if u.name in self._selected]
+        download = sum(u.download_size for u in chosen if u.download_size)
+        install = sum(u.installed_size for u in chosen if u.installed_size)
+        parts = [f"Selected: {len(chosen)} packages"]
+        if download:
+            parts.append(f"Download: {format_bytes(download)}")
+        if install:
+            parts.append(f"Estimated install: {format_bytes(install)}")
+        widget.update("   ".join(parts))
+
+    def _render_table(self) -> None:
+        table = self.query_one("#updates-table", DataTable)
+        table.clear()
+        order = {4: 0, 3: 1, 2: 2, 1: 3}
+        sorted_updates = sorted(
+            self._updates, key=lambda u: (order.get(u.priority.value, 2), u.name)
+        )
+        for update in sorted_updates:
+            mark = "[x]" if update.name in self._selected else "[ ]"
+            prio = _PRIORITY_LABEL.get(update.priority.value, "MEDIUM")
+            size = format_bytes(
+                update.download_size if update.download_size is not None else update.installed_size
+            )
+            table.add_row(
+                mark,
+                update.name,
+                update.current_version or "Unknown",
+                update.new_version or "Unknown",
+                size,
+                prio,
+                key=update.name,
+            )
+
+    # -- actions ----------------------------------------------------------
+
+    def action_toggle_select(self) -> None:
+        table = self.query_one("#updates-table", DataTable)
+        update = self._current_update()
+        if update is None:
+            return
+        name = update.name
+        if name in self._selected:
+            self._selected.discard(name)
+        else:
+            self._selected.add(name)
+        self._render_selection()
+        self._render_table()
+
+    def _current_update(self) -> Optional[PackageUpdate]:
+        table = self.query_one("#updates-table", DataTable)
+        if not table.row_count:
+            return None
+        row = table.coordinate_to_cell_key(table.cursor_coordinate)
+        if not row or not row.row_key.value:
+            return None
+        name = str(row.row_key.value)
+        return next((u for u in self._updates if u.name == name), None)
+
+    def action_show_details(self) -> None:
+        update = self._current_update()
+        if update is None:
+            return
+        self.app.push_screen(DetailsScreen(update))
+
+    def action_update_selected(self) -> None:
+        chosen = [u for u in self._updates if u.name in self._selected]
+        if not chosen:
+            self.app.push_screen(
+                ErrorScreen(
+                    title="Nothing selected",
+                    message="Select at least one package with SPACE before updating.",
+                )
+            )
+            return
+        self.app.push_screen(ConfirmScreen(chosen))
+
+    def action_select_all(self) -> None:
+        all_names = {u.name for u in self._updates}
+        if self._selected == all_names:
+            self._selected = set()
+        else:
+            self._selected = all_names
+        self._render_selection()
+        self._render_table()
+
+    def action_refresh(self) -> None:
+        self.app.notify("Refreshing… this can take a moment")
+        try:
+            refreshed = self.app.refresh_analysis()
+            self._analysis = refreshed
+            self._updates = refreshed.updates
+            self._selected = {n for n in self._selected if n in {u.name for u in refreshed.updates}}
+            self._rebuild_all()
+        except Exception as exc:
+            self.app.push_screen(
+                ErrorScreen(
+                    title="Refresh failed",
+                    message="The package manager could not refresh the update list.",
+                    detail=str(exc),
+                )
+            )
+
+    def action_stop(self) -> None:
+        """Pop the screen only when there is something to pop."""
+        if len(self.app.screen_stack) > 1:
+            self.app.pop_screen()
+
+    def on_resize(self) -> None:
+        self._render_storage()
+
+
+class DetailsScreen(Screen):
+    """Explain why a single update is (or is not) prioritized highly."""
+
+    BINDINGS = [
+        Binding("escape", "app.pop_screen", "Back"),
+        Binding("u", "update_package", "Update this package"),
+        Binding("q", "quit", "Quit"),
+    ]
+
+    def __init__(self, update: PackageUpdate, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._update = update
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        with VerticalScroll(id="details"):
+            yield Static(id="detail-body")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        update = self._update
+        text = Text()
+        text.append("PACKAGE DETAILS\n", style="bold")
+        text.append("\n")
+        text.append(f"Name:       {update.name}\n")
+        text.append(f"Current:    {update.current_version or 'Unknown'}\n")
+        text.append(f"Available:  {update.new_version or 'Unknown'}\n")
+        text.append("\n")
+        text.append(f"Download:   {format_bytes(update.download_size)}\n")
+        text.append(f"Install:    {format_bytes(update.installed_size)}\n")
+        text.append("\n")
+        label = _PRIORITY_LABEL.get(update.priority.value, "MEDIUM")
+        text.append(f"Priority:   {label}\n", style="bold")
+        text.append("\n")
+        text.append("WHY?\n", style="underline")
+        for reason in update.priority_reasons or ["No metadata available."]:
+            text.append(f"✓ {reason}\n")
+        text.append("\n")
+        security = "Unknown"
+        if update.security_update is True:
+            security = "Yes"
+        elif update.security_update is False:
+            security = "No"
+        text.append(f"Security status: {security}\n")
+        reboot = "Unknown"
+        if update.reboot_required is True:
+            reboot = "Likely (kernel)"
+        elif update.reboot_required is False:
+            reboot = "No"
+        text.append(f"Likely reboot:   {reboot}\n")
+        text.append(f"Package manager: {update.package_manager}\n")
+        self.query_one("#detail-body", Static).update(text)
+
+    def action_update_package(self) -> None:
+        self.app.push_screen(ConfirmScreen([self._update]))
+
+
+class ConfirmScreen(ModalScreen):
+    """Explicit-update gate. Default answer is always No."""
+
+    BINDINGS = [
+        Binding("escape", "decline", "Back"),
+        Binding("y", "accept", "Yes"),
+        Binding("n", "decline", "No"),
+    ]
+
+    def __init__(self, updates: List[PackageUpdate], **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._updates = updates
+
+    def compose(self) -> ComposeResult:
+        download = sum(u.download_size for u in self._updates if u.download_size)
+        install = sum(u.installed_size for u in self._updates if u.installed_size)
+        names = ", ".join(sorted(u.name for u in self._updates))
+        body = Text()
+        body.append("\n")
+        body.append(f"You selected {len(self._updates)} packages.\n\n")
+        body.append(f"Packages: {names}\n\n")
+        body.append(f"Download: {format_bytes(download)}\n")
+        body.append(f"Estimated disk usage: {format_bytes(install)}\n\n")
+        body.append("Continue? [y/N]  ", style="bold")
+        yield Static(body)
+        yield Footer()
+
+    def action_accept(self) -> None:
+        self.app.pop_screen()
+        self.app.proceed_with_updates(self._updates)
+
+    def action_decline(self) -> None:
+        self.app.pop_screen()
+
+
+class BlockedScreen(ModalScreen):
+    """Shown instead of an update when a safety check fails."""
+
+    BINDINGS = [Binding("escape", "app.pop_screen", "Back"), Binding("q", "quit", "Quit")]
+
+    def __init__(self, title: str, message: str, detail: str = "", **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._title = title
+        self._message = message
+        self._detail = detail
+
+    def compose(self) -> ComposeResult:
+        body = Text()
+        body.append(f"{self._title}\n", style="bold red")
+        body.append("\n")
+        body.append(self._message)
+        if self._detail:
+            body.append("\n\n")
+            body.append(self._detail, style="dim")
+        body.append("\n\n[ESC] Back", style="dim")
+        yield Static(body)
+        yield Footer()
+
+
+class ResultScreen(Screen):
+    """Post-update report: what happened and (usually) what to run manually."""
+
+    BINDINGS = [Binding("escape", "app.pop_screen", "Back"), Binding("q", "quit", "Quit")]
+
+    def __init__(self, title: str, body: Text | str, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._title = title
+        self._body = body
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        text = Text(f"{self._title}\n\n", style="bold")
+        if isinstance(self._body, Text):
+            text.append_text(self._body)
+        else:
+            text.append(str(self._body))
+        yield Static(text)
+        yield Footer()
+
+
+class ErrorScreen(ModalScreen):
+    """Human-readable error report — never a raw traceback by default."""
+
+    BINDINGS = [Binding("escape", "app.pop_screen", "Back"), Binding("q", "quit", "Quit")]
+
+    def __init__(self, title: str, message: str, detail: str = "", **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._title = title
+        self._message = message
+        self._detail = detail
+
+    def compose(self) -> ComposeResult:
+        body = Text()
+        body.append(f"⚠ {self._title}\n", style="bold red")
+        body.append("\n")
+        body.append(self._message)
+        if self._detail:
+            body.append("\n\nDetail:\n", style="dim")
+            body.append(self._detail, style="dim")
+        body.append("\n\n[ESC] Back", style="dim")
+        yield Static(body)
+        yield Footer()
+
+
+def render_storage_block(storage: StorageInfo, width: int) -> Text:
+    """Compose the storage text block including the progress bar."""
+    return storage_summary_text(storage, width)

pkgwise/ui/widgets.py

@@ -0,0 +1,57 @@
+"""Reusable TUI widgets.
+
+Kept deliberately small: a progress-bar renderer and a storage summary
+builder that adapt to the current terminal width (no hard-coded dimensions).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from rich.text import Text
+from textual.widgets import Static
+
+from pkgwise.core.models import StorageInfo
+from pkgwise.utils.formatting import format_bytes
+
+
+def progress_text(percentage: float, width: Optional[int] = None) -> Text:
+    """Render a percentage as a filled █/░ progress bar at *width* columns."""
+    if width is None:
+        width = 24
+    width = max(width, 6)
+    inner = width - 2
+    filled = int(round((min(max(percentage, 0.0), 100.0) / 100.0) * inner))
+    bar = "█" * filled + "░" * (inner - filled)
+    label = f" {percentage:.0f}%"
+    return Text(bar + label)
+
+
+def storage_summary_text(
+    storage: StorageInfo, width: Optional[int] = None
+) -> Text:
+    """Multi-line Rich Text describing an :class:`StorageInfo` snapshot."""
+    if width is None:
+        width = 24
+    bar = progress_text(storage.usage_percentage, width)
+    text = Text()
+    text.append("STORAGE\n", style="bold")
+    text.append(bar)
+    text.append("\n")
+    text.append(
+        f"{format_bytes(storage.used_bytes)} used / "
+        f"{format_bytes(storage.total_bytes)}"
+    )
+    text.append("     ", style="dim")
+    text.append(f"{format_bytes(storage.free_bytes)} free", style="dim")
+    return text
+
+
+def make_status_widget(inner: bool = False) -> type:
+    """Return a lightweight Static subclass for status lines."""
+    return Static
+
+
+def short_size(download: Optional[int], installed: Optional[int]) -> str:
+    """One compact size string, preferring download size for tables."""
+    return format_bytes(download if download is not None else installed)

pkgwise/utils/__init__.py

@@ -0,0 +1 @@
+"""Small helpers for command execution, distro detection, formatting and config."""

pkgwise/utils/commands.py

@@ -0,0 +1,98 @@
+"""Safe subprocess helpers.
+
+All package-manager interaction goes through :func:`run_command`. Commands are
+always executed as argument lists with ``shell=False`` — never via a shell
+string — so no package metadata or user input can ever be interpreted as a
+shell instruction.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    """Result of a successfully executed command."""
+
+    stdout: str
+    stderr: str
+    returncode: int
+
+
+class CommandError(Exception):
+    """Raised when a command cannot be run or exits with a failure code."""
+
+    def __init__(self, command: List[str], message: str, returncode: Optional[int] = None):
+        self.command = list(command)
+        self.message = message
+        self.returncode = returncode
+        super().__init__(message)
+
+
+class CommandNotFoundError(CommandError):
+    """Raised when the executable for a command does not exist."""
+
+
+def which(executable: str) -> Optional[str]:
+    """Return the path to *executable* or ``None`` if it is not on ``PATH``."""
+    import shutil
+
+    return shutil.which(executable)
+
+
+def run_command(
+    command: List[str],
+    timeout: Optional[int] = 120,
+    check: bool = True,
+    env: Optional[dict] = None,
+) -> CommandResult:
+    """Run *command* (an argument list) and return its captured output.
+
+    Prefer this over direct ``subprocess`` calls everywhere so error handling
+    stays consistent. ``timeout=None`` waits indefinitely (used for long,
+    interactive installs that the TUI runs with its own progress handling).
+
+    Raises:
+        CommandNotFoundError: the executable is not available.
+        CommandError: the command failed (return code != 0) and ``check``.
+        TimeoutExpired: the command exceeded *timeout* seconds.
+    """
+    if not command:
+        raise ValueError("run_command requires a non-empty command list")
+
+    executable = command[0]
+    path = which(executable)
+    if path is None:
+        raise CommandNotFoundError(command, f"Command not found: {executable}")
+
+    proc = subprocess.run(
+        [path, *command[1:]],
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        env=env,
+        check=False,
+    )
+    if check and proc.returncode != 0:
+        raise CommandError(
+            command,
+            f"Command exited with status {proc.returncode}: {' '.join(command)}",
+            returncode=proc.returncode,
+        )
+    return CommandResult(stdout=proc.stdout or "", stderr=proc.stderr or "", returncode=proc.returncode)
+
+
+def is_elevated() -> bool:
+    """Return whether the current process has elevated privileges (root).
+
+    ``os.geteuid()`` is not available on non-POSIX systems; guard it so the
+    check degrades to ``False`` (requiring elevation) elsewhere.
+    """
+    try:
+        return os.geteuid() == 0
+    except AttributeError:  # pragma: no cover - non-POSIX
+        return False

pkgwise/utils/config.py

@@ -0,0 +1,134 @@
+"""Configuration loading for PkgWise.
+
+The MVP reads a single optional TOML file at ``~/.config/pkgwise/config.toml``.
+Unknown keys are ignored, missing keys fall back to built-in defaults, and a
+malformed config file never crashes the application — it produces a warning
+string instead.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+try:  # Python 3.11+
+    import tomllib
+
+    _TOMLLI_LOAD = tomllib.load
+except ImportError:  # Python 3.9/3.10 — optional backport
+    try:
+        import tomli  # type: ignore[import-not-found]
+
+        _TOMLLI_LOAD = tomli.load
+    except ImportError:
+        _TOMLLI_LOAD = None  # config will degrade to defaults with a warning
+
+
+@dataclass(frozen=True)
+class PkgWiseConfig:
+    """Effective configuration for the current run."""
+
+    show_low_priority: bool = True
+    show_download_size: bool = True
+    show_install_size: bool = True
+    confirm_before_update: bool = True
+    config_path: Optional[str] = None
+    warnings: List[str] = field(default_factory=list)
+
+
+_DEFAULTS = {
+    "display": {
+        "show_low_priority": True,
+        "show_download_size": True,
+        "show_install_size": True,
+    },
+    "updates": {
+        "confirm_before_update": True,
+    },
+}
+
+
+def default_config_path() -> Path:
+    """Path of the per-user config file (``$XDG_CONFIG_HOME`` aware)."""
+    base = os.environ.get("XDG_CONFIG_HOME")
+    if base:
+        return Path(base) / "pkgwise" / "config.toml"
+    return Path.home() / ".config" / "pkgwise" / "config.toml"
+
+
+def load_config() -> PkgWiseConfig:
+    """Load configuration from the default user location.
+
+    Never raises; unsupported/malformed files downgrade to defaults with an
+    explanatory warning.
+    """
+    path = default_config_path()
+    if not path.is_file():
+        return PkgWiseConfig()
+
+    return load_config_file(path)
+
+
+def load_config_file(path: Path) -> PkgWiseConfig:
+    """Load configuration from a specific TOML *path* (used by tests/CLI)."""
+    warnings: List[str] = []
+    try:
+        data = _parse_toml(path)
+    except OSError as exc:
+        return PkgWiseConfig(
+            config_path=str(path), warnings=[f"Could not read {path}: {exc}"]
+        )
+    except Exception as exc:
+        return PkgWiseConfig(
+            config_path=str(path), warnings=[f"Config file {path} is invalid: {exc}"]
+        )
+
+    merged = _merge_defaults(data)
+    return PkgWiseConfig(
+        show_low_priority=_as_bool(merged["display"]["show_low_priority"], True),
+        show_download_size=_as_bool(merged["display"]["show_download_size"], True),
+        show_install_size=_as_bool(merged["display"]["show_install_size"], True),
+        confirm_before_update=_as_bool(merged["updates"]["confirm_before_update"], True),
+        config_path=str(path),
+        warnings=warnings,
+    )
+
+
+def _parse_toml(path: Path) -> dict:
+    if _TOMLLI_LOAD is None:
+        raise RuntimeError(
+            "A TOML parser is unavailable on this Python (need 3.11+ or 'tomli')."
+        )
+    with open(path, "rb") as fh:
+        return _TOMLLI_LOAD(fh)
+
+
+def _merge_defaults(raw: dict) -> dict:
+    merged = {
+        section: dict(defaults)
+        for section, defaults in _DEFAULTS.items()
+    }
+    for section, defaults in _DEFAULTS.items():
+        theirs = raw.get(section)
+        if not isinstance(theirs, dict):
+            continue
+        for key in defaults:
+            if key in theirs:
+                merged[section][key] = theirs[key]
+    return merged
+
+
+def _as_bool(value: object, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in {"true", "yes", "on", "1"}:
+            return True
+        if lowered in {"false", "no", "off", "0"}:
+            return False
+    if isinstance(value, int) and value in (0, 1):
+        return bool(value)
+    return default