fix(shims): Preserve system PATH case on Windows in goenv exec (#561)

* fix(shims): Preserve system PATH case on Windows in goenv exec (#557)

Windows environment variables are case-insensitive but os.Environ() preserves
the original casing (e.g., Path, PATH, path). Previously, setEnvVar() and
prependToPath() used case-sensitive string matching, causing duplicate
environment variables when the casing didn't match exactly.

This caused PATH to be overwritten instead of prepended, breaking CGO builds
when gcc was in the system PATH but not found after goenv exec.

Changes:
- Added findEnvVar() helper that uses case-insensitive matching on Windows
- Updated setEnvVar() to use findEnvVar and preserve original casing
- Updated prependToPath() to use findEnvVar and preserve original casing
- Added comprehensive unit tests including regression test for issue #557

Fixes #557

* [AB#557] docs: Add optional cross-platform testing with nektos/act

Added instructions for developers who want to run cross-platform CI tests
locally using nektos/act before pushing to GitHub.

Also fixed PATH separator detection in prependToPath() to handle cross-
platform test scenarios where Unix-style paths (with :) are tested on
Windows runners (which default to ; separator).

Changes:
- Added nektos/act installation and usage guide to agent instructions
- Updated when-to-use guidance to cover all OS-specific code, not just shims
- Fixed prependToPath() to detect separator from existing PATH value
- Updated repo memory with cross-platform testing guidance

This is optional - CI always runs full cross-platform tests automatically.

* [AB#557] style: Apply automated formatting

- Format markdown sections with proper spacing
- Align test struct fields
- Clean up whitespace in exec.go

* fix(test): Use count check for colon separator detection

Fixed Windows test failures where drive letter colons (C:) were being
incorrectly detected as path separators.

Changed separator detection from:
  - strings.Contains(currentPath, ":")
to:
  - strings.Count(currentPath, ":") > 1

This distinguishes between:
  - Drive letters: C:\Windows\System32 (one colon)
  - Path separators: /usr/bin:/usr/local/bin (multiple colons)

Fixes test failures:
  - TestPrependToPath/prepend_to_existing_path_-_Windows_(lowercase)
  - TestPrependToPath/prepend_to_existing_PaTh_-_Windows_(mixed_case)

* fix(shims): improve separator detection to handle single-colon Unix paths

Previous logic failed when Unix paths had exactly 1 colon (e.g., /usr/bin:/bin)
because the check was 'count > 1'. This caused Windows CI tests to incorrectly
use semicolon as separator when testing Unix-style paths.

New logic:
- Checks for semicolons first (Windows-style)
- Counts colons but excludes drive letter colons (position 1)
- Any remaining colons indicate Unix-style separator
- Falls back to OS default separator if neither detected

Fixes Windows CI test failure for 'prepend to existing PATH - Unix' case.

Issue #557

Author: ChronosMasterOfAllTime

.github/copilot-instructions.md

@@ -315,6 +315,53 @@ Before submitting a PR:
 4. ✅ No race conditions: `go test -race ./...` (done by `make test`)
 5. ✅ Windows compatibility validated (for shim/path/shell changes)
 
+### Local Cross-Platform Testing (Optional)
+
+**For developers who want to test against Windows/other platforms locally**, you can use [nektos/act](https://github.com/nektos/act) to run GitHub Actions workflows on your machine:
+
+**Installation**:
+
+```bash
+# macOS
+brew install act
+
+# Linux
+curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+
+# Windows
+choco install act-cli
+```
+
+**Usage**:
+
+```bash
+# Run all CI tests (includes Windows)
+act
+
+# Run specific job (e.g., Windows tests only)
+act -j test-windows
+
+# Run with specific platform
+act --platform ubuntu-latest=catthehacker/ubuntu:act-latest
+
+# Dry run to see what would execute
+act --dryrun
+```
+
+**Note**:
+
+- Windows containers require Docker Desktop with Windows containers enabled
+- For Windows-specific tests, you may need larger runners: `act -P windows-latest=-self-hosted`
+- CI will always run full cross-platform tests automatically when you push
+
+**When to use local cross-platform testing**:
+
+- ✅ Testing platform-specific code (Windows batch files, Unix shell scripts, path handling)
+- ✅ Verifying OS-specific features (environment variables, file permissions, executables)
+- ✅ Testing changes to shims, install scripts, or platform detection
+- ✅ Debugging cross-platform CI failures locally
+- ❌ Not needed for most changes (CI handles it automatically)
+
 ### Common Testing Commands
 
 ```bash

AGENTS.md

@@ -220,6 +220,49 @@ Before submitting:
 4. ✅ Windows compatibility validated (if applicable)
 5. ✅ Coverage maintained or improved
 
+### Local Cross-Platform Testing (Optional)
+
+**For developers who want to test against Windows/other platforms locally**, you can use [nektos/act](https://github.com/nektos/act) to run GitHub Actions workflows on your machine:
+
+**Installation**:
+```bash
+# macOS
+brew install act
+
+# Linux
+curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+
+# Windows
+choco install act-cli
+```
+
+**Usage**:
+```bash
+# Run all CI tests (includes Windows)
+act
+
+# Run specific job (e.g., Windows tests only)
+act -j test-windows
+
+# Run with specific platform
+act --platform ubuntu-latest=catthehacker/ubuntu:act-latest
+
+# Dry run to see what would execute
+act --dryrun
+```
+
+**Note**: 
+- Windows containers require Docker Desktop with Windows containers enabled
+- For Windows-specific tests, you may need larger runners: `act -P windows-latest=-self-hosted`
+- CI will always run full cross-platform tests automatically when you push
+
+**When to use local cross-platform testing**:
+- ✅ Testing platform-specific code (Windows batch files, Unix shell scripts, path handling)
+- ✅ Verifying OS-specific features (environment variables, file permissions, executables)
+- ✅ Testing changes to shims, install scripts, or platform detection
+- ✅ Debugging cross-platform CI failures locally
+- ❌ Not needed for most changes (CI handles it automatically)
+
 ### Quick Commands
 
 ```bash

cmd/shims/exec.go

@@ -374,16 +374,44 @@ func runRehashSilent(cfg *config.Config, env *utils.GoenvEnvironment) error {
 	return shimMgr.Rehash()
 }
 
-// setEnvVar sets or updates an environment variable
-func setEnvVar(env []string, key, value string) []string {
-	prefix := key + "="
+// findEnvVar finds an environment variable in the env slice using case-insensitive matching on Windows.
+// Returns the index and the actual key name (with original casing) if found, or -1 and empty string if not found.
+// On Unix systems, matching is case-sensitive.
+func findEnvVar(env []string, key string) (int, string) {
 	for i, envVar := range env {
-		if strings.HasPrefix(envVar, prefix) {
-			env[i] = prefix + value
-			return env
+		// Find the equals sign to separate key from value
+		eqIdx := strings.Index(envVar, "=")
+		if eqIdx == -1 {
+			continue
+		}
+		actualKey := envVar[:eqIdx]
+
+		// On Windows, environment variables are case-insensitive
+		if utils.IsWindows() {
+			if strings.EqualFold(actualKey, key) {
+				return i, actualKey
+			}
+		} else {
+			// On Unix, case-sensitive match
+			if actualKey == key {
+				return i, actualKey
+			}
 		}
 	}
-	return append(env, prefix+value)
+	return -1, ""
+}
+
+// setEnvVar sets or updates an environment variable.
+// On Windows, this handles case-insensitive environment variable names to prevent
+// creating duplicate entries (e.g., both "Path=" and "PATH=").
+func setEnvVar(env []string, key, value string) []string {
+	if idx, actualKey := findEnvVar(env, key); idx != -1 {
+		// Update existing variable, preserving original key casing
+		env[idx] = actualKey + "=" + value
+		return env
+	}
+	// Variable not found, add it with the requested key
+	return append(env, key+"="+value)
 }
 
 // buildCacheSuffix constructs a cache directory suffix that includes ABI variants.
@@ -392,17 +420,40 @@ func buildCacheSuffix(goBinaryPath, goos, goarch string, env []string) string {
 	return cache.BuildCacheSuffix(goBinaryPath, goos, goarch, env)
 }
 
-// prependToPath prepends a directory to the PATH environment variable
+// prependToPath prepends a directory to the PATH environment variable.
+// On Windows, this handles case-insensitive PATH matching to prevent creating duplicate
+// PATH entries (e.g., both "Path=" and "PATH="), which would cause the original system
+// PATH to be lost.
 func prependToPath(env []string, dir string) []string {
-	const pathPrefix = "PATH="
-	for i, envVar := range env {
-		if strings.HasPrefix(envVar, pathPrefix) {
-			currentPath := envVar[len(pathPrefix):]
-			newPath := dir + string(os.PathListSeparator) + currentPath
-			env[i] = pathPrefix + newPath
-			return env
+	if idx, actualKey := findEnvVar(env, "PATH"); idx != -1 {
+		// Found PATH, extract current value and prepend new directory
+		currentPath := env[idx][len(actualKey)+1:] // +1 for the "=" sign
+
+		// Detect separator from existing PATH to handle cross-platform scenarios
+		// (e.g., testing Unix-style paths on Windows)
+		sep := string(os.PathListSeparator) // default to OS separator
+		if strings.Contains(currentPath, ";") {
+			// Semicolon found - Windows-style separator
+			sep = ";"
+		} else {
+			// Check for colons, but exclude Windows drive letter colons (e.g., "C:")
+			colonCount := strings.Count(currentPath, ":")
+			if len(currentPath) >= 2 && currentPath[1] == ':' {
+				// Has a drive letter at the start, subtract it from the count
+				colonCount--
+			}
+			if colonCount > 0 {
+				// Has colons that are path separators (Unix-style)
+				sep = ":"
+			}
+			// Otherwise, use OS default (already set)
 		}
+
+		newPath := dir + sep + currentPath
+		// Preserve original key casing (e.g., "Path" on Windows, "PATH" on Unix)
+		env[idx] = actualKey + "=" + newPath
+		return env
 	}
 	// PATH not found, add it
-	return append(env, pathPrefix+dir)
+	return append(env, "PATH="+dir)
 }