freshenup 3.0.0__tar.gz

freshenup-3.0.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.2
+        with:
+          enable-cache: true
+      - run: uv sync
+      - run: uv run ruff format --check src tests
+      - run: uv run ruff check src tests
+      - run: uv run pyright src tests
+      - run: uv run pytest -q

freshenup-3.0.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish
+
+# Cut a GitHub Release to publish that version to PyPI. Release from a green main —
+# this workflow builds and publishes, it does not re-run the CI gate.
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # mint the short-lived OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.2
+      - run: uv build
+      - run: uv publish --trusted-publishing always

freshenup-3.0.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+dist/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/

freshenup-3.0.0/LICENSE

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

freshenup-3.0.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: freshenup
+Version: 3.0.0
+Summary: Pick outdated Homebrew and Mac App Store items to upgrade or uninstall
+Project-URL: Homepage, https://github.com/akirayamamoto/freshenup
+Project-URL: Repository, https://github.com/akirayamamoto/freshenup
+Project-URL: Issues, https://github.com/akirayamamoto/freshenup/issues
+Author: Akira Yamamoto
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,homebrew,macos,mas,updates
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.14
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# freshenup
+
+Pick outdated Homebrew formulae and casks — and, optionally, outdated Mac App Store apps — from an `fzf` menu, then upgrade or uninstall them.
+
+A formula node is a top-level (leaf) formula that is outdated itself or has outdated dependencies beneath it; a cask or App Store app is a standalone node. Everything starts selected. Keys are shown in the `fzf` header. App Store rows show a slugified name; the numeric id drives the action via `mas` (which needs root, so a `sudo` prompt appears only when an App Store row is selected).
+
+## Install
+
+```bash
+brew install akirayamamoto/tap/freshenup
+```
+
+## Usage
+
+```bash
+freshenup          # scan and pick
+freshenup -u       # force `brew update` first (brew otherwise auto-refreshes at most once/24h)
+```
+
+- **enter** — upgrade the selected nodes
+- **ctrl-x** — uninstall the highlighted node (confirmed)
+- **tab** — toggle selection
+- **ctrl-t** — invert selection
+
+## Dependencies
+
+- [`fzf`](https://github.com/junegunn/fzf) — the interactive picker (installed automatically via Homebrew)
+- Python 3.14+ and [`pydantic`](https://docs.pydantic.dev) (bundled by the Homebrew install)
+- Homebrew
+- Optional: [`mas`](https://github.com/mas-cli/mas) for Mac App Store support (detected at runtime)
+
+## Development
+
+Managed with [`uv`](https://docs.astral.sh/uv/); lint/format with Ruff, type-checked with pyright (strict).
+
+```bash
+uv sync              # create the venv and install deps
+uv run pytest        # run tests
+uv run ruff check    # lint
+uv run ruff format   # format
+uv run pyright       # type-check (strict)
+```
+
+## License
+
+MIT

freshenup-3.0.0/README.md

@@ -0,0 +1,46 @@
+# freshenup
+
+Pick outdated Homebrew formulae and casks — and, optionally, outdated Mac App Store apps — from an `fzf` menu, then upgrade or uninstall them.
+
+A formula node is a top-level (leaf) formula that is outdated itself or has outdated dependencies beneath it; a cask or App Store app is a standalone node. Everything starts selected. Keys are shown in the `fzf` header. App Store rows show a slugified name; the numeric id drives the action via `mas` (which needs root, so a `sudo` prompt appears only when an App Store row is selected).
+
+## Install
+
+```bash
+brew install akirayamamoto/tap/freshenup
+```
+
+## Usage
+
+```bash
+freshenup          # scan and pick
+freshenup -u       # force `brew update` first (brew otherwise auto-refreshes at most once/24h)
+```
+
+- **enter** — upgrade the selected nodes
+- **ctrl-x** — uninstall the highlighted node (confirmed)
+- **tab** — toggle selection
+- **ctrl-t** — invert selection
+
+## Dependencies
+
+- [`fzf`](https://github.com/junegunn/fzf) — the interactive picker (installed automatically via Homebrew)
+- Python 3.14+ and [`pydantic`](https://docs.pydantic.dev) (bundled by the Homebrew install)
+- Homebrew
+- Optional: [`mas`](https://github.com/mas-cli/mas) for Mac App Store support (detected at runtime)
+
+## Development
+
+Managed with [`uv`](https://docs.astral.sh/uv/); lint/format with Ruff, type-checked with pyright (strict).
+
+```bash
+uv sync              # create the venv and install deps
+uv run pytest        # run tests
+uv run ruff check    # lint
+uv run ruff format   # format
+uv run pyright       # type-check (strict)
+```
+
+## License
+
+MIT

freshenup-3.0.0/RELEASING.md

@@ -0,0 +1,6 @@
+# Releasing
+
+1. Commit to `main`.
+2. Tag and push: `git tag vX.Y.Z && git push --tags` (semver — your call on the bump).
+
+The [Homebrew tap](https://github.com/akirayamamoto/homebrew-tap) auto-bumps its formula within a week. To publish immediately, run the **bump** workflow: Actions → bump → Run workflow.

freshenup-3.0.0/freshenup

@@ -0,0 +1,221 @@
+#!/usr/bin/env bash
+# freshenup — pick outdated Homebrew nodes (formulae + casks) and, optionally, outdated Mac
+# App Store apps, then act on them. A formula node is a leaf that is outdated itself or has
+# outdated deps beneath it; a cask or App Store app is a standalone node. Everything starts
+# selected. Keys are shown in the fzf header (single source of truth). Updating names the
+# outdated deps directly — `brew upgrade mpv` is a no-op when mpv is current, so it wouldn't
+# pull an outdated dep along. App Store rows show a slugified name; the numeric id drives the
+# action (upgrade/uninstall via `mas`, which needs root — a sudo prompt appears only then).
+# Flag: -u/--update force `brew update` now (brew otherwise auto-refreshes at most once/24h).
+# Deps: fzf, brew, coreutils(comm), awk. Optional: mas (Mac App Store). No config, no state.
+set -euo pipefail
+
+# Preview mode (re-invoked by fzf per row): the node's outdated members + version bumps.
+# Payload columns: type <TAB> node <TAB> member <TAB> "current → latest".
+if [ "${1:-}" = "--preview" ]; then
+  awk -F'\t' -v n="${2:-}" '
+    $2 == n { typ = $1
+      if ($3 == n || $1 == "mas") self = $4; else deps = deps sprintf("  %-22s %s\n", $3, $4) }
+    END {
+      lab["cask"] = "  (cask)"; lab["mas"] = "  (App Store)"; lab["formula"] = "  (formula)"
+      print (self == "") ? n lab[typ] : n "  " self lab[typ]; printf "%s", deps }' \
+    "${BREWTOP_PAYLOAD:-/dev/null}"
+  exit 0
+fi
+
+SELF="$(command -v -- "$0" 2>/dev/null || true)"; [ -x "$SELF" ] || SELF="$0"
+
+# No NO_AUTO_UPDATE override: brew's built-in throttle auto-refreshes at most once every
+# ~24h before outdated/upgrade, so within a day this uses the cache and stays fast.
+if [ "${1:-}" = "-u" ] || [ "${1:-}" = "--update" ]; then
+  echo "Refreshing Homebrew…" >&2; brew update >/dev/null
+fi
+
+of="$(mktemp)"; oc="$(mktemp)"; lf="$(mktemp)"; vmap="$(mktemp)"; payload="$(mktemp)"; om="$(mktemp)"
+trap 'rm -f "$of" "$oc" "$lf" "$vmap" "$payload" "$om"' EXIT
+has_mas=""; command -v mas >/dev/null 2>&1 && has_mas=1
+msg="Scanning for outdated formulae and casks"
+[ -n "$has_mas" ] && msg="Scanning for outdated formulae, casks, and App Store apps"
+echo "${msg}…" >&2
+# brew's per-call startup is ~2.5s, so run the independent lookups concurrently.
+brew outdated --formula --verbose >"$of" 2>/dev/null &
+brew outdated --cask --verbose >"$oc" 2>/dev/null &
+brew leaves --installed-on-request | sort >"$lf" 2>/dev/null &
+[ -n "$has_mas" ] && mas outdated --json >"$om" 2>/dev/null &
+wait
+
+# Version map "name<TAB>current → latest" from "name (…, current) < latest" (formulae)
+# and "name (version) != version" (casks). A cask version's comma-suffix is part of the
+# version — keep it (e.g. dotnet 8.0.422,8.0.28) and only strip a trailing build hash.
+# ponytail: "16+ hex chars" is the hash heuristic; tighten to require an a–f digit if a real
+# version ever gets truncated.
+awk '{
+  i = index($0, " ("); if (i == 0) next
+  name = substr($0, 1, i-1); rest = substr($0, i+2)
+  j = index(rest, ")"); inside = substr(rest, 1, j-1); after = substr(rest, j+1)
+  sub(/^ *(<|!=) */, "", after)
+  m = split(inside, a, ", "); cur = a[m]
+  sub(/,[0-9a-fA-F]{16,}$/, "", cur); sub(/,[0-9a-fA-F]{16,}$/, "", after)
+  printf "%s\t%s → %s\n", name, cur, after
+}' "$of" "$oc" > "$vmap"
+
+names_in() { awk '{ i=index($0," ("); if (i>0) print substr($0,1,i-1) }' "$1"; }
+outdated="$(names_in "$of")"        # outdated formula names
+casks="$(names_in "$oc")"           # outdated cask names
+leaves="$(cat "$lf")"; export leaves
+
+# Map each outdated formula to its top node:
+#   - outdated leaf         → the node itself (set intersection)
+#   - outdated non-leaf dep → its leaf ancestors (brew uses, one per dep, in parallel)
+build() {
+  comm -12 <(echo "$leaves") <(echo "$outdated" | sort) | while read -r l; do
+    [ -n "$l" ] && printf '%s\t●\t\n' "$l"
+  done
+  comm -13 <(echo "$leaves") <(echo "$outdated" | sort) | xargs -P8 -I{} bash -c '
+    d="$1"; [ -z "$d" ] && exit 0
+    comm -12 <(brew uses --installed --recursive "$d" | sort) <(echo "$leaves") \
+      | while read -r a; do [ -n "$a" ] && printf "%s\t\t%s\n" "$a" "$d"; done
+  ' _ {} || true
+}
+
+# One row per formula node: node <TAB> ●-or-empty <TAB> "dep1 dep2 ".
+pending="$(build | awk -F'\t' '
+  { seen[$1]=1; if ($2=="●") self[$1]=1; if ($3!="") deps[$1]=deps[$1] $3 " " }
+  END { for (n in seen) printf "%s\t%s\t%s\n", n, (n in self ? "●" : ""), deps[n] }
+')"
+
+# Payload: type <TAB> node <TAB> member <TAB> "current → latest".
+# Formula nodes expand to their outdated members; casks collapse under a depends_on parent.
+awk -F'\t' '
+  NR==FNR { ver[$1]=$2; next }
+  { if ($2=="●") print "formula\t" $1 "\t" $1 "\t" ver[$1]
+    c=split($3,a," "); for (i=1;i<=c;i++) if (a[i]!="") print "formula\t" $1 "\t" a[i] "\t" ver[a[i]] }
+' "$vmap" <(printf '%s\n' "$pending") > "$payload"
+# Fold an outdated cask under an outdated cask that depends on it (e.g. dotnet-sdk8 →
+# dotnet-sdk8-0-400) so a wrapper and its version band show as one node, like formula deps
+# under their leaf. Deps come from each cask's install receipt (runtime_dependencies) — a
+# ~1KB local read, no brew calls. ponytail: one dep level, covers the wrapper pattern.
+caskroom="${HOMEBREW_PREFIX:-$(dirname "$(dirname "$(command -v brew)")")}/Caskroom"
+cver() { awk -F'\t' -v n="$1" '$1==n{print $2}' "$vmap"; }
+cask_apps() {  # installed .app bundle name(s) for a cask, from its receipt's uninstall_artifacts
+  awk -F'"' '
+    $0 ~ /"app"[[:space:]]*:/ { inapp=1; next }
+    inapp && /\]/ { inapp=0; next }
+    inapp && NF>=2 { print $2 }' "$caskroom/$1/.metadata/INSTALL_RECEIPT.json" 2>/dev/null
+}
+cdeps="$(while read -r c; do
+  [ -z "$c" ] && continue
+  awk -F'"' '/"full_name":/ { d = $4; sub(/.*\//, "", d); print c "\t" d }' \
+    c="$c" "$caskroom/$c/.metadata/INSTALL_RECEIPT.json" 2>/dev/null
+done <<<"$casks")"                                          # parent<TAB>dep
+folded="$(printf '%s\n' "$cdeps" | awk -F'\t' 'NF==2{print $2}' | sort -u \
+         | comm -12 - <(printf '%s\n' "$casks" | sort -u))" # outdated casks shown under a parent
+while read -r c; do
+  [ -z "$c" ] && continue
+  printf '%s\n' "$folded" | grep -qxF "$c" && continue      # this cask folds under a parent
+  printf 'cask\t%s\t%s\t%s\n' "$c" "$c" "$(cver "$c")"      # top-level node (self row)
+  printf '%s\n' "$cdeps" | awk -F'\t' -v c="$c" '$1==c{print $2}' | while read -r d; do
+    printf '%s\n' "$folded" | grep -qxF "$d" && printf 'cask\t%s\t%s\t%s\n' "$c" "$d" "$(cver "$d")"
+  done
+done <<<"$casks" >> "$payload"
+
+# Each outdated Mac App Store app is a standalone self node: display a slugified name + the
+# last 3 id digits (keeps rows visually brew-like and near-unique); the numeric id in the
+# member slot is what `mas` acts on. JSON fields are order-independent, so match each.
+if [ -s "$om" ]; then
+  awk '
+    { id=""; name=""; cur=""; new=""
+      if (match($0, /"adamID":[0-9]+/))       id   = substr($0, RSTART+9,  RLENGTH-9)
+      if (match($0, /"name":"[^"]*"/))        name = substr($0, RSTART+8,  RLENGTH-9)
+      if (match($0, /"version":"[^"]*"/))     cur  = substr($0, RSTART+11, RLENGTH-12)
+      if (match($0, /"newVersion":"[^"]*"/))  new  = substr($0, RSTART+14, RLENGTH-15)
+      if (id == "" || name == "") next
+      s = tolower(name); gsub(/[^a-z0-9]+/, "-", s); gsub(/^-+|-+$/, "", s)
+      printf "mas\t%s-%s\t%s\t%s\n", s, substr(id, length(id)-2), id, (cur == "" ? new : cur " → " new)
+    }' "$om" >> "$payload"
+fi
+
+[ ! -s "$payload" ] && { echo "Nothing outdated."; exit 0; }
+export BREWTOP_PAYLOAD="$payload"
+
+# ctrl-x prints a marker then the highlighted line only (deselect-all makes accept emit the
+# current item, not the selection — verified in fzf src output()/{} handling). No --expect.
+sel="$(cut -f2 "$payload" | sort -u | fzf -m \
+  --bind 'load:select-all' \
+  --bind 'ctrl-t:toggle-all' \
+  --bind 'ctrl-x:print(%%UNINSTALL%%)+deselect-all+accept' \
+  --header=$'enter=update  ctrl-x=uninstall highlighted  tab=toggle  ctrl-t=invert' \
+  --preview="$SELF --preview {1}" --preview-window=right,55%)" || exit 0
+
+[ -z "$sel" ] && exit 0
+
+if [ "$(head -1 <<<"$sel")" = "%%UNINSTALL%%" ]; then
+  # Uninstall the single highlighted node (line 2), confirmed; runs here so output persists.
+  n="$(sed -n 2p <<<"$sel")"
+  [ -z "$n" ] && exit 0
+  t="$(awk -F'\t' -v n="$n" '$2==n{print $1; exit}' "$payload")"
+  printf 'Uninstall %s (%s)? [y/N] ' "$n" "$t" > /dev/tty
+  read -r ans < /dev/tty || ans=""
+  case "$ans" in
+    y|Y) case "$t" in
+           cask) brew uninstall --cask "$n" || true ;;
+           mas)  mid="$(awk -F'\t' -v n="$n" '$1=="mas" && $2==n {print $3; exit}' "$payload")"
+                 { [ -n "$mid" ] && sudo mas uninstall "$mid"; } || true ;;
+           *)    { brew uninstall --formula "$n" && brew autoremove; } || true ;;
+         esac ;;
+    *) echo "  skipped $n" > /dev/tty ;;
+  esac
+else
+  # Update: gather selected nodes' outdated members, split by type, upgrade in one call each.
+  nodes="$sel"
+  fpkgs=""; cpkgs=""; mpkgs=""
+  while read -r n; do
+    [ -z "$n" ] && continue
+    while IFS=$'\t' read -r t m; do
+      [ -z "$m" ] && continue
+      case "$t" in
+        cask) cpkgs="$cpkgs$m"$'\n' ;;
+        mas)  mpkgs="$mpkgs$m"$'\n' ;;
+        *)    fpkgs="$fpkgs$m"$'\n' ;;
+      esac
+    done < <(awk -F'\t' -v n="$n" '$2==n { print $1 "\t" $3 }' "$payload")
+  done <<<"$nodes"
+  fpkgs="$(printf '%s' "$fpkgs" | sed '/^$/d' | sort -u)"
+  cpkgs="$(printf '%s' "$cpkgs" | sed '/^$/d' | sort -u)"
+  mpkgs="$(printf '%s' "$mpkgs" | sed '/^$/d' | sort -u)"
+  # shellcheck disable=SC2086
+  [ -n "$fpkgs" ] && brew upgrade --formula $fpkgs
+  # A cask whose installed .app is owned by another user (typically root, after a vendor
+  # self-updater reinstalled it) can't be upgraded by brew without sudo — brew would `sudo cp`
+  # the bundle, which fails non-interactively (e.g. under topgrade) and which freshenup never
+  # does. Detect those up front (ownership, not `-w`: App Management protection makes `-w`
+  # report false even for your own apps) and per cask offer to chown it back to you or skip it.
+  if [ -n "$cpkgs" ]; then
+    me="$(id -un)"; ok=""
+    while read -r c; do
+      [ -z "$c" ] && continue
+      root_app=""
+      while read -r app; do
+        p="/Applications/$app"; [ -e "$p" ] || continue
+        # ponytail: owner-based (updaters root the whole bundle); group-writable edge unhandled.
+        [ "$(stat -f '%Su' "$p")" != "$me" ] && root_app="$p"
+      done < <(cask_apps "$c")
+      if [ -z "$root_app" ]; then ok="$ok$c"$'\n'; continue; fi
+      o="$(stat -f '%Su' "$root_app")"
+      printf '%s is owned by %s — brew needs sudo to upgrade it. chown to you first? [y/N] ' \
+        "$c" "$o" > /dev/tty
+      read -r ans < /dev/tty || ans=""
+      case "$ans" in
+        y|Y) sudo chown -R "$me:admin" "$root_app" && ok="$ok$c"$'\n' \
+               || echo "  chown failed; skipped $c" > /dev/tty ;;
+        *)   echo "  skipped $c (owned by $o)" > /dev/tty ;;
+      esac
+    done <<<"$cpkgs"
+    cpkgs="$(printf '%s' "$ok" | sed '/^$/d' | sort -u)"
+  fi
+  # shellcheck disable=SC2086
+  [ -n "$cpkgs" ] && brew upgrade --cask $cpkgs
+  # shellcheck disable=SC2086
+  [ -n "$mpkgs" ] && sudo mas upgrade $mpkgs
+  true
+fi

freshenup-3.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "freshenup"
+version = "3.0.0"
+description = "Pick outdated Homebrew and Mac App Store items to upgrade or uninstall"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Akira Yamamoto" }]
+keywords = ["homebrew", "mas", "cli", "macos", "updates"]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: System :: Software Distribution",
+]
+dependencies = ["pydantic>=2"]
+
+[project.scripts]
+freshenup = "freshenup.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/akirayamamoto/freshenup"
+Repository = "https://github.com/akirayamamoto/freshenup"
+Issues = "https://github.com/akirayamamoto/freshenup/issues"
+
+[dependency-groups]
+dev = ["ruff>=0.10", "pyright>=1.1", "pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/freshenup"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.14"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

freshenup-3.0.0/src/freshenup/__init__.py

@@ -0,0 +1,3 @@
+"""freshenup — pick outdated Homebrew and Mac App Store items to upgrade or uninstall."""
+
+__version__ = "3.0.0"

freshenup-3.0.0/src/freshenup/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

freshenup-3.0.0/src/freshenup/cli.py

@@ -0,0 +1,131 @@
+"""Command-line entry: parse flags, then orchestrate scan → pick → act."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import sys
+
+from . import system
+from .models import Item, Kind, Node
+from .nodes import build_formula_nodes, collapse_casks
+from .pick import pick, preview
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv)
+    if args.preview is not None:
+        print(preview(args.preview))
+        return 0
+    nodes = _gather(refresh=args.update)
+    if not nodes:
+        print("Nothing outdated.")
+        return 0
+    selection = pick(nodes)
+    if selection is None:
+        return 0
+    if selection.uninstall is not None:
+        _uninstall(selection.uninstall)
+    else:
+        _update(selection.nodes)
+    return 0
+
+
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="freshenup",
+        description="Pick outdated Homebrew and Mac App Store items to upgrade or uninstall.",
+    )
+    parser.add_argument("-u", "--update", action="store_true", help="run `brew update` first")
+    parser.add_argument("--preview", metavar="NODE", help=argparse.SUPPRESS)
+    return parser.parse_args(argv)
+
+
+def _gather(*, refresh: bool) -> list[Node]:
+    has_mas = shutil.which("mas") is not None
+    kinds = "formulae, casks, and App Store apps" if has_mas else "formulae and casks"
+    print(f"Scanning for outdated {kinds}…", file=sys.stderr)
+    scanned = system.scan(refresh=refresh, has_mas=has_mas)
+    return [
+        *build_formula_nodes(scanned.formulae, scanned.leaves, system.uses),
+        *collapse_casks(scanned.casks, system.deps_of),
+        *_mas_nodes(scanned.mas),
+    ]
+
+
+def _mas_nodes(apps: list[Item]) -> list[Node]:
+    # Display a slugified name + the last 3 id digits (near-unique, brew-like); the numeric id in
+    # itself.mas_id drives the action.
+    return [
+        Node(kind=Kind.MAS, name=f"{_slug(app.name)}-{app.mas_id[-3:]}", itself=app) for app in apps
+    ]
+
+
+def _slug(name: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+
+
+def _items(node: Node) -> list[Item]:
+    items = list(node.members)
+    if node.itself is not None:
+        items.append(node.itself)
+    return items
+
+
+def _update(nodes: list[Node]) -> None:
+    formulae: list[str] = []
+    casks: list[str] = []
+    mas_ids: list[str] = []
+    for node in nodes:
+        for item in _items(node):
+            if item.kind is Kind.CASK:
+                casks.append(item.name)
+            elif item.kind is Kind.MAS:
+                mas_ids.append(item.mas_id)
+            else:
+                formulae.append(item.name)
+    system.upgrade(Kind.FORMULA, _unique(formulae))
+    _upgrade_casks(_unique(casks))
+    system.upgrade(Kind.MAS, _unique(mas_ids))
+
+
+def _upgrade_casks(tokens: list[str]) -> None:
+    """Upgrade casks, but first handle any whose .app is owned by another user (brew would need
+    sudo and fail): offer to chown it back, else skip that cask."""
+    if not tokens:
+        return
+    me = system.current_user()
+    blocked = dict(system.blocked_casks(tokens, system.apps_of, system.owner_of, me))
+    approved = [token for token in tokens if token not in blocked]
+    for token, owner in blocked.items():
+        prompt = (
+            f"{token} is owned by {owner} — brew needs sudo to upgrade it. "
+            "chown to you first? [y/N] "
+        )
+        if not _confirm(prompt):
+            print(f"  skipped {token} (owned by {owner})", file=sys.stderr)
+        elif system.chown_cask(token, me):
+            approved.append(token)
+        else:
+            print(f"  chown failed; skipped {token}", file=sys.stderr)
+    system.upgrade(Kind.CASK, sorted(approved))
+
+
+def _uninstall(node: Node) -> None:
+    if not _confirm(f"Uninstall {node.name} ({node.kind.value})? [y/N] "):
+        print(f"  skipped {node.name}", file=sys.stderr)
+        return
+    mas_id = node.itself.mas_id if node.itself is not None else ""
+    system.uninstall(node.kind, node.name, mas_id)
+
+
+def _confirm(prompt: str) -> bool:
+    try:
+        return input(prompt).strip().lower() == "y"
+    except EOFError:
+        return False
+
+
+def _unique(names: list[str]) -> list[str]:
+    return sorted({name for name in names if name})

freshenup-3.0.0/src/freshenup/models.py

@@ -0,0 +1,39 @@
+"""Domain types: the outdated Item the rest of freshenup works with."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Kind(Enum):
+    FORMULA = "formula"
+    CASK = "cask"
+    MAS = "mas"
+
+    @property
+    def label(self) -> str:
+        return {Kind.FORMULA: "(formula)", Kind.CASK: "(cask)", Kind.MAS: "(App Store)"}[self]
+
+
+@dataclass(frozen=True, slots=True)
+class Item:
+    """One outdated package and its version bump. `mas_id` is set only for App Store apps."""
+
+    kind: Kind
+    name: str
+    current: str
+    latest: str
+    mas_id: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class Node:
+    """One fzf row: a top-level package, optionally its own outdated Item (`itself`), plus any
+    outdated members folded under it — a formula's outdated dependencies, or casks folded under a
+    cask that depends on them."""
+
+    kind: Kind
+    name: str
+    itself: Item | None = None
+    members: tuple[Item, ...] = ()