Add AdbRunner for adb CLI operations

.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) ?? "";