pkgwise 0.1.0__tar.gz

pkgwise-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PkgWise Developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pkgwise-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: pkgwise
+Version: 0.1.0
+Summary: Know what you're updating before you update — a smart Linux update analyzer.
+Author: PkgWise Developers
+License: MIT
+Project-URL: Homepage, https://github.com/Senpi-Station/PkgWise
+Project-URL: Repository, https://github.com/Senpi-Station/PkgWise
+Project-URL: Issues, https://github.com/Senpi-Station/PkgWise/issues
+Project-URL: Changelog, https://github.com/Senpi-Station/PkgWise/blob/main/CHANGELOG.md
+Keywords: linux,packages,updates,pacman,apt,tui,system-administration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil<7,>=5.9
+Requires-Dist: textual<2,>=0.60
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov>=4; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; python_version >= "3.9" and extra == "test"
+Dynamic: license-file
+
+<h1 align="center">PkgWise</h1>
+
+<p align="center">
+  <b>Know what you're updating before you update.</b><br/>
+  A conservative Linux package-update analyzer for Arch (pacman) and Debian-family (apt) systems.
+</p>
+
+<p align="center">
+  <a href="https://github.com/Senpi-Station/PkgWise/actions"><img src="https://github.com/Senpi-Station/PkgWise/actions/workflows/ci.yaml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python 3.9+"></a>
+</p>
+
+PkgWise checks for available updates **without installing anything**, shows you what
+is waiting (name, versions, sizes, security and reboot hints), scores each update with
+a **transparent, conservative priority**, and only ever runs a real update after you
+explicitly confirm the exact command.
+
+## Features
+
+- **Dual package managers** — `pacman` (Arch) and `apt-get`/`apt-cache` (Debian, Kali, Ubuntu).
+- **Sizes you can plan with** — download and installed sizes are read from the package
+  manager's own metadata, never guessed.
+- **Transparent priorities** — every CRITICAL/HIGH/MEDIUM/LOW label comes with the
+  human-readable reasons behind it. Unknown facts are shown as “Unknown”, never invented.
+- **Security-first updates** — nothing runs automatically, nothing is removed or cleaned,
+  empty selections can never trigger a full-system upgrade, and disk-space + privilege
+  checks gate every real update.
+- **Two interfaces** — a fast terminal CLI and a Textual TUI with selection, detail and
+  confirmation screens.
+- **Mock mode** — preview the whole tool on any machine without touching a real package
+  manager.
+
+## Installation
+
+```bash
+pip install pkgwise          # core (storage + CLI)
+pip install "pkgwise[all]"   # + TUI (textual) and enhanced storage stats (psutil)
+```
+
+Requires Python 3.9+. Works on Arch-based and Debian-based Linux systems.
+
+## Quick start
+
+```console
+$ pkgwise check                 # storage summary + available updates, prioritized
+$ pkgwise updates               # just the pending updates
+$ pkgwise storage               # disk information only (no package manager needed)
+$ pkgwise --refresh             # refresh package indexes first (network)
+$ pkgwise                      # launch the interactive TUI
+$ pkgwise --version             # version and system info
+```
+
+## Example output
+
+```
+STORAGE
+  Total : 291.4 GB
+  Used  : 87.3 GB
+  Free  : 189.2 GB
+  Usage : 30.0%
+  System: Arch Linux (pacman)
+
+UPDATES (3 available, ~150 MB to download)
+  🔴 CRITICAL  openssl          3.0.1 -> 3.0.2   Security-related update        (2.5 MB / 9 MB)
+  🟠 HIGH      linux            6.0.1 -> 6.0.2   Kernel package — needs reboot  (38 MB / 700 MB)
+  🟡 MEDIUM    figlet           2.2.5 -> 2.2.6   No security metadata detected  (0.5 MB / 1 MB)
+```
+
+## How priorities work
+
+PkgWise collects only **observable facts** about a package — security metadata, whether it
+is a kernel, a core system component or a system library — and maps them through a small,
+documented scoring table in `pkgwise/core/priority.py`. Labels always come with their
+reasons, so nothing is ever marked important without an explanation.
+
+## Safety model
+
+| Guarantee | Where enforced |
+| --- | --- |
+| Nothing runs automatically | `cli.py`, TUI confirm screens |
+| Exact command shown before running | backends' `install_command()` |
+| Empty selection can't upgrade everything | backends return `[]` for empty selections |
+| Disk-space check before install | `analyzer.prepare_update()` |
+| Privilege check before install | `analyzer.prepare_update()` |
+| No packages removed or cleaned | analyzer never invokes remove/clean |
+
+## Development
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[all,test]"
+pytest
+```
+
+See [CONTRIBUTING](docs/CONTRIBUTING.md) and [DEVELOPMENT](docs/DEVELOPMENT.md).
+
+## License
+
+Released under the [MIT License](LICENSE).

pkgwise-0.1.0/README.md

@@ -0,0 +1,100 @@
+<h1 align="center">PkgWise</h1>
+
+<p align="center">
+  <b>Know what you're updating before you update.</b><br/>
+  A conservative Linux package-update analyzer for Arch (pacman) and Debian-family (apt) systems.
+</p>
+
+<p align="center">
+  <a href="https://github.com/Senpi-Station/PkgWise/actions"><img src="https://github.com/Senpi-Station/PkgWise/actions/workflows/ci.yaml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python 3.9+"></a>
+</p>
+
+PkgWise checks for available updates **without installing anything**, shows you what
+is waiting (name, versions, sizes, security and reboot hints), scores each update with
+a **transparent, conservative priority**, and only ever runs a real update after you
+explicitly confirm the exact command.
+
+## Features
+
+- **Dual package managers** — `pacman` (Arch) and `apt-get`/`apt-cache` (Debian, Kali, Ubuntu).
+- **Sizes you can plan with** — download and installed sizes are read from the package
+  manager's own metadata, never guessed.
+- **Transparent priorities** — every CRITICAL/HIGH/MEDIUM/LOW label comes with the
+  human-readable reasons behind it. Unknown facts are shown as “Unknown”, never invented.
+- **Security-first updates** — nothing runs automatically, nothing is removed or cleaned,
+  empty selections can never trigger a full-system upgrade, and disk-space + privilege
+  checks gate every real update.
+- **Two interfaces** — a fast terminal CLI and a Textual TUI with selection, detail and
+  confirmation screens.
+- **Mock mode** — preview the whole tool on any machine without touching a real package
+  manager.
+
+## Installation
+
+```bash
+pip install pkgwise          # core (storage + CLI)
+pip install "pkgwise[all]"   # + TUI (textual) and enhanced storage stats (psutil)
+```
+
+Requires Python 3.9+. Works on Arch-based and Debian-based Linux systems.
+
+## Quick start
+
+```console
+$ pkgwise check                 # storage summary + available updates, prioritized
+$ pkgwise updates               # just the pending updates
+$ pkgwise storage               # disk information only (no package manager needed)
+$ pkgwise --refresh             # refresh package indexes first (network)
+$ pkgwise                      # launch the interactive TUI
+$ pkgwise --version             # version and system info
+```
+
+## Example output
+
+```
+STORAGE
+  Total : 291.4 GB
+  Used  : 87.3 GB
+  Free  : 189.2 GB
+  Usage : 30.0%
+  System: Arch Linux (pacman)
+
+UPDATES (3 available, ~150 MB to download)
+  🔴 CRITICAL  openssl          3.0.1 -> 3.0.2   Security-related update        (2.5 MB / 9 MB)
+  🟠 HIGH      linux            6.0.1 -> 6.0.2   Kernel package — needs reboot  (38 MB / 700 MB)
+  🟡 MEDIUM    figlet           2.2.5 -> 2.2.6   No security metadata detected  (0.5 MB / 1 MB)
+```
+
+## How priorities work
+
+PkgWise collects only **observable facts** about a package — security metadata, whether it
+is a kernel, a core system component or a system library — and maps them through a small,
+documented scoring table in `pkgwise/core/priority.py`. Labels always come with their
+reasons, so nothing is ever marked important without an explanation.
+
+## Safety model
+
+| Guarantee | Where enforced |
+| --- | --- |
+| Nothing runs automatically | `cli.py`, TUI confirm screens |
+| Exact command shown before running | backends' `install_command()` |
+| Empty selection can't upgrade everything | backends return `[]` for empty selections |
+| Disk-space check before install | `analyzer.prepare_update()` |
+| Privilege check before install | `analyzer.prepare_update()` |
+| No packages removed or cleaned | analyzer never invokes remove/clean |
+
+## Development
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[all,test]"
+pytest
+```
+
+See [CONTRIBUTING](docs/CONTRIBUTING.md) and [DEVELOPMENT](docs/DEVELOPMENT.md).
+
+## License
+
+Released under the [MIT License](LICENSE).

pkgwise-0.1.0/pkgwise/__init__.py

@@ -0,0 +1,12 @@
+"""PkgWise — Smart Linux Update Analyzer.
+
+Know what you're updating before you update.
+
+PkgWise is an analysis-first package update assistant. It uses the native
+package manager (currently ``pacman`` and ``apt``) as its backend and provides
+a better interface for understanding and selecting package updates.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

pkgwise-0.1.0/pkgwise/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point: ``python -m pkgwise``."""
+
+from pkgwise.cli import main
+
+if __name__ == "__main__":
+    main()

pkgwise-0.1.0/pkgwise/backends/__init__.py

@@ -0,0 +1 @@
+"""Package-manager backends: pacman (Arch), apt (Debian) and the shared interface."""

pkgwise-0.1.0/pkgwise/backends/arch.py

@@ -0,0 +1,223 @@
+"""Arch Linux backend — wraps the ``pacman`` package manager.
+
+Parser details
+--------------
+``pacman -Qu`` lists outdated packages as ``name current => new``.
+``pacman -Si <name>...`` reads the local sync databases (no network) and
+reports per-package ``Download Size`` and ``Installed Size`` for the *new*
+version, so sizes are realistic for planning an update.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Optional
+
+from pkgwise.backends.base import InstallError, PackageManager
+from pkgwise.core.models import PackageUpdate
+from pkgwise.utils.commands import CommandError, run_command
+
+_QU_LINE = re.compile(r"^(?P<name>[^\s]+)\s+(?P<current>[^\s]+)\s*=>\s*(?P<new>[^\s]+)$")
+_SI_FIELD = re.compile(r"^(?P<key>[^:]+):(?P<value>.*)$")
+
+_UPDATE_COMMAND = "-Su"
+
+
+class ArchBackend(PackageManager):
+    """pacman-backed implementation for Arch Linux and derivatives."""
+
+    executable = "pacman"
+    name = "pacman"
+
+    @property
+    def supported(self) -> bool:
+        import shutil
+
+        return shutil.which("pacman") is not None
+
+    # -- parsing -----------------------------------------------------------
+
+    def check_updates(self) -> List[PackageUpdate]:
+        """Read available updates from the local sync databases (no refresh)."""
+        lines = self._run_pacman(["-Qu"]).stdout.splitlines()
+        parsed = [_parse_qu_line(line) for line in lines]
+        updates: List[PackageUpdate] = []
+        for row in parsed:
+            if row is None:
+                continue
+            name, current, new = row
+            updates.append(
+                PackageUpdate(
+                    name=name,
+                    current_version=current,
+                    new_version=new,
+                    package_manager=self.name,
+                )
+            )
+        if not updates:
+            return updates
+        self._attach_sizes(updates)
+        return updates
+
+    def list_updates(self) -> List[PackageUpdate]:
+        """Refresh sync databases, then return available updates."""
+        self._sync_databases()
+        return self.check_updates()
+
+    def install_updates(self, names: List[str]) -> None:
+        """Build an update transaction for *names* and run it.
+
+        Authorization (root/sudo) is handled by the caller before this runs;
+        the produced command is deterministic and uses ``--noconfirm`` because
+        PkgWise already collected an explicit confirmation.
+        """
+        if not names:
+            return
+        _run_real_install("pacman", self.install_command(names), names)
+
+    def install_command(self, names: List[str]) -> List[str]:
+        """Return the ``pacman`` invocation used to update *names*.
+
+        An empty selection yields an empty command: with no explicit targets
+        ``pacman -Su`` would upgrade the entire system, which PkgWise must
+        never trigger by accident.
+        """
+        selected = sorted(set(names))
+        if not selected:
+            return []
+        return ["pacman", "--noconfirm", _UPDATE_COMMAND, *selected]
+
+    # -- internal helpers --------------------------------------------------
+
+    def _sync_databases(self) -> None:
+        """Refresh the sync databases (``pacman -Sy``); read-only regarding packages."""
+        run_command(["pacman", "-Sy", "--noconfirm"], timeout=300, check=False)
+
+    def _run_pacman(self, args: List[str]):
+        return run_command(["pacman", *args], timeout=180)
+
+    def _attach_sizes(self, updates: List[PackageUpdate]) -> None:
+        """Populate download/installed sizes using ``pacman -Si`` (offline)."""
+        if not updates:
+            return
+        names = [u.name for u in updates]
+        try:
+            output = self._run_pacman(["-Si", *names]).stdout
+        except CommandError:
+            return
+        sizes = _parse_si_blocks(output)
+        for index, update in enumerate(updates):
+            info = sizes.get(update.name)
+            if info is None:
+                continue
+            updated = replaceable(update, info)
+            if updated is not update:
+                updates[index] = updated
+
+
+def replaceable(update: PackageUpdate, info: Dict[str, Optional[int]]) -> PackageUpdate:
+    """Return an updated copy only when *info* provides reliable values."""
+    from dataclasses import replace
+
+    overrides = {}
+    if info.get("download") is not None:
+        overrides["download_size"] = info["download"]
+    if info.get("installed") is not None:
+        overrides["installed_size"] = info["installed"]
+    if not overrides:
+        return update
+    return replace(update, **overrides)
+
+
+def _parse_qu_line(line: str) -> Optional[tuple]:
+    """Parse one ``pacman -Qu`` output line into (name, current, new)."""
+    stripped = line.strip()
+    if not stripped:
+        return None
+    match = _QU_LINE.match(stripped)
+    if not match:
+        return None
+    return (match.group("name"), match.group("current"), match.group("new"))
+
+
+def _parse_si_blocks(output: str) -> Dict[str, Dict[str, Optional[int]]]:
+    """Parse consolidated ``pacman -Si`` output into ``{name: sizes}``.
+
+    Sizes are converted from strings such as ``8.25 MiB`` to integer bytes.
+    Returns an empty dict when nothing parsable is found.
+    """
+    result: Dict[str, Dict[str, Optional[int]]] = {}
+    current: Dict[str, str] = {}
+    for raw in output.splitlines():
+        line = raw.strip()
+        if not line and current:
+            _commit_si_block(result, current)
+            current = {}
+            continue
+        match = _SI_FIELD.match(line)
+        if not match:
+            continue
+        key = match.group("key").strip().lower()
+        value = match.group("value").strip()
+        if key in {"name", "version", "download size", "installed size"}:
+            current[key] = value
+    if current:
+        _commit_si_block(result, current)
+    return result
+
+
+def _commit_si_block(result: Dict[str, Dict[str, Optional[int]]], block: Dict[str, str]) -> None:
+    name = block.get("name")
+    if not name:
+        return
+    entry = {
+        "download": _parse_size(block.get("download size")),
+        "installed": _parse_size(block.get("installed size")),
+    }
+    result[name] = entry
+
+
+def _parse_size(raw: Optional[str]) -> Optional[int]:
+    """Parse pacman sizes like ``408.88 KiB`` / ``4.02 MiB`` into bytes."""
+    if not raw:
+        return None
+    match = re.match(r"^([0-9.]+)\s*([A-Za-z]+)?$", raw.strip())
+    if not match:
+        return None
+    try:
+        value = float(match.group(1))
+    except ValueError:
+        return None
+    unit = (match.group(2) or "B").lower()
+    multiplier = {
+        "b": 1,
+        "kib": 1024,
+        "mib": 1024**2,
+        "gib": 1024**3,
+        "tib": 1024**4,
+    }.get(unit, 1)
+    return int(value * multiplier)
+
+
+def _run_real_install(manager: str, command: List[str], names: List[str]) -> None:
+    """Execute a real install/update command, converting failures to InstallError.
+
+    Never constructs a shell string — always an argument list.
+    """
+    from pkgwise.utils import commands as cmd_utils
+
+    path = cmd_utils.which(manager)
+    if path is None:
+        raise InstallError(
+            f"The package manager '{manager}' is not installed.",
+            detail="Install it before retrying an update.",
+        )
+    try:
+        cmd_utils.run_command(command, timeout=_INSTALL_TIMEOUT, check=False)
+    except cmd_utils.CommandError as exc:
+        raise InstallError(
+            exc.message, returncode=exc.returncode, detail=exc.detail
+        ) from exc
+
+
+_INSTALL_TIMEOUT = 86_400  # 24h: installs can legitimately take a long time

pkgwise-0.1.0/pkgwise/backends/base.py

@@ -0,0 +1,107 @@
+"""Abstract package-manager interface.
+
+The TUI and analyzer talk only to this interface. Concrete backends
+(:mod:`pkgwise.backends.arch` and :mod:`pkgwise.backends.debian`)
+implement the same contract, so adding Fedora/dnf later means adding one new
+backend class — no changes to the UI or analyzer.
+
+Parsers return raw parsed values (``None`` when unknown); assigning priority
+is exclusively the job of :mod:`pkgwise.core.priority`.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from pkgwise.core.models import PackageUpdate
+
+
+class UpdateCheckError(Exception):
+    """Base error for any backend query failure. Raised with a human message."""
+
+    def __init__(self, message: str, detail: Optional[str] = None):
+        self.message = message
+        self.detail = detail
+        super().__init__(message)
+
+
+class BackendUnavailableError(UpdateCheckError):
+    """The package-manager binary is not installed on this system."""
+
+
+class UnsupportedDistroError(UpdateCheckError):
+    """No backend maps to the detected distribution/package manager."""
+
+
+class PackageManager(ABC):
+    """Common contract every backend implements."""
+
+    #: Binary invoked to perform update operations.
+    executable: str = ""
+
+    #: Human name for the backend, e.g. "pacman".
+    name: str = ""
+
+    @property
+    @abstractmethod
+    def supported(self) -> bool:
+        """True when this backend's package manager is installed."""
+
+    @abstractmethod
+    def check_updates(self) -> List[PackageUpdate]:
+        """Query and return available updates (read-only, no refresh)."""
+
+    @abstractmethod
+    def list_updates(self) -> List[PackageUpdate]:
+        """Update the package index, then return available updates."""
+
+    @abstractmethod
+    def install_updates(self, names: List[str]) -> None:
+        """Perform a real update for the given package names.
+
+        May raise :class:`InstallError` on failure. Intended to be run from
+        middleware that has already checked permissions and disk space.
+        """
+
+    @abstractmethod
+    def install_command(self, names: List[str]) -> List[str]:
+        """Return the argument list that would update *names* (no side effects).
+
+        Exists so callers can display/confirm the exact command first.
+        """
+
+
+class InstallError(Exception):
+    """Raised when an update operation fails."""
+
+    def __init__(self, message: str, returncode: Optional[int] = None, detail: Optional[str] = None):
+        self.message = message
+        self.returncode = returncode
+        self.detail = detail
+        super().__init__(message)
+
+
+def _as_int(raw: Optional[str]) -> Optional[int]:
+    """Parse a size/count string (often with commas or units) to int."""
+    if not raw:
+        return None
+    cleaned = raw.replace(",", "").replace(" ", "").strip()
+    if not cleaned:
+        return None
+    try:
+        return int(cleaned)
+    except (ValueError, TypeError):
+        return None
+
+
+def _yes_no(raw: Optional[str]) -> Optional[bool]:
+    """Parse a y/n style value into a bool, or ``None`` if unparseable."""
+    if raw is None:
+        return None
+    lowered = raw.strip().lower()
+    if lowered in {"y", "yes", "true", "1"}:
+        return True
+    if lowered in {"n", "no", "false", "0"}:
+        return False
+    return None