AI upgrade check

Upgrade Checker (AI) — experimental

fettle upgrade-check asks Claude whether a pending upgrade is safe before you run it. It collects the packages that would upgrade plus a hardware/software profile (inxi), has Claude research the distro's forums (Arch BBS, Manjaro, Ubuntu Forums, Launchpad) for known issues, and returns a clean, cited verdict with concrete before/after steps. It is report-only — it never touches your system; you run fettle -u yourself once you're satisfied.

⚠️ Experimental / under active testing. This feature is still being validated across VMs and distros. Treat its advice as a second opinion, not a guarantee — read the cited forum threads and use your own judgment before upgrading.

export ANTHROPIC_API_KEY=sk-ant-…
fettle upgrade-check                 # verdict + steps -> ~/.fettle/reports/
fettle upgrade-check --effort high   # deeper analysis for a big/risky upgrade
fettle upgrade-check --no-web        # skip forum search (faster, cheaper)
fettle remote HOST upgrade-check     # check a remote host — key stays on YOUR box

For a remote host, fettle gathers the snapshot on the host (read-only, no key) and runs the AI analysis locally with your key, saving ~/.fettle/reports/<host>/ — see Remote maintenance.

• API key (first found wins): ANTHROPIC_API_KEY env → ai_api_key in the config. Prefer the env var. If you put the key in the config, chmod 600 it yourself — fettle refuses a world-writable config but does not reject a world-readable one, so a default 644 file leaks the key to other local users. No key → it just prints the pending-package list. --print-config never prints the key in full — only a sk-ant-…1234 hint and its source.
• Privacy: hardware serials, MAC addresses, and UUIDs are stripped from the inxi output before anything is sent; only the redacted profile + package list reach the API.
• Grounded, not guessed: the model is given the real package list and told to cite a forum source for every claim (and to call the upgrade routine when it finds nothing). fettle then drops any flagged package that isn't actually upgrading and any source outside the trusted forums — so the report can't warn you about things that aren't in your update.
• Cost & controls: one request per run — claude-sonnet-5 at effort=medium, forum searches capped at ai_max_web_searches (default 5). Roughly $0.10–0.30 for a small upgrade, up to ~$0.60 for a large batch (a 330-package Ubuntu run with 5 web searches was ~186k input / 7k output tokens), since the fetched forum pages ride in the input. The exact token + search count prints at the end. Tune via config (ai_model, ai_effort, ai_max_web_searches), --effort, or --no-web (cheapest — skips the forum search entirely).

Actions the model suggests are labelled as such. must_do_before / should_do_after are text the model wrote, and the prompt asks it for concrete commands — so they render as "suggested by the model — verify before running" rather than in the same style as fettle's own advice. Package names in watch_items are checked against the real pending set and dropped if invented; the free-form command text is not validated, which is why it is attributed instead.

Exit status: 1 when the check could not run — no API key, or the analysis came back unavailable. A verdict always exits 0, whatever it says: safe/caution/risky is the model's opinion about an upgrade, not fettle being unable to do its job. The verdict also reaches the run summary, so -U is no longer silent in the digest.

Pure stdlib, like everything else — the API is called over urllib, no anthropic SDK to install (which also means no pip/venv friction on Arch).