pkgwise 0.1.0__py3-none-any.whl

pkgwise/cli.py

@@ -0,0 +1,222 @@
+"""Command-line interface.
+
+Kept strictly separate from the TUI so ``pkgwise check`` / ``updates`` /
+``storage`` work without a terminal UI or Textual installed.
+
+Subcommands
+-----------
+``pkgwise``          launch the interactive TUI
+``pkgwise check``    one-shot analysis: storage + update counts + sizes
+``pkgwise updates``  list updates as plain text with priorities
+``pkgwise storage``  print filesystem usage only
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from pkgwise import __version__
+from pkgwise.core import analyzer as analyzer_mod
+from pkgwise.core.models import AnalysisResult, Priority
+from pkgwise.utils import distro as distro_utils
+from pkgwise.utils.formatting import format_bytes
+
+_TUI_IMPORT_ERROR = (
+    "The interactive interface needs the optional 'tui' extra.\n"
+    "Install it with:  python -m pip install 'pkgwise[tui]'"
+)
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    """Entry point installed as the ``pkgwise`` console script."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        _dispatch(parser, args)
+    except KeyboardInterrupt:
+        print("\nInterrupted.")
+        raise SystemExit(130)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pkgwise",
+        description="Know what you're updating before you update. "
+        "Analyzes available Linux package updates.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"pkgwise {__version__}"
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    analyze_parser(sub, "check", "One-shot analysis of storage and available updates")
+    analyze_parser(sub, "updates", "List available updates with priorities")
+    analyze_parser(sub, "storage", "Show filesystem usage only")
+
+    return parser
+
+
+def analyze_parser(subparsers, name: str, help_text: str) -> None:
+    parser = subparsers.add_parser(name, help=help_text)
+    parser.add_argument(
+        "--refresh",
+        action="store_true",
+        help="Refresh the package index before listing updates",
+    )
+    parser.add_argument(
+        "--plain", action="store_true", help="Disable emoji and ANSI color"
+    )
+
+
+def _dispatch(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:
+    command = args.command
+    if command is None:
+        _launch_tui()
+        return
+
+    try:
+        if command == "storage":
+            _print_storage_only(plain=args.plain)
+            return
+        analysis = analyzer_mod.analyze()
+        if args.refresh:
+            analysis = analyzer_mod.refresh_updates(analysis)
+    except Exception as exc:
+        print(f"⚠ Unable to check for updates.\n\n{_friendly_cli_error(exc)}", file=sys.stderr)
+        raise SystemExit(1)
+
+    if command == "check":
+        _print_check(analysis, plain=args.plain)
+    elif command == "updates":
+        _print_updates(analysis, plain=args.plain)
+    else:  # pragma: no cover - argparse rejects unknown commands
+        parser.print_help()
+
+
+def _print_storage_only(plain: bool = False) -> None:
+    """Storage needs no package manager — print it directly."""
+    from pkgwise.core import storage as storage_mod
+
+    info = storage_mod.get_storage_info()
+    from pkgwise.core.models import SystemInfo
+
+    system = SystemInfo(
+        distro_name=distro_utils.get_system_info().distro_name,
+        package_manager=distro_utils.get_system_info().package_manager,
+    )
+    _print_storage(AnalysisResult(storage=info, system=system, updates=[]), plain=plain)
+
+
+def _friendly_cli_error(exc: Exception) -> str:
+    from pkgwise.utils import distro as distro_utils
+
+    base = str(exc) or exc.__class__.__name__
+    if "not recognized" in base or "unsupported" in base or "not found" in base:
+        return (
+            f"{base}\n\n"
+            "Check that your package manager is installed and your distribution "
+            "is supported: Arch Linux (pacman) or Debian/Kali/Ubuntu (apt)."
+        )
+    return (
+        f"{base}\n\n"
+        "The package manager returned an error.\n"
+        "Check your network connection and package-manager configuration."
+    )
+
+
+def _launch_tui() -> None:
+    """Start the Textual app, with a helpful message if it is missing."""
+    try:
+        from pkgwise.ui.app import PkgWiseApp
+    except ImportError:  # Textual not installed
+        print(_TUI_IMPORT_ERROR, file=sys.stderr)
+        raise SystemExit(1)
+
+    PkgWiseApp().run()
+
+
+def _print_storage(analysis: AnalysisResult, plain: bool = False) -> None:
+    info = analysis.storage
+    print("STORAGE")
+    print(f"  Total : {format_bytes(info.total_bytes)}")
+    print(f"  Used  : {format_bytes(info.used_bytes)}")
+    print(f"  Free  : {format_bytes(info.free_bytes)}")
+    print(f"  Usage : {info.usage_percentage:.1f}%")
+    if not plain:
+        print(f"  System: {analysis.system.distro_name} "
+              f"({analysis.system.package_manager})")
+
+
+def _print_check(analysis: AnalysisResult, plain: bool = False) -> None:
+    _print_storage(analysis, plain=plain)
+    print()
+    _print_update_summary(analysis, plain=plain)
+
+
+def _print_update_summary(analysis: AnalysisResult, plain: bool = False) -> None:
+    updates = analysis.updates
+    print("UPDATES")
+    if not updates:
+        print("  System is up to date.")
+        return
+    download = _total_download(updates)
+    install = _total_install(updates)
+    print(f"  Available : {len(updates)}")
+    print(f"  Download  : {download}")
+    print(f"  Install   : {install}")
+    cr = sum(1 for u in updates if u.priority == Priority.CRITICAL)
+    hi = sum(1 for u in updates if u.priority == Priority.HIGH)
+    me = sum(1 for u in updates if u.priority == Priority.MEDIUM)
+    lo = sum(1 for u in updates if u.priority == Priority.LOW)
+    if not plain:
+        print(f"  CRITICAL  : {cr}")
+        print(f"  HIGH      : {hi}")
+        print(f"  MEDIUM    : {me}")
+        print(f"  LOW       : {lo}")
+
+
+def _print_updates(analysis: AnalysisResult, plain: bool = False) -> None:
+    _print_storage(analysis, plain=plain)
+    print()
+    _print_update_summary(analysis, plain=plain)
+    updates = analysis.updates
+    if not updates:
+        return
+    print()
+    order = {
+        Priority.CRITICAL: 0,
+        Priority.HIGH: 1,
+        Priority.MEDIUM: 2,
+        Priority.LOW: 3,
+    }
+    for update in sorted(updates, key=lambda u: (order[u.priority], u.name)):
+        tag = "" if plain else f"{_EMOJI[update.priority]} "
+        size = format_bytes(update.download_size)
+        current = update.current_version or "?"
+        new = update.new_version or "?"
+        print(f"{tag}{update.name:<24} {current:<16} -> {new:<16} {size:>10}")
+
+
+_EMOJI = {
+    Priority.CRITICAL: "CRIT",
+    Priority.HIGH: "HIGH",
+    Priority.MEDIUM: "MED ",
+    Priority.LOW: "LOW ",
+}
+
+
+def _total_download(updates) -> str:
+    known = [u.download_size for u in updates if u.download_size is not None]
+    return format_bytes(sum(known)) if known else "Unknown"
+
+
+def _total_install(updates) -> str:
+    known = [u.installed_size for u in updates if u.installed_size is not None]
+    return format_bytes(sum(known)) if known else "Unknown"
+
+
+if __name__ == "__main__":
+    main()

pkgwise/core/__init__.py

@@ -0,0 +1 @@
+"""Core domain logic: models, storage, priority analysis and the analyzer."""

pkgwise/core/analyzer.py

@@ -0,0 +1,169 @@
+"""High-level analysis and update orchestration.
+
+This is the single entry point the CLI and TUI use. It hides the backend
+abstraction, storage detection and priority scoring behind a few focused
+functions, and it is where all *safety* checks for real updates live:
+
+- updates are never run automatically;
+- the exact command is always shown before running it;
+- disk-space and privilege checks gate execution;
+- nothing is ever removed or cleaned automatically.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import List, Optional
+
+from pkgwise.backends.factory import get_backend
+from pkgwise.core import storage as storage_mod
+from pkgwise.core.models import AnalysisResult, PackageUpdate, StorageInfo, SystemInfo
+from pkgwise.core.priority import analyze_priority
+from pkgwise.utils import distro as distro_utils
+
+
+def analyze(distro_name: str = "", package_manager: str = "") -> AnalysisResult:
+    """Produce a full analysis snapshot: storage + system + prioritized updates."""
+    system = SystemInfo(
+        distro_name=distro_name or distro_utils.get_system_info().distro_name,
+        distro_version=distro_utils.get_system_info().distro_version,
+        package_manager=package_manager or distro_utils.get_system_info().package_manager,
+    )
+    storage = storage_mod.get_storage_info()
+    updates = _load_updates(system.package_manager, distro_name=system.distro_name)
+    updates = _prioritize(updates)
+    return AnalysisResult(storage=storage, system=system, updates=updates)
+
+
+def _load_updates(package_manager: str, distro_name: str) -> List[PackageUpdate]:
+    backend = get_backend(distro_name=distro_name, package_manager=package_manager)
+    return backend.check_updates()
+
+
+def _prioritize(updates: List[PackageUpdate]) -> List[PackageUpdate]:
+    result: List[PackageUpdate] = []
+    for update in updates:
+        priority, reasons = analyze_priority(update)
+        result.append(update.prioritized(priority, reasons))
+    return result
+
+
+def refresh_updates(analysis: AnalysisResult) -> AnalysisResult:
+    """Re-run the analysis after refreshing the package index (``list_updates``)."""
+    backend = get_backend(
+        distro_name=analysis.system.distro_name,
+        package_manager=analysis.system.package_manager,
+    )
+    updates = _prioritize(backend.list_updates())
+    return AnalysisResult(
+        storage=analysis.storage,
+        system=analysis.system,
+        updates=updates,
+        warnings=analysis.warnings,
+    )
+
+
+class UpdateGated(Exception):
+    """Raised when a safety check blocks an update before execution."""
+
+    pass
+
+
+class InsufficientDiskSpace(UpdateGated):
+    """Raised when the system does not have enough free space for an update."""
+
+    def __init__(self, available: int, required: int):
+        self.available = available
+        self.required = required
+        super().__init__("Insufficient disk space for the planned update.")
+
+
+class RequiresElevation(UpdateGated):
+    """Raised when updating requires root and none is available."""
+
+    def __init__(self, message: str, command: List[str]):
+        self.message = message
+        self.command = command
+        super().__init__(message)
+
+
+def prepare_update(
+    selected: List[PackageUpdate],
+    storage: Optional[StorageInfo] = None,
+) -> None:
+    """Validate that *selected* can be safely updated. Raises on problems.
+
+    Checks, in order: an empty selection, sufficient free disk space, and that
+    the deep command (``pacman``/``apt``) can reach elevation. PkgWise never
+    runs anything itself — the TUI runs the resulting command only after the
+    user confirms it.
+    """
+    if not selected:
+        raise UpdateGated("No packages selected.")
+
+    storage = storage or storage_mod.get_storage_info()
+
+    required = _estimated_required_bytes(selected)
+    if required is not None and required > storage.free_bytes:
+        raise InsufficientDiskSpace(available=storage.free_bytes, required=required)
+
+    names = [u.name for u in selected]
+    backend = get_backend()
+    command = _elevated_command(backend.install_command(names))
+    _ensure_elevation(command)
+
+
+def _elevated_command(command: List[str]) -> List[str]:
+    """Prefix ``sudo`` when the command requires root and sudo is available."""
+    from pkgwise.utils.commands import is_elevated, which
+
+    if not is_elevated() and which("sudo"):
+        return ["sudo", *command]
+    return command
+
+
+def _estimated_required_bytes(selected: List[PackageUpdate]) -> Optional[int]:
+    """Best-effort estimate of disk space the update will use.
+
+    Uses installed sizes when present; falls back to download sizes. ``None``
+    when no sizes are available (the safety check is skipped in that case).
+    """
+    known = [
+        u.installed_size
+        for u in selected
+        if u.installed_size is not None
+    ]
+    if known:
+        return sum(known)
+    downloads = [
+        u.download_size
+        for u in selected
+        if u.download_size is not None
+    ]
+    return sum(downloads) if downloads else None
+
+
+def _ensure_elevation(command: List[str]) -> None:
+    """Fail with an explanation when the command cannot gain root."""
+    from pkgwise.utils.commands import is_elevated
+
+    if is_elevated():
+        return
+
+    from pkgwise.utils.commands import which
+
+    sudo = which("sudo")
+    if sudo is None:
+        raise RequiresElevation(
+            "Elevated privileges are required to update packages, but no "
+            "password-elevation tool (such as sudo) is available.",
+            command=command,
+        )
+    # sudo exists; the TUI will invoke it for the user to authenticate.
+    return
+
+
+def display_command(names: List[str]) -> List[str]:
+    """Human-visible command PkgWise would run for *names* (used for confirmation)."""
+    backend = get_backend()
+    return _elevated_command(backend.install_command(names))

pkgwise/core/models.py

@@ -0,0 +1,126 @@
+"""Typed data models for PkgWise.
+
+These are plain dataclasses (no runtime dependency); Pydantic is deliberately
+avoided for the MVP because nothing here needs coercion or schema generation.
+Unknown data is represented as ``None`` and rendered as "Unknown" by the UI.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from enum import Enum
+from typing import List, Optional
+
+
+class Priority(Enum):
+    """Priority levels assigned by :mod:`pkgwise.core.priority`."""
+
+    CRITICAL = 4
+    HIGH = 3
+    MEDIUM = 2
+    LOW = 1
+
+    @property
+    def label(self) -> str:
+        return self.name.title()
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        return self.name
+
+
+@dataclass(frozen=True)
+class StorageInfo:
+    """Snapshot of disk usage for a filesystem."""
+
+    path: str
+    total_bytes: int
+    used_bytes: int
+    free_bytes: int
+
+    @property
+    def usage_percentage(self) -> float:
+        """Usage percentage (0.0-100.0); 0 when total is unknown/zero."""
+        if self.total_bytes <= 0:
+            return 0.0
+        return (self.used_bytes / self.total_bytes) * 100.0
+
+
+@dataclass(frozen=True)
+class PackageUpdate:
+    """A single available package update."""
+
+    name: str
+    current_version: Optional[str] = None
+    new_version: Optional[str] = None
+    download_size: Optional[int] = None
+    installed_size: Optional[int] = None
+    security_update: Optional[bool] = None
+    reboot_required: Optional[bool] = None
+    core: Optional[bool] = None
+    package_manager: str = "unknown"
+
+    # Assigned by the priority analyzer, not by the backend parser.
+    priority: Priority = Priority.MEDIUM
+    priority_reasons: List[str] = field(default_factory=list)
+
+    def prioritized(self, priority: Priority, reasons: List[str]) -> "PackageUpdate":
+        """Return a copy of this update with priority metadata attached."""
+        return replace(self, priority=priority, priority_reasons=list(reasons))
+
+    @property
+    def display_current(self) -> str:
+        return self.current_version or "Unknown"
+
+    @property
+    def display_new(self) -> str:
+        return self.new_version or "Unknown"
+
+    @property
+    def has_versions(self) -> bool:
+        return bool(self.current_version and self.new_version)
+
+
+@dataclass(frozen=True)
+class UpdateSummary:
+    """Aggregate information about a set of package updates."""
+
+    updates: List[PackageUpdate] = field(default_factory=list)
+
+    @property
+    def count(self) -> int:
+        return len(self.updates)
+
+    @property
+    def total_download_bytes(self) -> Optional[int]:
+        """Sum of known download sizes; ``None`` when none are known."""
+        known = [u.download_size for u in self.updates if u.download_size is not None]
+        return sum(known) if known else None
+
+    @property
+    def total_install_bytes(self) -> Optional[int]:
+        """Sum of known installed sizes; ``None`` when none are known."""
+        known = [u.installed_size for u in self.updates if u.installed_size is not None]
+        return sum(known) if known else None
+
+    @property
+    def security_count(self) -> int:
+        return sum(1 for u in self.updates if u.security_update)
+
+
+@dataclass(frozen=True)
+class SystemInfo:
+    """Detected system context passed down to analysis."""
+
+    distro_name: str
+    distro_version: str = ""
+    package_manager: str = "unknown"
+
+
+@dataclass(frozen=True)
+class AnalysisResult:
+    """Everything the analysis stage produces in one call."""
+
+    storage: StorageInfo
+    system: SystemInfo
+    updates: List[PackageUpdate]
+    warnings: List[str] = field(default_factory=list)