@dahch/heimdall 1.1.0 → 1.3.0

package/README.md

@@ -19,8 +19,10 @@
   1. **Detection & Bounded Scan**: Available package managers are checked concurrently using an internal worker pool (concurrency limit of 4) to query pending updates without overloading CPU or network.
   2. **Aggregated Review & Confirmation**: Shows an interactive tabular overview comparing current and latest package versions across all managers, prompting for confirmation before modifying the system.
 - 🧪 **True Simulated Dry-Run (`--dry-run`)**: Traverses the full engine lifecycle, formats outdated packages, and executes mock update routines step-by-step with real-time feedback without touching system files.
-- ⚡ **High-Speed Registry Queries**: Yarn and pipx bypass heavy CLI subprocess spawning by querying the npm Registry and PyPI JSON APIs directly over HTTP with strict 3-second abort timeouts.
-- 🔐 **Non-Interactive Sudo Pre-Checks**: Privileged managers (MacPorts, Linux APT, Linux DNF) verify cached credentials using `sudo -n true` beforehand, preventing terminal lockups and password prompt hangs.
+- ⚡ **High-Speed Registry Queries**: Yarn, pipx, uv and Poetry bypass heavy CLI subprocess spawning by querying the npm Registry and PyPI JSON APIs directly over HTTP with strict 3-second abort timeouts.
+- 🔧 **Firmware Updates (Linux)**: Detects pending firmware through `fwupd` (`fwupdmgr refresh` + `fwupdmgr --json get-updates`) and applies it with `sudo fwupdmgr update`, never rebooting the machine on its own.
+- 🚀 **Distribution Release Upgrades**: At the end of every run, checks whether a newer OS release exists (Fedora n+1 via Bodhi, Ubuntu via `do-release-upgrade -c`, Debian via the stable suite) and offers to stage it — reporting the exact command instead of applying it silently, and never rebooting for you.
+- 🔐 **Interactive Sudo Acquisition**: When a selected manager requires elevation (`requiresSudo`), `hmd` verifies the cached ticket with `sudo -n true` and, if missing, prompts for the password exactly once through `sudo -v` on the controlling terminal before any spinner takes over the TTY. A background keep-alive refreshes the ticket during long upgrades, and every privileged step re-verifies non-interactive credentials so subprocesses can never hang on a hidden password prompt. Running `sudo hmd` is neither required nor supported (the CLI lives under the user's `PATH`, which root's `secure_path` does not include).
 - 🎨 **Modern Minimalist UX**: Terminal interface powered by `@clack/prompts`, micro-border tabular layouts with directional version transitions (`current → latest`), persistent real-time step progression with elapsed durations, and actionable error extraction.
 - 🏷 **Dynamic Version Resolution**: Reads package name and version dynamically from `package.json` at runtime via `import.meta.url`, ensuring banners and `--version` flags remain in sync with repository releases.
 - ⚙ **Flexible Targeting**: Run interactively, execute non-interactively with `--yes`, or filter target managers using `--only` and `--exclude`.
@@ -29,7 +31,7 @@
 
 ## 📦 Supported Package Managers
 
-Heimdall (`hmd`) supports 14 package managers across system, runtime, language, and application store categories:
+Heimdall (`hmd`) supports 18 package managers across system, runtime, language, and application store categories:
 
 | Manager | Icon | Category | Detection Strategy | Update Routine & Resilience Rules |
 | :--- | :---: | :---: | :--- | :--- |
@@ -40,13 +42,46 @@ Heimdall (`hmd`) supports 14 package managers across system, runtime, language,
 | **[Yarn (global)](https://yarnpkg.com)** | 🧶 | `runtime` | `yarn global list --depth=0` + native npm registry HTTP checks | 1. `yarn global add <pkg>@latest` (bypasses global semver lockouts)<br>2. `yarn global upgrade` |
 | **[Python (pip user)](https://pip.pypa.io)** | 🐍 | `language` | `pip3 list --user --outdated --format=json` (targets user site-packages) | `pip3 install --user --upgrade <pkgs>` (complies with PEP 668 externally managed environment protections) |
 | **[pipx](https://pipx.pypa.io)** | 📦 | `language` | `pipx list --json` + native PyPI JSON API lookups | `pipx upgrade-all` |
+| **[uv](https://astral.sh/uv)** | 🧪 | `language` | `uv tool list` + native PyPI JSON API lookups | 1. `uv tool upgrade --all`<br>2. `uv tool install <pkg>@latest` for tools pinned to an older major (uv respects install-time constraints) |
+| **[Poetry](https://python-poetry.org)** | 📜 | `language` | `poetry --version` + native PyPI JSON API lookups | `poetry self update` |
+| **[Conda](https://conda.io)** | 🅒 | `language` | `conda update --all --dry-run --json` (solver `LINK`/`UNLINK` actions paired by package name, 60s solver budget) | `conda update --all -y` |
 | **[Rust (Cargo & Rustup)](https://doc.rust-lang.org/cargo/)** | 🦀 | `language` | `rustup check` (toolchains) + `cargo install-update -l` (crates) | 1. `rustup update` (if `rustup` exists)<br>2. `cargo install-update -a` (if `cargo-update` is installed) |
 | **[Ruby Gem](https://rubygems.org)** | 💎 | `language` | `gem outdated` (skips deprecated Apple System Ruby `/usr/bin/gem`) | 1. `gem update --user-install`<br>2. `gem cleanup` |
 | **[MacPorts](https://www.macports.org)** | ⚓ | `system` | `port outdated` + non-interactive `sudo -n true` verification | 1. `sudo port selfupdate`<br>2. `sudo port upgrade outdated` |
 | **[Mac App Store (mas)](https://github.com/mas-cli/mas)** | 🍎 | `appstore` | `mas outdated` | `mas upgrade` |
-| **[APT (Debian/Ubuntu)](https://wiki.debian.org/Apt)** | 🐧 | `system` | `apt list --upgradable` + non-interactive `sudo -n true` check | 1. `sudo apt-get update -y`<br>2. `sudo apt-get upgrade -y`<br>3. `sudo apt-get autoremove -y` |
+| **[APT (Debian/Ubuntu)](https://wiki.debian.org/Apt)** | 🐧 | `system` | `apt list --upgradable` + non-interactive `sudo -n true` check | 1. `sudo apt-get update -y`<br>2. `sudo apt-get upgrade -y --with-new-pkgs` (avoids leaving dependency-gaining upgrades `kept back`)<br>3. `sudo apt-get autoremove -y` (prompted interactively with confirmation prompt, auto-approved with `--yes` or `--dry-run`, skipped when declined or after a failed upgrade) |
 | **[DNF (Fedora/RHEL)](https://docs.fedoraproject.org/en-US/quick-docs/dnf/)** | 📦 | `system` | `dnf check-update -y` (exit code 100 signals updates) + `sudo -n true` check | 1. `sudo dnf upgrade -y --refresh`<br>2. `sudo dnf autoremove -y` (prompted interactively with confirmation prompt, auto-approved with `--yes` or `--dry-run`) |
-| **[Flatpak](https://flatpak.org)** | 📦 | `system` | `flatpak remote-ls --updates` | `flatpak update -y --noninteractive` |
+| **[Flatpak](https://flatpak.org)** | 📦 | `system` | `flatpak remote-ls --user --updates` + `flatpak remote-ls --system --updates` (both scopes, deduplicated) | 1. `flatpak update --user -y --noninteractive`<br>2. `sudo flatpak update --system -y --noninteractive` (marked `failed` with sudo guidance when system apps exist but privileges are unavailable, `skipped` when no system-scope apps are installed) |
+| **[Firmware (fwupd)](https://fwupd.org)** | 🔧 | `system` | Linux only: `fwupdmgr refresh` (best-effort) + `fwupdmgr --json get-updates` + `sudo -n true` check | 1. `sudo fwupdmgr refresh --force`<br>2. `sudo fwupdmgr update -y --no-reboot-check --no-unreported-check --no-metadata-check` (installs every pending device update; never reboots by itself, so the machine reboots only when you decide to) |
+
+---
+
+## 🚀 Distribution Release Upgrades
+
+Package updates are not the only maintenance task: the operating system itself gets a new release. After the package summary (and also when everything was already up to date), `hmd` checks whether a newer distribution release exists, reports it, and asks before touching anything.
+
+| Family | Detection | Upgrade Routine |
+| :--- | :--- | :--- |
+| **Fedora** | Bodhi `releases?state=current` (GA releases only; EPEL/ELN ignored) | `sudo dnf system-upgrade download --releasever=<next> -y` — stages the offline transaction |
+| **Ubuntu** | Authoritative `do-release-upgrade -c`; fallback to `changelogs.ubuntu.com/meta-release` | `sudo do-release-upgrade -f DistUpgradeViewNonInteractive` (when the upgrader is installed) |
+| **Debian** | `deb.debian.org/debian/dists/stable/Release` vs. `VERSION_ID` | *Report only*: no unattended in-place path; guidance to switch suites then `sudo apt update && sudo apt full-upgrade` |
+
+Safety rules:
+
+- **Never reboots**: Fedora stages the packages and tells you to run `sudo dnf system-upgrade reboot`; Ubuntu reports its own restart requirement. You decide when to reboot.
+- **`--yes` does not auto-apply it**: distribution upgrades are heavier than package updates, so an unattended run only reports the availability and the exact command. Use `-U`/`--upgrade-distro` to opt in explicitly.
+- **`--dry-run`** prints the exact command that would run; **`--no-distro-upgrade`** disables the check entirely.
+- Sudo is acquired once, just before applying, with a keep-alive for the (potentially hour-long) upgrade.
+
+Example output:
+
+```text
+◇  Distribution upgrade available ─────────────────────────────╮
+│  Fedora Linux 45 is available (current: 44).                 │
+│  Heimdall can stage/apply the upgrade; it never reboots.     │
+├──────────────────────────────────────────────────────────────╯
+◇  ↳ Reboot to apply it: sudo dnf system-upgrade reboot
+```
 
 ---
 
@@ -107,6 +142,8 @@ heimdall [options]
 | `-x` | `--exclude <mgrs>` | Comma-separated list of managers to exclude (e.g. `gem,macports`) | *None* |
 | `-t` | `--timeout <ms>` | Network/subprocess timeout per check phase in milliseconds | `25000` |
 | `-v` | `--verbose` | Output detailed diagnostic messages and skipped manager listings | `false` |
+| — | `--no-distro-upgrade` | Skip the distribution release upgrade check at the end of the run | `false` |
+| `-U` | `--upgrade-distro` | Apply a detected distribution release upgrade without asking (never reboots) | `false` |
 | `-h` | `--help` | Display command help and option summary | — |
 | `-V` | `--version` | Output CLI version (dynamically resolved from `package.json`) | Dynamic |
 
@@ -135,6 +172,12 @@ hmd --timeout 40000 --verbose
 
 # 7. Using the Canonical Alias
 heimdall --dry-run
+
+# 8. Stage a distribution release upgrade without asking (never reboots)
+hmd --upgrade-distro
+
+# 9. Skip the distribution release upgrade check
+hmd --no-distro-upgrade
 ```
 
 ---
@@ -157,8 +200,13 @@ Test coverage includes:
 - Concurrency pool bounds and error isolation in [`UpdaterEngine`](src/core/engine.ts).
 - `NpmManager` targeted batch installation, fallback trigger handling, and `--ignore-scripts` resilience.
 - `HomebrewManager` selective formula vs. cask execution branches.
-- Pre-check behaviors (skipping `/usr/bin/gem`, sudo privilege checks for MacPorts and APT).
-- HTTP registry lookup error handling for Yarn and pipx.
+- Pre-check behaviors (skipping `/usr/bin/gem`, sudo privilege checks for MacPorts, APT and DNF, interactive sudo acquisition with ticket keep-alive).
+- `FlatpakManager` dual-scope querying (user + system installations) and system-step sudo gating.
+- `AptManager` upgradable parsing (epochs, architecture-qualified names, header/warning lines) and its consent-gated autoremove branch.
+- `UvManager` tool-list parsing, cross-major reinstalls and PyPI lookups; `PoetryManager` version banner parsing; `CondaManager` dry-run `LINK`/`UNLINK` pairing.
+- `FirmwareManager` fwupd JSON parsing (including the legacy non-zero "no updates" exit code), sudo fast-fail and reboot-safe update flags.
+- `detectDistroUpgrade()`/`applyDistroUpgrade()`: os-release parsing, Fedora Bodhi, Ubuntu `do-release-upgrade -c` + meta-release fallback, Debian stable-suite detection, sudo fast-fail and no-reboot guarantees.
+- HTTP registry lookup error handling for Yarn, pipx, uv and Poetry.
 - Formatting renderers (micro-border table, directional version diffs, execution summary metrics).
 
 ---