From 2da90c2a893cc4bc20ea58df5cdd58bb4a911cde Mon Sep 17 00:00:00 2001
From: Jon Gallant <jong@microsoft.com>
Date: Sat, 18 Jul 2026 08:00:39 -0700
Subject: [PATCH] fix(mage): report PATH changes clearly during install

`mage install` added the dev bin dir to the User PATH but never said so:
the last PATH line users saw was "Machine PATH failed (need admin), trying
User PATH..." with no confirmation, and the User PATH fallback swallowed
its error, so a genuine failure looked identical to success. Users
reasonably concluded install did not touch PATH.

- Print "Added to Machine PATH." / "Added to User PATH." on success.
- Surface a warning (with the error) when the User PATH write actually
  fails, instead of failing silently.
- End the install with a hint: open a new terminal, then `dispatch-dev`,
  since already-open shells keep the old PATH.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 524cf702-8922-4cfd-b23f-4069b734e09b
---
 magefile.go | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/magefile.go b/magefile.go
index e581dab5..12e059a8 100644
--- a/magefile.go
+++ b/magefile.go
@@ -450,15 +450,22 @@ func ensurePath() error {
 		return nil
 	}
 
-	fmt.Printf("\n=== Adding %s to system PATH ===\n", binDir)
-	newPath := binDir + ";" + machinePath
-	err := exec.Command("powershell", "-NoProfile", "-Command",
-		fmt.Sprintf(`[Environment]::SetEnvironmentVariable('Path','%s','Machine')`, newPath)).Run()
-	if err != nil {
-		fmt.Println("   Machine PATH failed (need admin), trying User PATH...")
-		if !containsPath(userPath, binDir) {
-			exec.Command("powershell", "-NoProfile", "-Command",
-				fmt.Sprintf(`[Environment]::SetEnvironmentVariable('Path','%s;%s','User')`, binDir, userPath)).Run()
+	fmt.Printf("\n=== Adding %s to PATH ===\n", binDir)
+	// Prefer Machine PATH (visible to every user) but fall back to User PATH,
+	// which does not need administrator rights. Report the outcome either way
+	// so a failed persist is never silent.
+	machineErr := exec.Command("powershell", "-NoProfile", "-Command",
+		fmt.Sprintf(`[Environment]::SetEnvironmentVariable('Path','%s;%s','Machine')`, binDir, machinePath)).Run()
+	if machineErr == nil {
+		fmt.Println("   Added to Machine PATH.")
+	} else {
+		fmt.Println("   Machine PATH needs admin; adding to User PATH instead...")
+		if userErr := exec.Command("powershell", "-NoProfile", "-Command",
+			fmt.Sprintf(`[Environment]::SetEnvironmentVariable('Path','%s;%s','User')`, binDir, userPath)).Run(); userErr != nil {
+			fmt.Printf("   WARNING: could not add %s to User PATH: %v\n", binDir, userErr)
+			fmt.Println("   Add it manually, or re-run `mage install` from an elevated terminal.")
+		} else {
+			fmt.Println("   Added to User PATH.")
 		}
 	}
 	ensureSessionPath(binDir)
@@ -555,6 +562,7 @@ func verify() error {
 	fmt.Printf("\n✅ %s installed\n", binaryName())
 	fmt.Printf("   Path:  %s\n", outPath)
 	fmt.Printf("   Built: %s\n", info.ModTime().Format(time.DateTime))
+	fmt.Printf("   Run:   open a new terminal, then `%s` (already-open shells keep the old PATH)\n", binName)
 	return nil
 }