@gjermundgaraba/upup 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gjermund Garaba
+
+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.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# upup
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Understand, audit and update system tools and project dependencies from one TUI.
+
+## Install
+
+```sh
+npm install -g @gjermundgaraba/upup
+```
+
+Requires Node 26.4 or newer. The TUI is built on [OpenTUI](https://github.com/anomalyco/opentui), which runs through Node's experimental FFI; the `upup` command enables it for you.
+
+## Usage
+
+```sh
+upup                 # the current project's dependencies, or the system inventory outside a project
+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.
+
+**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.
+
+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.
+
+## 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.
+
+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.
+
+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.
+
+## Agents
+
+`upup mcp` serves the same operations to coding agents over MCP on standard I/O: listing an inventory, describing a package, showing an update's changes, starting and reading Audits, and updating or removing packages. For Claude Code:
+
+```sh
+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`.
+
+## Keys
+
+| Key                              | Action                                                                   |
+| -------------------------------- | ------------------------------------------------------------------------ |
+| `j`/`k`, ↑/↓, PgUp/PgDn, `g`/`G` | Move                                                                     |
+| Space                            | Select the package under the cursor                                      |
+| `*`                              | Select every package shown, or clear them                                |
+| `/`                              | Filter by name (Enter keeps, Esc clears); hidden selections still count  |
+| Enter, Esc                       | Open and close details on narrow terminals                               |
+| `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                     |
+| 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 |
+| `m`                              | Switch between the system inventory and the project                      |
+| `R`                              | Discover and list again, and re-read stored Reports                      |
+| `,`                              | Settings: audit model, thinking level and audit first                    |
+| `?`                              | List the keys                                                            |
+| `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.
+
+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.
+
+Each update run is also logged to `updates/` in the user cache directory, one JSON line per package with its outcome and, for a failure, the command's full output. The 50 newest runs are kept.
+
+## Development
+
+Requires Node 26.4 or newer and [Vite+](https://viteplus.dev).
+
+```sh
+vp install
+vp check
+vp test
+vp pack
+```
+
+`vp run sea` builds a standalone `dist-sea/upup` for this machine (macOS or Linux), with Node and OpenTUI's native library inside, so it runs without Node installed. It extracts those assets to a per-user directory under the system temp directory on first run. `vp run sea:install` builds it and copies it to `~/.local/bin/upup`.
+
+The Go implementation lives in history at `d2a5ed7`.