Add AdbRunner for adb CLI operations (#283)

## Summary

Wraps `adb` CLI operations for device management. Addresses #279.

Parsing/formatting/merging logic ported from `dotnet/android` `GetAvailableAndroidDevices` MSBuild task, enabling code sharing via the `external/xamarin-android-tools` submodule. See draft PR: dotnet/android#10880

## Public API

```csharp
public class AdbRunner
{
    // Constructor — requires full path to adb executable
    public AdbRunner(string adbPath, IDictionary<string, string>? environmentVariables = null);

    // Instance methods (async, invoke adb process)
    public Task<IReadOnlyList<AdbDeviceInfo>> ListDevicesAsync(CancellationToken ct = default);
    public Task WaitForDeviceAsync(string? serial = null, TimeSpan? timeout = null, CancellationToken ct = default);
    public Task StopEmulatorAsync(string serial, CancellationToken ct = default);

    // Static helpers — public so dotnet/android can call without instantiating AdbRunner
    public static List<AdbDeviceInfo> ParseAdbDevicesOutput(IEnumerable<string> lines);
    public static AdbDeviceStatus MapAdbStateToStatus(string adbState);
    public static string BuildDeviceDescription(AdbDeviceInfo device, Action<TraceLevel, string>? logger = null);
    public static string FormatDisplayName(string avdName);
    public static List<AdbDeviceInfo> MergeDevicesAndEmulators(
        IReadOnlyList<AdbDeviceInfo> adbDevices,
        IReadOnlyList<string> availableEmulators,
        Action<TraceLevel, string>? logger = null);
}
```

**Internal methods** (not part of public API):
- `GetEmulatorAvdNameAsync` — queries AVD name via `adb emu avd name` with TCP console fallback
- `ProcessUtils.ThrowIfFailed` — shared exit code validation (string and StringWriter overloads)

## Key Design Decisions

- **Constructor takes `string adbPath`**: Callers pass the resolved path; no lazy `Func<>` indirection. Optional `environmentVariables` dictionary for ANDROID_HOME/JAVA_HOME/PATH.
- **Static parsing methods** are `public static` so `dotnet/android` can call them without instantiating `AdbRunner` (e.g., `GetAvailableAndroidDevices` MSBuild task passes `List<string>` to `ParseAdbDevicesOutput`)
- **`IEnumerable<string>` overload**: `dotnet/android` passes `List<string>` directly from output lines
- **Logger parameter**: `BuildDeviceDescription` and `MergeDevicesAndEmulators` accept `Action<TraceLevel, string>?` — `dotnet/android` passes `this.CreateTaskLogger()` for MSBuild trace output
- **Regex with explicit state list**: Uses `\s+` separator to match one or more whitespace characters (spaces or tabs). Matches explicit known states with `IgnoreCase`. Daemon startup lines (`*`) are pre-filtered.
- **Exit code checking**: `ListDevicesAsync`, `WaitForDeviceAsync`, and `StopEmulatorAsync` throw `InvalidOperationException` with stderr context on non-zero exit via `ProcessUtils.ThrowIfFailed` (internal)
- **`MapAdbStateToStatus` as switch expression**: Simple value mapping uses C# switch expression for conciseness
- **Property patterns instead of null-forgiving**: Uses `is { Length: > 0 }` patterns throughout for null checks on `netstandard2.0` where `string.IsNullOrEmpty()` lacks `[NotNullWhen(false)]`
- **FormatDisplayName**: Lowercases before `ToTitleCase` to normalize mixed-case input (e.g., "PiXeL" → "Pixel")
- **Environment variables via `StartProcess`**: Runners pass env vars dictionary to `ProcessUtils.StartProcess`. `AndroidEnvironmentHelper.GetEnvironmentVariables()` builds the dict.

## Tests

**45 unit tests** (`AdbRunnerTests.cs`):
- **ParseAdbDevicesOutput**: real-world data, empty output, single/multiple devices, mixed states, daemon messages, IP:port, Windows newlines, recovery/sideload, tab-separated output
- **FormatDisplayName**: underscores, title case, API capitalization, mixed case, special chars, empty
- **MapAdbStateToStatus**: all known states + unknown (recovery, sideload)
- **MergeDevicesAndEmulators**: no emulators, no running, mixed, case-insensitive dedup, sorting
- **Constructor**: valid path, null/empty throws
- **WaitForDeviceAsync**: timeout validation (negative, zero)

**4 integration tests** (`RunnerIntegrationTests.cs`):
- Run only when `TF_BUILD=True` or `CI=true` (case-insensitive truthy check), skipped locally
- Require pre-installed JDK (`JAVA_HOME`) and Android SDK (`ANDROID_HOME`) on CI agent
- `Assert.Ignore` when `ANDROID_HOME` missing (no bootstrap/network dependency)
- Cover: constructor, `ListDevicesAsync`, `WaitForDeviceAsync` timeout, tool discovery

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Jonathan Peppers <jonathan.peppers@microsoft.com>

Author: 3 people

.github/copilot-instructions.md

@@ -49,6 +49,8 @@ When setting environment variables for SDK tools (e.g. `sdkmanager`, `avdmanager
 - **File-scoped namespaces**: all new files should use file-scoped namespaces (`namespace Foo;` instead of `namespace Foo { ... }`).
 - **Static `HttpClient`**: `HttpClient` instances must be `static` to avoid socket exhaustion. See [HttpClient guidelines](https://learn.microsoft.com/dotnet/fundamentals/networking/http/httpclient-guidelines#recommended-use). Do not create per-instance `HttpClient` fields or dispose them in `IDisposable`.
 - [Mono Coding Guidelines](http://www.mono-project.com/community/contributing/coding-guidelines/): tabs, K&R braces, `PascalCase` public members.
+- **No null-forgiving operator (`!`)**: do not use the null-forgiving operator after null checks. Instead, use C# property patterns (e.g. `if (value is { Length: > 0 } v)`) which give the compiler proper non-null flow analysis on all target frameworks including `netstandard2.0`.
+- **Prefer switch expressions**: use C# switch expressions over switch statements for simple value mappings (e.g. `return state switch { "x" => A, _ => B };`). Use switch statements only when the body has side effects or complex logic.
 - Nullable enabled in `AndroidSdk`. `NullableAttributes.cs` excluded on `net10.0+`.
 - Strong-named via `product.snk`. In the AndroidSdk project, tests use `InternalsVisibleTo` with full public key (`Properties/AssemblyInfo.cs`).
 - Assembly names support `$(VendorPrefix)`/`$(VendorSuffix)` for branding forks.

src/Xamarin.Android.Tools.AndroidSdk/EnvironmentVariableNames.cs

@@ -40,5 +40,17 @@ internal static class EnvironmentVariableNames
 		/// Executable file extensions (Windows).
 		/// </summary>
 		public const string PathExt = "PATHEXT";
+
+		/// <summary>
+		/// Overrides the default location for Android user-specific data
+		/// (AVDs, preferences, etc.). Defaults to $HOME/.android.
+		/// </summary>
+		public const string AndroidUserHome = "ANDROID_USER_HOME";
+
+		/// <summary>
+		/// Overrides the AVD storage directory. Takes precedence over
+		/// <see cref="AndroidUserHome"/>/avd.
+		/// </summary>
+		public const string AndroidAvdHome = "ANDROID_AVD_HOME";
 	}
 }

src/Xamarin.Android.Tools.AndroidSdk/Models/AdbDeviceInfo.cs

@@ -0,0 +1,62 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Xamarin.Android.Tools;
+
+/// <summary>
+/// Represents an Android device or emulator from 'adb devices -l' output.
+/// Mirrors the metadata produced by dotnet/android's GetAvailableAndroidDevices task.
+/// </summary>
+public class AdbDeviceInfo
+{
+	/// <summary>
+	/// Serial number of the device (e.g., "emulator-5554", "0A041FDD400327").
+	/// For non-running emulators, this is the AVD name.
+	/// </summary>
+	public string Serial { get; set; } = string.Empty;
+
+	/// <summary>
+	/// Human-friendly description of the device (e.g., "Pixel 7 API 35", "Pixel 6 Pro").
+	/// </summary>
+	public string Description { get; set; } = string.Empty;
+
+	/// <summary>
+	/// Device type: Device or Emulator.
+	/// </summary>
+	public AdbDeviceType Type { get; set; }
+
+	/// <summary>
+	/// Device status: Online, Offline, Unauthorized, NoPermissions, NotRunning, Unknown.
+	/// </summary>
+	public AdbDeviceStatus Status { get; set; }
+
+	/// <summary>
+	/// AVD name for emulators (e.g., "pixel_7_api_35"). Null for physical devices.
+	/// </summary>
+	public string? AvdName { get; set; }
+
+	/// <summary>
+	/// Device model from adb properties (e.g., "Pixel_6_Pro").
+	/// </summary>
+	public string? Model { get; set; }
+
+	/// <summary>
+	/// Product name from adb properties (e.g., "raven").
+	/// </summary>
+	public string? Product { get; set; }
+
+	/// <summary>
+	/// Device code name from adb properties (e.g., "raven").
+	/// </summary>
+	public string? Device { get; set; }
+
+	/// <summary>
+	/// Transport ID from adb properties.
+	/// </summary>
+	public string? TransportId { get; set; }
+
+	/// <summary>
+	/// Whether this device is an emulator.
+	/// </summary>
+	public bool IsEmulator => Type == AdbDeviceType.Emulator;
+}

src/Xamarin.Android.Tools.AndroidSdk/Models/AdbDeviceStatus.cs

@@ -0,0 +1,17 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Xamarin.Android.Tools;
+
+/// <summary>
+/// Represents the status of an Android device.
+/// </summary>
+public enum AdbDeviceStatus
+{
+	Online,
+	Offline,
+	Unauthorized,
+	NoPermissions,
+	NotRunning,
+	Unknown
+}

src/Xamarin.Android.Tools.AndroidSdk/Models/AdbDeviceType.cs

@@ -0,0 +1,13 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Xamarin.Android.Tools;
+
+/// <summary>
+/// Represents the type of an Android device.
+/// </summary>
+public enum AdbDeviceType
+{
+	Device,
+	Emulator
+}

src/Xamarin.Android.Tools.AndroidSdk/ProcessUtils.cs

@@ -203,6 +203,33 @@ static string JoinArguments (string[] args)
 		}
 #endif
 
+		/// <summary>
+		/// Throws <see cref="InvalidOperationException"/> when <paramref name="exitCode"/> is non-zero.
+		/// Includes stderr/stdout context in the message when available.
+		/// </summary>
+		internal static void ThrowIfFailed (int exitCode, string command, string? stderr = null, string? stdout = null)
+		{
+			if (exitCode == 0)
+				return;
+
+			var message = $"'{command}' failed with exit code {exitCode}.";
+
+			if (stderr is { Length: > 0 })
+				message += $" stderr:{Environment.NewLine}{stderr.Trim ()}";
+			if (stdout is { Length: > 0 })
+				message += $" stdout:{Environment.NewLine}{stdout.Trim ()}";
+
+			throw new InvalidOperationException (message);
+		}
+
+		/// <summary>
+		/// Overload that accepts <see cref="StringWriter"/> directly so callers don't need to call ToString().
+		/// </summary>
+		internal static void ThrowIfFailed (int exitCode, string command, StringWriter? stderr = null, StringWriter? stdout = null)
+		{
+			ThrowIfFailed (exitCode, command, stderr?.ToString (), stdout?.ToString ());
+		}
+
 		internal static IEnumerable<string> FindExecutablesInPath (string executable)
 		{
 			var path        = Environment.GetEnvironmentVariable (EnvironmentVariableNames.Path) ?? "";