feat(cli): hold back brand-new releases, remember a skipped version, and document the whole surface

Three finishing touches on top of the update ladder. A release younger than the
cooldown window is never installed automatically, so a version that is published
and then pulled minutes later cannot land on anyone's machine. The prompt gains
a third answer — skip this version — which silences that one release without
silencing the next. And the notice carries the release headline when the source
already returned it, at no extra request. Adds docs/src/cli/updates.md as the
one page describing the settings, the environment variables that override them,
and what a check actually sends.

Author: jdalton

changelog.d/7784-update-prompt-auto-and-channels.md

@@ -0,0 +1,105 @@
+### Added
+
+**`prompt` and `auto` update modes now do something, and refuse to do the wrong
+thing.** The previous slice made the modes configurable; this wires them to the
+existing signed self-updater, behind three refusals.
+
+**A package-managed install is never replaced in place.** `perry update`
+overwrites the running executable, which is right for a tarball or `install.sh`
+install and wrong for every managed one: Homebrew, npm, apt and winget each keep
+their own record of what is installed and at what version, and overwriting the
+file underneath leaves that record lying. `prompt` and `auto` now detect the
+owner and name that owner's command instead:
+
+| owner | what Perry says to run |
+|---|---|
+| Homebrew | `brew upgrade perryts/perry/perry` |
+| npm | `npm install -g @perryts/perry@latest` |
+| apt | `sudo apt update && sudo apt install --only-upgrade perry` |
+| winget | `winget upgrade PerryTS.Perry` |
+
+npm gets an extra sentence, because it is the worst case: Perry ships as a
+wrapper package plus a per-platform binary package, so replacing the binary also
+desyncs it from the wrapper that launched it.
+
+**Nothing is offered after a command that failed.** The user is looking at an
+error; a question about upgrading is noise at the worst possible moment, and an
+unattended install would bury the error under progress output. Both active modes
+fall back to a plain notice.
+
+**An unwritable install directory is reported, not attempted.** `install.sh`
+targets `/usr/local/bin`, which is root-owned on a default macOS and most Linux
+boxes. That is now checked *before* anything is downloaded, so the outcome is
+one sentence naming `sudo perry update` rather than a half-finished install. Perry
+never escalates on its own.
+
+**`perry update --mode <off|notify|prompt|auto>`** saves the setting and exits,
+so the one thing people are most likely to change does not require hand-editing
+TOML. It is a read-modify-write through the shared loader, so the rest of the
+file comes back out the way it went in.
+
+**`perry doctor`** now reports the effective mode and, when there is one, the
+package manager that owns the binary — the two questions behind "why did it not
+update".
+
+<details>
+<summary><b>Why the channel detection fails open</b></summary>
+
+Every rule answers "is this definitely managed?", never "is this definitely
+unmanaged?", and an unrecognised layout resolves to self-managed.
+
+That asymmetry is deliberate. Guessing "managed" wrongly would refuse to
+self-update a plain tarball install — the majority case, and the one with no
+other upgrade path. Guessing "self-managed" wrongly costs an in-place update on
+a machine that had a package manager available, which is recoverable by running
+that manager.
+
+The paths are canonicalized before classification, because Homebrew's `perry` in
+`/usr/local/bin` is a symlink into the Cellar; classifying the link rather than
+its target would miss every Homebrew install there is.
+
+apt requires **both** a dpkg file list and a dpkg-owned path, because dpkg does
+not own `/usr/local` — that is `install.sh`'s directory. The path alone would
+misclassify a hand-placed binary; the dpkg list alone would claim a tarball
+install on a machine that also has the `.deb` installed somewhere else. The check
+is a file-existence test rather than a `dpkg -S` subprocess, since this runs on
+the update path of every command.
+</details>
+
+<details>
+<summary><b>Prompting needs stdin, not just stderr</b></summary>
+
+The mode gate already requires stderr to be a terminal. That is not enough to
+ask a question: stdin can be a pipe while stderr is a tty, and reading from it
+would either block the command or take whatever the pipe happened to contain as
+consent. `prompt` degrades to a plain notice when stdin is not a terminal.
+
+`auto` asks nothing, so it does not need stdin — but it does still require the
+command to have succeeded, an unmanaged install, and a writable directory.
+</details>
+
+<details>
+<summary><b>Tests</b></summary>
+
+24 new, all in the required per-pull-request job. The decision is a pure
+function of the mode plus four facts about the machine, so every refusal is
+asserted directly rather than left inside an `if` in the middle of a teardown
+path:
+
+- both active modes downgrade to a notice after a failed command;
+- both refuse on all four managed channels, and name a command for each;
+- both report elevation rather than attempting an unwritable install;
+- `prompt` degrades without stdin while `auto` does not need it.
+
+The channel table covers Homebrew under all three prefixes, npm for global, nvm
+and project-local layouts, apt with and without each half of its rule, both
+winget delivery shapes, and four unrecognised layouts that must fail open.
+Classification splits on both path separators rather than using
+`Path::components`, so the winget cases run on every host instead of only on
+Windows.
+
+Verified end to end: writing `mode` into a real config file that already had a
+`license_key` and an unknown `[update] future_key` left both intact.
+
+`cargo test -p perry`: 914 passed, 0 failed.
+</details>

changelog.d/7785-update-check-sources.md

@@ -0,0 +1,92 @@
+### Added
+
+**Where Perry asks "what is the latest version?" is now a choice.** It used to
+walk one fixed list — an override, the config, Perry Hub, then the GitHub
+releases API — and read a GitHub-releases-shaped document from whichever
+answered first. That is fine while everyone installs the same way, and wrong as
+soon as they do not: an npm user's "latest" is whatever the registry's `latest`
+dist-tag says, and asking GitHub instead can announce a version their package
+manager cannot install yet.
+
+```toml
+[update]
+source = "npm"              # gh-releases | npm | gh-registry | custom
+package = "@perryts/perry"  # npm-shaped sources; defaults to Perry's own
+registry = "..."            # npm-shaped sources; defaults to the public registry
+server = "..."              # the URL for `custom`, and the mirror override
+```
+
+Unset keeps the historical ladder, so nothing changes for anyone who does not
+set it — except on an **npm-managed install**, which now defaults to asking npm,
+because that is the version its own package manager can actually install.
+
+<details>
+<summary><b>The split that matters: checking is not downloading</b></summary>
+
+A check source answers one question and returns a version, a link, a publish
+time and a headline. It does **not** decide where the binary comes from.
+Artifacts and their signed manifest always resolve from the release
+infrastructure, whatever the check source is.
+
+That separation is load-bearing rather than tidy. The manifest — Ed25519 over
+the artifact's digest and version — is what makes a self-update trustworthy,
+and a check source is a URL a user can point anywhere. Letting it redirect the
+download would turn a configuration setting into a way to install an arbitrary
+binary. Whoever answers "what is new?" never gets to answer "what should I
+run?", and there is a test that fails if a source ever leaks into the artifact
+ladder.
+
+The old `get_update_servers` and its private config reader are **deleted**
+rather than left beside the new code, so the compiler enforces that both call
+sites moved. A new abstraction with the old ladder still wired up underneath is
+the shape where four sources exist, pass their own tests, and are never
+reached.
+</details>
+
+<details>
+<summary><b>Credentials go to exactly one of the four</b></summary>
+
+The npm shapes ask for the *abbreviated* packument
+(`Accept: application/vnd.npm.install-v1+json`) — smaller, cacheable, and the
+document npm itself requests for this question. It also avoids GitHub's
+unauthenticated API rate limit, which the old ladder shared with everything
+else on the machine.
+
+The public registry is asked **without credentials**, and a test asserts no
+`Authorization` header is sent: a token there would be a leak, not a
+convenience. GitHub Packages does need one, so that shape reads `GH_TOKEN` /
+`GITHUB_TOKEN` and fails with a sentence naming the fix when neither is set,
+rather than retrying anonymously and reporting the resulting 404 as "up to
+date".
+
+A configured source does not fall back to the ladder when it errors. Somebody
+who said "ask npm" and got a failure wants to hear that, not a version from
+somewhere they never named.
+</details>
+
+<details>
+<summary><b>Tests</b></summary>
+
+11 new, all parsing real response shapes from string fixtures so no network is
+involved:
+
+- a GitHub release document, including that the `v` prefix is stripped;
+- an abbreviated packument, which has no `time` map — so the publish date reads
+  "unknown" rather than being invented, which matters because the release
+  cooldown in the next slice depends on it;
+- a full packument, which does supply it;
+- a custom manifest with only a `version`, and one with every optional field;
+- that each shape **rejects the others' documents** rather than reading a field
+  that happens to be present — a registry answering a gh-releases request must
+  be an error, not a version of `""`;
+- that a scoped package's `/` is percent-encoded, or the registry reads the
+  scope as a path segment and answers 404;
+- that an unknown `source` name falls back instead of failing, so a config
+  written by a newer Perry does not break an older one;
+- that `custom` with no URL is treated as a missing key rather than a default;
+- that an npm install defaults to npm and every other channel keeps the ladder;
+- that no check source can reach the artifact ladder;
+- and both credential rules.
+
+`cargo test -p perry`: 925 passed, 0 failed.
+</details>

changelog.d/7786-no-cache-migrations.md

@@ -0,0 +1,33 @@
+### Changed
+
+**The update cache carries its shape, and a foreign shape is discarded rather
+than migrated.** `~/.perry/update-check.json` now records a `schema` number; a
+value this build does not recognize — including its absence, which reads as `0` —
+means the file is thrown away and the next check rewrites it.
+
+This replaces the alternative, which was to keep every field optional forever so
+that older shapes still load. That trade is a bad one for a cache: it buys one
+saved network request in exchange for a set of `Option` fields that only exist
+to describe versions nobody runs, and that nothing ever removes. Bumping
+`CACHE_SCHEMA` is now the whole migration story.
+
+**One spelling per check source.** `github`, `npm-registry` and
+`github-packages` are gone; the names are `gh-releases`, `npm`, `gh-registry`
+and `custom`. A set of accepted aliases is a surface to document and test
+forever in exchange for saving one look at the docs.
+
+An unknown `source` still falls back to the default rather than failing, but for
+a different reason than compatibility: an update check is the wrong place to
+turn a config typo into a hard error.
+
+<details>
+<summary><b>Tests</b></summary>
+
+The test that asserted a pre-throttle cache still loads is replaced by one
+asserting the opposite — that a foreign schema, and an absent one, are both
+recognized as not-ours. Verified at runtime as well: a planted cache with no
+schema, claiming version `99.0.0` and a `last_check` in 2099, was ignored, a
+real check ran, and the file came back stamped `"schema": 1`.
+
+`cargo test -p perry`: 930 passed, 0 failed.
+</details>

changelog.d/7786-update-cooldown-skip-docs.md

@@ -0,0 +1,53 @@
+### Added
+
+**`auto` waits a day before installing a brand-new release.** `min_age_hours`
+defaults to 24 for `auto` and 0 for every other mode, so a notice still mentions
+a release the moment it exists while an unattended install holds off.
+
+A release published by mistake, pulled shortly after, or published by someone
+who should not have been able to is most dangerous in its first hours. Waiting
+costs nothing and means your machine is not the one that finds out. `notify` and
+`prompt` are unaffected — they tell a human, who can decide.
+
+**An unknown publish date counts as too fresh, not as old enough.** The
+abbreviated npm document carries no dates, so treating unknown as "old enough"
+would switch the cooldown off for exactly the people using the cheapest source —
+a protection present in the config and absent in effect. `min_age_hours = 0`
+turns it off deliberately.
+
+**The prompt has three answers.** "No" and "never tell me about this one" are
+different intentions, and with only two answers a user who does not want one
+specific release has to switch the whole mode off — which then hides the release
+that fixes it. Answering the third writes `skip_version`, which suppresses
+exactly that version; the next release is mentioned normally.
+
+**The notice says what the release is,** not only that one exists. Sources that
+carry a title now pass it through, and it prints under the version line at no
+extra request.
+
+### Documentation
+
+New page `docs/src/cli/updates.md`, covering the default behaviour, everything
+in `[update]`, the four modes and their three refusals, the four check sources,
+the cooldown, skipping a version, exactly what a check transmits, and where the
+two files live. `perry update`'s section in `commands.md` is rewritten around
+`--mode`; `installation.md` gains the per-package-manager upgrade table; the
+environment tables in `flags.md` gain `NO_UPDATE_NOTIFIER` and
+`PERRY_UPDATE_MODE`.
+
+<details>
+<summary><b>Tests</b></summary>
+
+Four new, bringing the update surface to 22 in `update_policy`:
+
+- `auto` holds off inside the cooldown and installs past it, while `notify` and
+  `prompt` are never held back;
+- an unknown release age is treated as too fresh, and an explicit `0` still lets
+  it through so nobody is stuck;
+- the cooldown defaults to a day for `auto` only, and an explicit value wins for
+  every mode;
+- a skipped version suppresses itself and **not** the next one, which is what
+  separates it from switching notices off.
+
+`cargo test -p perry`: 929 passed, 0 failed.
+</details>

changelog.d/7787-update-surface-followups.md

@@ -0,0 +1,55 @@
+### Fixed
+
+Five defects in the update surface, all found in review of
+[#7749](https://github.com/PerryTS/perry/pull/7749) after it had merged.
+
+**The config warning escaped the rules that were meant to silence it.** The
+"unrecognized `[update] mode`" line was printed inside `UpdatePolicy::resolve`,
+before the precedence rules it sits behind had been applied — so it reached
+stderr during `--format json`, in CI, with a piped stderr, and under `--quiet`.
+Those rules exist to keep exactly those runs silent, and the one line whose job
+was to report a config problem was the one line ignoring them. It is now held on
+the policy and emitted at the single point where the run is known to be speaking
+at all.
+
+**The notify interval throttled on time alone, so it swallowed the next
+release.** The documented contract is that the interval throttles repeats of
+*the same* update. Keyed only on a timestamp, it also suppressed a **different**
+version that arrived inside the window — so somebody setting a week-long
+interval to stop being nagged about one release would also have been denied the
+release that fixed it. The cache now records which version it announced, and a
+different version is announced regardless of the interval.
+
+**The interval comparison was signed.** `Duration::as_secs() as i64` goes
+negative for a large enough configured value, and a negative interval reads as
+already-elapsed — so an absurd value would have notified on *every* run instead
+of suppressing. The comparison is unsigned.
+
+**Two `perry` processes could corrupt the cache.** Every write used one shared
+`*.json.tmp`, so two writers each wrote it and each renamed it: the loser's
+rename landed a file the winner was still writing into. Each write now builds
+its own temporary name.
+
+**A refresh could erase a notice recorded while its request was in flight.**
+`fetch_latest_version` read the notice state *before* issuing its request and
+wrote it back afterwards, overwriting anything recorded in between — telling the
+user about the same release twice. The read-modify-write pairs are now
+serialized by a lock file, and the refresh re-reads inside that lock immediately
+before replacing.
+
+<details>
+<summary><b>Tests</b></summary>
+
+Two new contract tests, both sabotage-verified — reverting either fix turns its
+test red:
+
+- a different version is announced regardless of the interval, and never having
+  announced anything counts as "not this version";
+- an enormous interval still suppresses rather than wrapping into notifying.
+
+The existing interval tests are unchanged in intent: they now go through a
+helper that holds the announced version constant, so they still exercise only
+the interval arithmetic.
+
+`cargo test -p perry`: 904 passed, 0 failed.
+</details>

crates/perry/src/commands/doctor.rs

@@ -286,16 +286,41 @@ fn check_runtime_library() -> CheckResult {
 }
 
 fn check_update_available() -> CheckResult {
+    // Say which mode is in effect and who owns this binary. Both are things a
+    // user asks `doctor` about precisely when updates are not behaving as they
+    // expect — "why did it not install" is almost always one of the two.
+    let policy = crate::update_policy::UpdatePolicy::resolve();
+    let channel = crate::install_channel::detect();
+    // Configured, not effective: `doctor --format json` and `doctor | less` both
+    // suppress the update surface for their own run, so reporting the effective
+    // mode would answer "off" to the very question being asked.
+    let mut detail = format!(" (mode: {}", policy.configured_mode.label());
+    if !policy.is_active() && policy.configured_mode != crate::update_policy::UpdateMode::Off {
+        detail.push_str("; suppressed for this run");
+    }
+    if let Some(command) = channel.upgrade_command() {
+        detail.push_str(&format!(
+            "; installed by {} — upgrade with `{}`",
+            channel.label(),
+            command
+        ));
+    }
+    detail.push(')');
+    let context = detail;
+
     match update_checker::check_cached_status() {
         update_checker::UpdateStatus::UpdateAvailable { latest, .. } => CheckResult {
             name: "update status".to_string(),
             status: CheckStatus::Warning,
-            details: Some(format!("v{} available — run `perry update`", latest)),
+            details: Some(format!(
+                "v{} available — run `perry update`{}",
+                latest, context
+            )),
         },
         update_checker::UpdateStatus::UpToDate => CheckResult {
             name: "update status".to_string(),
             status: CheckStatus::Ok,
-            details: Some("up to date".to_string()),
+            details: Some(format!("up to date{}", context)),
         },
         update_checker::UpdateStatus::CheckFailed => CheckResult {
             name: "update status".to_string(),

crates/perry/src/commands/publish/mod.rs

@@ -35,7 +35,8 @@ pub use args::PublishArgs;
 #[cfg(test)]
 pub(crate) use saved_config::IosSavedConfig; // consumed only by tests
 pub(crate) use saved_config::{
-    check_beta_consent, config_path, is_interactive, load_config, prompt_input, report_beta_error,
+    check_beta_consent, config_path, is_interactive, load_config, load_config_checked,
+    prompt_input, report_beta_error, update_config_file,
     save_config, AndroidSavedConfig, AppleSavedConfig, HarmonyosSavedConfig, PerryConfig,
 };
 pub(crate) use tarball::create_project_tarball_with_filters;