@gjermundgaraba/upup 0.0.0 → 0.1.0

package/README.md

@@ -18,17 +18,53 @@ upup system          # tools installed on this machine
 upup project [dir]   # dependencies of the project containing dir
 ```
 
-**System** lists tools from Homebrew (formulae and casks), npm, pnpm and Vite+ globals, Vite+ itself, `cargo install`, `go install` and `uv tool`. Only the package managers on your `PATH` are asked.
+**System** lists operating-system updates from macOS Software Update and apt, macOS apps that update themselves, and tools from Homebrew (formulae and casks), npm, pnpm and Vite+ globals, Vite+ itself, `cargo install`, `go install` and `uv tool`. Only the package managers on your `PATH` are asked.
 
 **Project** lists the registry dependencies declared across the workspace that contains the directory: Go modules, Cargo workspaces, and npm or pnpm projects including pnpm catalogs. Path, Git and workspace references are not listed. Yarn and Bun projects are reported as unsupported.
 
+It also lists the GitHub Actions and reusable workflows that the repository's workflows (`.github/workflows`), its own `action.yml` and its composite actions (under `.github/actions`, and any local action a workflow uses) use, once per action and release however many files say it. Their tags are read with `git ls-remote`: first from the server the repository's `origin` is on, when that isn't github.com, since a GitHub Enterprise Server runs its own copy of an action before github.com's; then from github.com, a private repository's with your own git config. An update moves to the newest release tag written like the current one: as precise, and with or without the `v`. So `@v4` moves to `@v5` once the action tags `v5`, and `@v4.1.2` to the newest full release. A commit pin is read as the release tag that points at it (the one its comment names, such as `# v4.1.2`, else the most precise) and moves to the commit of the newest tag like that one, its comment's version moving with it; upup says when a comment names a tag that points elsewhere. Local (`./`) actions are read rather than listed, Docker actions are not listed, and branches such as `@main` are listed without an update. Removing an action is left to you.
+
 Current versions come from the package manager or lockfile. An offered update is the newest stable release. Updating a declared range keeps its style (`^1.2.0` becomes `^1.4.0`), and the lockfile is reconciled and checked afterwards. Removing a project dependency edits the manifest and reconciles the same way.
 
+## OS updates
+
+On macOS, upup lists what `softwareupdate --list` offers, scanning afresh on each refresh. The macOS row always shows the running version and offers the newest update within it; a new major version, Safari, Command Line Tools and firmware updates each get a row of their own while offered. macOS itself installs from System Settings › General › Software Update, which also asks for the owner's approval Apple silicon needs and restarts the Mac: press `o` on a macOS row to open it. upup installs the rest together with one `softwareupdate --install`, and says when one waits for a restart.
+
+On Debian and Ubuntu, upup lists what `apt list --upgradable` offers from apt's lists as they were last refreshed (daily, by apt's own timer); packages held with `apt-mark hold` are listed but not updated. Installing refreshes the lists with `apt-get update`, then installs the newest of each chosen update together in one `apt-get install --only-upgrade` that keeps your changed config files (`--force-confold`; the package's version is left beside yours), so an update may land newer than it was listed. When an update leaves `/var/run/reboot-required` behind, upup says to restart. upup doesn't remove OS packages.
+
+OS updates come from the vendor, so there is nothing for an Audit to read: they are marked as not audited and install as confirmed even with **audit first** on.
+
+Installing needs root. Unless sudo needs no password, upup asks for yours in a popup, once per install run; sudo's own prompt never runs in upup's terminal. The password goes to that run's one `sudo -S` command on standard input and is not kept. A wrong one fails the install, with sudo saying so; press `u` again. With Touch ID set up for sudo (`pam_tid.so` in `/etc/pam.d/sudo_local`), upup leaves the asking to sudo's own Touch ID sheet instead, once per install run; cancelling it fails the install, with sudo saying so. Agents can install only where sudo needs no password for any command (`NOPASSWD: ALL`): a rule for `apt-get` alone doesn't apply, since upup runs it through `sh` and `env`.
+
+## App updates
+
+On macOS, upup also lists the apps in `/Applications` and `~/Applications` (and in plain folders one level down) that update themselves, from the same sources [Mole](https://github.com/tw93/Mole) reads, and the same table of feeds for apps that choose theirs at run time:
+
+- **Sparkle** apps, from the appcast their `Info.plist` names (`SUFeedURL`). upup offers the newest stable update on the default channel that this Mac can run. Sparkle compares builds, so unless the versions people see differ, each shows its build too: `1.0 (879)` → `1.0 (918)`.
+- **Electron** apps built with electron-builder, from the GitHub or generic feed in their `app-update.yml`: the zip for this Mac in the newest stable release.
+- **Mac App Store** apps, at the version their App Store page offers for the Mac. The App Store installs those: press `o` to open the app's page there.
+
+Apps a Homebrew cask installed stay Homebrew's, except those of casks that leave updates to the app (`auto_updates`), which are listed here; `d` on one runs `brew uninstall --cask`. upup doesn't remove other apps: move them to the Trash in Finder.
+
+Like OS updates, app updates are marked as not audited and install as confirmed even with **audit first** on.
+
+Before anything changes, upup checks each update:
+
+- The download matches its feed's EdDSA signature when the app has a Sparkle key (`SUPublicEDKey`), or the feed's sha512 for Electron.
+- The new app is signed through Apple's developer chain as the installed app's bundle ID by its team (`codesign --verify --deep --strict -R`), is built for this Mac, and is the offered version.
+- An installer package, for Sparkle updates that come as one (such as NordVPN's), is the only one in the download and is signed with a Developer ID Installer certificate of the installed app's team.
+
+upup then copies the new app beside the old one and swaps them; if the swap fails, it puts the old one back, or says where it is, and the next listing says so too until the old copy (`<app>.upup-old`) is gone. It never replaces an app while anything runs code from inside it: when the app itself is open, upup asks during the install, one app at a time, whether to quit it, and opens it again afterwards, also when the install failed; a helper or agent still running from inside it fails that update, naming it, its pid and what started it, until you quit or stop it. Nor does it replace an app that changed since upup listed it, such as one that installed its own update as it quit; refresh to see what it offers now. upup won't update the app it runs in, such as your terminal: update that one from another terminal.
+
+Apps upup can't write to, and every installer package, need root. They install together once the others are done, through one sudo command that asks as OS updates do, but separately from them. The password popup comes before any app is quit; a wrong password or a cancelled Touch ID sheet fails those updates and opens again the apps upup quit. As root, upup copies each checked update where only root can write, checks that copy again (the app against its code hashes, a package against its sha256 and Developer ID), and installs only that copy.
+
+macOS may stop upup from quitting an app or replacing one until the app upup runs in is allowed under System Settings › Privacy & Security › Automation or › App Management; upup says which.
+
 ## Audits
 
-An Audit asks a model whether an offered update is safe to take. upup downloads both versions from the package's registry (for npm, also each direct dependency whose declared version changed), verifies their checksums, extracts and diffs them, links each version to the source commit it was built from where it can (Sigstore-verified npm provenance, a matching GitHub release asset, or the commit the package declares, labelled by strength) and diffs that source too, and lets the model read that workspace through read, grep and list tools confined to it. The model has no shell, network or write access. It answers with a verdict (`ok`, `caution`, `danger` or `no-verdict`), a rationale and findings.
+An Audit asks a model whether an offered update is safe to take. upup downloads both versions from the package's registry (for npm, also each direct dependency whose declared version changed), verifies their checksums, extracts and diffs them, links each version to the source commit it was built from where it can (Sigstore-verified npm provenance, a matching GitHub release asset, or the commit the package declares, labelled by strength) and diffs that source too, and lets the model read that workspace through read, grep and list tools confined to it. A GitHub Action has no published package: upup fetches its repository with git at the commits the two tags point at and diffs those, committed bundles included. Tags can move, so an update is listed with the commit its tag points at: the Audit is of that commit and a pin is moved to exactly it, and once the tag points elsewhere upup won't audit it or move a pin to it until you refresh. A workflow that names a tag runs whatever the tag points at later. Changes in a file's mode, such as a script made executable, and the commits a submodule moved between are listed beside the diff; a submodule's own files are not fetched. An action whose repository is private, or which only the repository's own server has, is not audited. The model has no shell, network or write access. It answers with a verdict (`ok`, `caution`, `danger` or `no-verdict`), a rationale and findings.
 
-Choose the model and thinking level in Settings (`,`) from every model [pi-ai](https://github.com/earendil-works/pi) knows. upup shares pi's credentials file, `~/.pi/agent/auth.json` (or `$PI_CODING_AGENT_DIR/auth.json`), so a provider you signed in to with pi works here, and keys or logins added in upup are visible to pi. With **audit first** on, `u` audits the selection and applies only the updates whose audit found `ok`. An update already audited as `caution`, `danger` or `no verdict` is marked in the confirmation instead, and confirming installs it anyway. Agents over MCP can still apply only `ok` updates.
+Choose the model and thinking level in Settings (`,`) from every model [pi-ai](https://github.com/earendil-works/pi) knows. upup shares pi's credentials file, `~/.pi/agent/auth.json` (or `$PI_CODING_AGENT_DIR/auth.json`), so a provider you signed in to with pi works here, and keys or logins added in upup are visible to pi. With **audit first** on, `u` audits the selection and applies only the updates whose audit found `ok`. An update already audited as `caution`, `danger` or `no verdict` is marked in the confirmation instead, and confirming installs it anyway. Agents over MCP can still apply only `ok` updates, apart from OS and app updates.
 
 Audits run four at a time, are stored under your user cache directory (`$XDG_CACHE_HOME/upup` when set, otherwise `~/Library/Caches/upup` on macOS and `~/.cache/upup` elsewhere), and start over if upup quits mid-audit. A Report is reused while the update resolves to the same artifact digests and the model, the thinking level and the prompt are unchanged. It approves the package's own published files; changed dependencies are shown to the model but not pinned, because the package manager resolves them when it installs. Failed, interrupted, stale and replaced runs are kept under `audits/history/` in the same directory, so a bad run can be inspected afterwards. Downloaded and extracted packages and source checkouts are removed once an Audit is done; only the diff and its summaries stay, for 30 days.
 
@@ -40,7 +76,7 @@ Audits run four at a time, are stored under your user cache directory (`$XDG_CAC
 claude mcp add upup -- upup mcp
 ```
 
-Agents can't choose the audit model or add credentials; set those in the TUI. With audit first on, agents can apply only updates whose Audit found `ok`.
+Agents can't choose the audit model or add credentials; set those in the TUI. With audit first on, agents can apply only updates whose Audit found `ok`, except OS and app updates, which can't be audited and install as they do in the TUI. Agents can install OS updates, and app updates that need root, only where sudo needs no password, since only the TUI can ask for one. An app that is open when an agent updates it fails its update instead of being quit.
 
 ## Keys
 
@@ -54,6 +90,7 @@ Agents can't choose the audit model or add credentials; set those in the TUI. Wi
 | `u`                              | Update the selection, or the package under the cursor                    |
 | `d`                              | Remove the selection, or the package under the cursor                    |
 | `r`                              | Audit the selection, or the package under the cursor                     |
+| `o`                              | Open the package's homepage, or where its update installs from           |
 | Tab, Shift+Tab                   | Switch between About, Changes, Report and Transcript                     |
 | Ctrl+D/Ctrl+U                    | Scroll details                                                           |
 | Ctrl+X                           | Stop: targets not yet started are skipped; started edits still reconcile |
@@ -64,7 +101,7 @@ Agents can't choose the audit model or add credentials; set those in the TUI. Wi
 | `q`                              | Quit, after stopping a running update                                    |
 | Ctrl+C                           | Quit immediately                                                         |
 
-Details have four tabs. **About** shows what the package is: its provider, versions and declaration, plus a description, release dates, popularity, deprecations and links from its registry, cached for a day under your user cache directory. **Changes** shows the verified diff between the installed and offered versions without needing a model. **Report** and **Transcript** show the latest Audit's verdict and what the model did.
+Details have four tabs. **About** shows what the package is: its provider, versions and declaration, plus a description, release dates, popularity, deprecations and links from its registry, cached for a day under your user cache directory. **Changes** shows the verified diff between the installed and offered versions without needing a model; for an app update, the release notes from the app's feed. **Report** and **Transcript** show the latest Audit's verdict and what the model did.
 
 When npm's allow-scripts policy blocks an update, upup asks before retrying: it names the blocked install scripts. For a global install, approving adds those packages to your allow list for that one command. For a project, npm accepts no allow list from the command line, so approving turns its strict check off for that one install, and any install script in the project's dependencies may run. If npm's strict check crashes instead (`ENOENT` on a `lib` folder, which happens with `vp add -g` and `strict-allow-scripts=true`), retrying turns the strict check off for that one command, and the popup says so.