feat(cli): wire prompt and auto update modes, behind three refusals

prompt and auto now reach the existing signed self-updater, but never on a
package-managed install: Homebrew, npm, apt and winget each track what they
installed, and overwriting the binary underneath leaves that record lying. The
owner is detected and its own upgrade command named instead. npm says more,
because Perry ships as a wrapper plus a per-platform binary package, so a
replacement also desyncs the wrapper that launched it.

Neither mode offers anything after a command that failed -- the user is
reading an error, and an unattended install would bury it -- and an unwritable
install directory is reported before anything is downloaded rather than
failing halfway through a rename. Perry never escalates on its own.

Channel detection fails open: every rule answers 'definitely managed?', so an
unrecognized layout is treated as ours to replace. Guessing wrong the other
way would refuse to update a tarball install, which is the majority case and
the one with no alternative path. Paths are canonicalized first because
Homebrew's bin entry is a symlink into the Cellar, and apt requires both a
dpkg file list and a dpkg-owned path because dpkg does not own /usr/local.

perry update --mode saves the setting through the shared loader, and doctor
reports the effective mode plus the owning package manager.

Author: jdalton

changelog.d/A2-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>

crates/perry/src/commands/doctor.rs

@@ -286,16 +286,34 @@ 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();
+    let context = match channel.upgrade_command() {
+        Some(command) => format!(
+            " (mode: {}; installed by {} — upgrade with `{}`)",
+            policy.mode.label(),
+            channel.label(),
+            command
+        ),
+        None => format!(" (mode: {})", policy.mode.label()),
+    };
+
     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/update.rs

@@ -15,6 +15,14 @@ pub struct UpdateArgs {
     /// Ignore cache, always fetch from server
     #[arg(long)]
     pub force: bool,
+
+    /// Save how Perry should handle updates from now on, then exit.
+    ///
+    /// This is the writable half of `[update] mode` in ~/.perry/config.toml —
+    /// there to save people hand-editing TOML for the one setting they are
+    /// most likely to want to change.
+    #[arg(long, value_name = "off|notify|prompt|auto")]
+    pub mode: Option<String>,
 }
 
 pub fn run(
@@ -24,6 +32,10 @@ pub fn run(
     verbose: u8,
     quiet: bool,
 ) -> Result<()> {
+    if let Some(raw) = args.mode.as_deref() {
+        return set_mode(raw);
+    }
+
     let current = env!("CARGO_PKG_VERSION");
 
     let status = if !args.force && !update_checker::is_cache_stale() {
@@ -119,3 +131,34 @@ pub fn run(
 
     Ok(())
 }
+
+/// Persist `[update] mode`, and nothing else.
+///
+/// Read-modify-write through the shared loader so the rest of the file — the
+/// license key, the telemetry section, anything a newer Perry wrote — comes
+/// back out the way it went in.
+fn set_mode(raw: &str) -> Result<()> {
+    let Some(mode) = crate::update_policy::UpdateMode::parse(raw) else {
+        anyhow::bail!("unknown update mode `{raw}`. Valid values: off, notify, prompt, auto.");
+    };
+    if mode == crate::update_policy::UpdateMode::Unknown {
+        anyhow::bail!("unknown update mode `{raw}`. Valid values: off, notify, prompt, auto.");
+    }
+
+    let mut config = crate::commands::publish::load_config();
+    config.update.get_or_insert_with(Default::default).mode = Some(mode);
+    crate::commands::publish::save_config(&config)?;
+
+    let path = crate::commands::publish::config_path();
+    println!("Update mode set to \"{raw}\" ({}).", path.display());
+    if mode == crate::update_policy::UpdateMode::Auto {
+        // Say the limits up front rather than letting someone discover them
+        // the first time an update does not happen.
+        println!(
+            "Perry will install updates at the end of a successful run — except \
+             on a package-manager-managed install, where it names that manager's \
+             command instead."
+        );
+    }
+    Ok(())
+}