Add cross-channel install guard for cargo, winget, and Homebrew

AGENTS.md

@@ -34,6 +34,8 @@ CI runs `cargo test`, `cargo clippy -- -D warnings`, `cargo fmt --check`, and a
 
 ## Project Structure
 ```
+build.rs                 — cargo-install guard (cross-channel install detection)
+src/util/install_channel.rs — install-channel detection + interactive uninstall prompt
 src/
   main.rs              — CLI entry point (clap-based)
   config.rs            — Config load/save, root resolution

Cargo.toml

@@ -23,6 +23,10 @@ exclude = [
 name = "numan"
 path = "src/main.rs"
 
+[[bin]]
+name = "numan-install-guard"
+path = "src/bin/install_guard.rs"
+
 [dependencies]
 # CLI
 clap = { version = "4", features = ["derive"] }

README.md

@@ -127,14 +127,16 @@ brew tap tonythethompson/numan
 brew install numan
 ```
 
-Uses the public [`homebrew-numan`](https://github.com/tonythethompson/homebrew-numan) tap. Formula digests update automatically after each GitHub Release (see [docs/PACKAGING.md](docs/PACKAGING.md)).
+Uses the public [`homebrew-numan`](https://github.com/tonythethompson/homebrew-numan) tap. Formula digests update automatically after each GitHub Release (see [docs/PACKAGING.md](docs/PACKAGING.md)). If you already have numan from cargo or winget, use `scripts/install-homebrew.sh` so the installer prompts to remove the other copy first.
 
 ### winget (Windows)
 
 ```powershell
 winget install tonythethompson.numan
 ```
 
+If you already have numan from **cargo** or **Homebrew**, use `scripts/install-winget.ps1` (winget) or `cargo install` (automatic guard) so the installer prompts to remove the other copy first.
+
 See [packaging/winget/README.md](packaging/winget/README.md) and [docs/PACKAGING.md](docs/PACKAGING.md).
 
 ### crates.io
@@ -143,7 +145,7 @@ See [packaging/winget/README.md](packaging/winget/README.md) and [docs/PACKAGING
 cargo install numan-cli
 ```
 
-Requires [Rust](https://rustup.rs/) (stable). The installed binary is named `numan`.
+Requires [Rust](https://rustup.rs/) (stable). The installed binary is named `numan`. During `cargo install`, numan checks for winget/Homebrew/release copies and prompts to uninstall them first; decline cancels the install.
 
 **Requirements:** a [Nushell](https://www.nushell.sh/) binary on `PATH` for `numan init`, `numan activate`, and related commands.
 

build.rs

@@ -0,0 +1,25 @@
+mod install_channel {
+    #![allow(dead_code)]
+    include!("src/util/install_channel.rs");
+}
+
+fn is_cargo_install_build() -> bool {
+    if std::env::var("CARGO_INSTALL_ROOT").is_ok() {
+        return true;
+    }
+    if let Ok(out_dir) = std::env::var("OUT_DIR") {
+        let normalized = out_dir.replace('\\', "/").to_ascii_lowercase();
+        if normalized.contains("cargo-install") {
+            return true;
+        }
+    }
+    false
+}
+
+fn main() {
+    if is_cargo_install_build()
+        && install_channel::run_cargo_install_guard() != std::process::ExitCode::SUCCESS
+    {
+        std::process::exit(1);
+    }
+}

docs/PACKAGING.md

@@ -37,10 +37,22 @@ python3 scripts/render_homebrew_formula.py --version X.Y.Z --sha256sums SHA256SU
 | GitHub Release | Download archive from [Releases](https://github.com/tonythethompson/numan/releases) |
 | crates.io | `cargo install numan-cli` |
 | From git | `cargo install --git https://github.com/tonythethompson/numan` |
-| Homebrew (tap) | `brew tap tonythethompson/numan && brew install numan` |
-| winget (community) | `winget install tonythethompson.numan` |
+| Homebrew tap | `brew tap tonythethompson/numan && brew install numan` (use `scripts/install-homebrew.sh` when switching from cargo/winget) |
+| winget (community) | `winget install tonythethompson.numan` (use `scripts/install-winget.ps1` when switching from cargo/Homebrew) |
+
+## Install channel guard
+
+Cross-channel installs (cargo vs winget vs Homebrew) prompt to uninstall the existing copy first; declining cancels the install.
+
+| Channel | Guard behavior |
+|---------|----------------|
+| `cargo install numan-cli` | Automatic via `build.rs` during install |
+| winget | `powershell -File scripts/install-winget.ps1` |
+| Homebrew tap | `bash scripts/install-homebrew.sh` |
+| CI / automation | Set `NUMAN_SKIP_INSTALL_GUARD=1` to bypass |
+
+`numan doctor` warns when multiple channels are detected (`install.multiple_channels`).
 
-## Archive layout
 
 Release archives extract to `numan-<version>-<target>/` containing the `numan`
 (or `numan.exe`) binary. Homebrew and winget installers assume this layout.

docs/numan-doctor.md

@@ -129,6 +129,7 @@ Checks run in order below. Implementation should call existing validators (`NuPa
 |----|----------|-----------|
 | `nu.binary.missing_on_path` | `error` | Nu not on PATH and not under `$NUMAN_ROOT/tools/nushell/` → fix: `numan setup nu` |
 | `nu.binary.found_off_path` | `warn` | Nu exists in a known install root (e.g. `~/.cargo/bin`, `%LOCALAPPDATA%\Programs\nushell`) but not on PATH → fix: `numan setup nu use <path>` |
+| `install.multiple_channels` | `warn` | More than one `numan` binary from different install channels (cargo, winget, Homebrew, release archive) → fix: uninstall the other channel(s) before reinstalling |
 | `nu.path.version` | `info` | PATH-only Nu version (`PATH Nu: 0.114.1`), `PATH Nu: not found`, or `PATH Nu: found at '<path>' but version probe failed (<error>)` when the binary exists but `--version` fails. Does not treat managed Nu as PATH. Report-only (no automatic repair). |
 | `nu.managed.version` | `info` | Managed binary under `$NUMAN_ROOT/tools/nushell/` with version, `Managed Nu: not installed`, or `Managed Nu: present at '<path>' but version probe failed (<error>)` when the binary exists but `--version` fails. Report-only (no automatic repair). |
 | `nu.active_version.invalid` | `error` | `nu_state/active-version.json` is present but unreadable/invalid JSON. Lookup would otherwise soft-miss the marker and fall back to PATH. **auto:** copy raw bytes to `active-version.json.corrupt` (best-effort, recoverable `binary_path`), then clear via `clear_active_version` so resolution recovers cleanly. |

packaging/winget/README.md

@@ -20,6 +20,14 @@ After manifests are accepted in [microsoft/winget-pkgs](https://github.com/micro
 winget install tonythethompson.numan
 ```
 
+If you already installed numan via **cargo** or **Homebrew**, use the install guard wrapper so winget prompts to remove the other copy first (plain `winget install` does not):
+
+```powershell
+powershell -File scripts/install-winget.ps1
+```
+
+`cargo install numan-cli` runs the same guard automatically during install.
+
 ## Automated updates
 
 The [`Publish to WinGet`](../../.github/workflows/winget.yml) workflow submits one update PR after each published GitHub Release. It uses the Windows `.zip` release asset and the existing `tonythethompson/winget-pkgs` fork.

scripts/install-cargo.ps1

@@ -0,0 +1,25 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+  Install numan via cargo after checking for conflicting installs from other channels.
+#>
+[CmdletBinding()]
+param(
+    [Parameter(ValueFromRemainingArguments = $true)]
+    [string[]]$CargoArgs = @("install", "--path", ".")
+)
+
+$ErrorActionPreference = "Stop"
+
+$repoRoot = Split-Path -Parent $PSScriptRoot
+$manifest = Join-Path $repoRoot "Cargo.toml"
+
+Write-Host "Checking for conflicting numan installs..."
+& cargo run --quiet --bin numan-install-guard --manifest-path $manifest -- cargo
+if ($LASTEXITCODE -ne 0) {
+    exit $LASTEXITCODE
+}
+
+Write-Host "Running: cargo $($CargoArgs -join ' ')"
+& cargo @CargoArgs --manifest-path $manifest
+exit $LASTEXITCODE

scripts/install-homebrew.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Install numan via Homebrew after checking for conflicting installs from other channels.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+echo "Checking for conflicting numan installs..."
+cargo run --quiet --bin numan-install-guard --manifest-path "${repo_root}/Cargo.toml" -- brew
+echo "Running: brew install tonythethompson/numan/numan ${*}"
+brew install tonythethompson/numan/numan "$@"

scripts/install-winget.ps1

@@ -0,0 +1,24 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+  Install numan via winget after checking for conflicting installs from other channels.
+#>
+[CmdletBinding()]
+param(
+    [string[]]$WingetArgs = @("install", "tonythethompson.numan")
+)
+
+$ErrorActionPreference = "Stop"
+
+$repoRoot = Split-Path -Parent $PSScriptRoot
+$manifest = Join-Path $repoRoot "Cargo.toml"
+
+Write-Host "Checking for conflicting numan installs..."
+& cargo run --quiet --bin numan-install-guard --manifest-path $manifest -- winget
+if ($LASTEXITCODE -ne 0) {
+    exit $LASTEXITCODE
+}
+
+Write-Host "Running: winget $($WingetArgs -join ' ')"
+& winget @WingetArgs
+exit $LASTEXITCODE

src/bin/install_guard.rs

@@ -0,0 +1,18 @@
+use std::env;
+use std::process::ExitCode;
+
+use numan_cli::util::install_channel::{
+    run_cargo_install_guard, run_homebrew_install_guard, run_winget_install_guard,
+};
+
+fn main() -> ExitCode {
+    match env::args().nth(1).map(|s| s.to_ascii_lowercase()) {
+        Some(arg) if arg == "cargo" => run_cargo_install_guard(),
+        Some(arg) if arg == "winget" => run_winget_install_guard(),
+        Some(arg) if arg == "brew" || arg == "homebrew" => run_homebrew_install_guard(),
+        _ => {
+            eprintln!("usage: numan-install-guard <cargo|winget|brew>");
+            ExitCode::from(2)
+        }
+    }
+}

src/cmd/doctor.rs

@@ -38,6 +38,9 @@ use crate::util::hints::{
     ACTIVE_PLUGIN_MUTATION_GATED_FIX, CMD_ACTIVATE, CMD_DEACTIVATE, CMD_DOCTOR_FIX, CMD_INIT,
     CMD_INIT_REFRESH, CMD_REGISTRY_SYNC, CMD_SETUP_NU, CMD_USE,
 };
+use crate::util::install_channel::{
+    classify_binary_path, discover_path_installations, InstallChannel,
+};
 use crate::util::stdio_redirect::StdoutToStderr;
 
 const SCHEMA_VERSION: u32 = 1;
@@ -195,6 +198,7 @@ pub fn run_checks_with_options(
     let mut findings = Vec::new();
 
     check_root_layout(root, &mut findings);
+    check_install_channels(&mut findings);
     check_active_version_marker(root, &mut findings);
     let nu_paths = check_nu_paths(root, options, &mut findings);
     check_nu_environments(root, options, &mut findings);
@@ -322,6 +326,65 @@ fn nu_is_available(root: &Path) -> bool {
     false
 }
 
+fn check_install_channels(findings: &mut Vec<Finding>) {
+    // Doctor uses the cheap PATH-only scan; package-manager trees are checked by install guards.
+    let installs = discover_path_installations();
+    if installs.len() <= 1 {
+        return;
+    }
+
+    let channels: std::collections::HashSet<InstallChannel> =
+        installs.iter().map(|install| install.channel).collect();
+    if channels.len() <= 1 {
+        return;
+    }
+
+    let current = std::env::current_exe().ok();
+    let current_channel = current
+        .as_ref()
+        .map(|path| classify_binary_path(path))
+        .unwrap_or(InstallChannel::Unknown);
+
+    let mut lines =
+        vec!["Multiple numan installs from different package managers were detected:".to_string()];
+    for install in &installs {
+        lines.push(format!(
+            "  {} ({})",
+            install.path.display(),
+            install.channel.label()
+        ));
+    }
+    lines.push(format!(
+        "This session is running the {} build.",
+        current_channel.label()
+    ));
+    lines.push(
+        "Keep one install channel to avoid PATH ambiguity. Uninstall the others before reinstalling."
+            .to_string(),
+    );
+
+    let fix = installs
+        .iter()
+        .filter(|install| install.channel != current_channel)
+        .filter_map(|install| install.channel.uninstall_hint())
+        .collect::<std::collections::HashSet<_>>()
+        .into_iter()
+        .collect::<Vec<_>>()
+        .join("; ");
+
+    findings.push(finding(
+        "install.multiple_channels",
+        Severity::Warn,
+        lines.join("\n"),
+        if fix.is_empty() {
+            None
+        } else {
+            Some(fix.as_str())
+        },
+        RepairTier::Manual,
+    ));
+}
+
 /// Detect a present-but-unreadable `nu_state/active-version.json`.
 ///
 /// `find_nu_executable_with_root` treats marker read errors as soft misses and