Add environment check APIs

Add EnvironmentChecker that performs a comprehensive check of the Apple
development environment by aggregating results from CommandLineTools,
XcodeManager, and RuntimeService.

Includes Xcode license validation (xcodebuild -license check) and
first-launch support (xcodebuild -runFirstLaunch), patterns from
ClientTools.Platform iOSSshCommandsExtensions.

Also maps platform SDK directory names to friendly names (e.g.
iPhoneOS -> iOS, XROS -> visionOS).

Includes dependencies from PRs #156, #157, #159 which will merge
cleanly when those PRs land first.

Closes #148

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: rmarinho

Xamarin.MacDev/EnvironmentChecker.cs

@@ -0,0 +1,171 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+using System.IO;
+using System.Linq;
+
+using Xamarin.MacDev.Models;
+
+#nullable enable
+
+namespace Xamarin.MacDev {
+
+	/// <summary>
+	/// Performs a comprehensive check of the Apple development environment.
+	/// Aggregates results from <see cref="CommandLineTools"/>,
+	/// <see cref="XcodeManager"/>, and <see cref="RuntimeService"/>.
+	/// Also validates Xcode license acceptance and first-launch state,
+	/// patterns from ClientTools.Platform iOSSshCommandsExtensions.
+	/// </summary>
+	public class EnvironmentChecker {
+
+		readonly ICustomLogger log;
+
+		public EnvironmentChecker (ICustomLogger log)
+		{
+			this.log = log ?? throw new ArgumentNullException (nameof (log));
+		}
+
+		/// <summary>
+		/// Runs a full environment check and returns the results.
+		/// </summary>
+		public EnvironmentCheckResult Check ()
+		{
+			var result = new EnvironmentCheckResult ();
+
+			// 1. Check Xcode
+			var xcodeManager = new XcodeManager (log);
+			var xcode = xcodeManager.GetBest ();
+			result.Xcode = xcode;
+
+			if (xcode is not null) {
+				log.LogInfo ("Xcode {0} found at '{1}'.", xcode.Version, xcode.Path);
+
+				// Check license acceptance (pattern from ClientTools.Platform)
+				if (IsXcodeLicenseAccepted (xcode.Path))
+					log.LogInfo ("Xcode license is accepted.");
+				else
+					log.LogInfo ("Xcode license may not be accepted. Run 'sudo xcodebuild -license accept'.");
+
+				// Collect platform SDKs
+				result.Platforms = GetPlatforms (xcode.Path);
+			} else {
+				log.LogInfo ("No Xcode installation found.");
+			}
+
+			// 2. Check Command Line Tools
+			var clt = new CommandLineTools (log);
+			result.CommandLineTools = clt.Check ();
+
+			// 3. Check runtimes
+			var runtimeService = new RuntimeService (log);
+			result.Runtimes = runtimeService.List (availableOnly: true);
+
+			// 4. Derive overall status
+			result.DeriveStatus ();
+
+			log.LogInfo ("Environment check complete. Status: {0}.", result.Status);
+			return result;
+		}
+
+		/// <summary>
+		/// Checks whether the Xcode license has been accepted by running
+		/// <c>xcodebuild -license check</c>.
+		/// Pattern from ClientTools.Platform iOSSshCommandsExtensions.CheckXcodeLicenseAsync.
+		/// </summary>
+		public bool IsXcodeLicenseAccepted (string xcodePath)
+		{
+			var xcodebuildPath = Path.Combine (xcodePath, "Contents", "Developer", "usr", "bin", "xcodebuild");
+			if (!File.Exists (xcodebuildPath))
+				return false;
+
+			try {
+				var (exitCode, _, _) = ProcessUtils.Exec (xcodebuildPath, "-license", "check");
+				return exitCode == 0;
+			} catch (System.ComponentModel.Win32Exception) {
+				return false;
+			}
+		}
+
+		/// <summary>
+		/// Runs <c>xcodebuild -runFirstLaunch</c> to ensure packages are installed.
+		/// Pattern from ClientTools.Platform iOSSshCommandsExtensions.RunXcodeBuildFirstLaunchAsync.
+		/// Returns true if the command succeeded.
+		/// </summary>
+		public bool RunFirstLaunch (string xcodePath)
+		{
+			var xcodebuildPath = Path.Combine (xcodePath, "Contents", "Developer", "usr", "bin", "xcodebuild");
+			if (!File.Exists (xcodebuildPath)) {
+				log.LogInfo ("xcodebuild not found at '{0}'.", xcodebuildPath);
+				return false;
+			}
+
+			try {
+				log.LogInfo ("Running xcodebuild -runFirstLaunch...");
+				var (exitCode, _, stderr) = ProcessUtils.Exec (xcodebuildPath, "-runFirstLaunch");
+				if (exitCode != 0) {
+					log.LogInfo ("xcodebuild -runFirstLaunch failed (exit {0}): {1}", exitCode, stderr.Trim ());
+					return false;
+				}
+
+				log.LogInfo ("xcodebuild -runFirstLaunch completed successfully.");
+				return true;
+			} catch (System.ComponentModel.Win32Exception ex) {
+				log.LogInfo ("Could not run xcodebuild: {0}", ex.Message);
+				return false;
+			}
+		}
+
+		/// <summary>
+		/// Gets the list of available platform SDK directories in the Xcode bundle.
+		/// </summary>
+		System.Collections.Generic.List<string> GetPlatforms (string xcodePath)
+		{
+			var platforms = new System.Collections.Generic.List<string> ();
+			var platformsDir = Path.Combine (xcodePath, "Contents", "Developer", "Platforms");
+
+			if (!Directory.Exists (platformsDir))
+				return platforms;
+
+			try {
+				foreach (var dir in Directory.GetDirectories (platformsDir, "*.platform")) {
+					var name = Path.GetFileNameWithoutExtension (dir);
+					// Convert "iPhoneOS" to "iOS", "AppleTVOS" to "tvOS", etc.
+					var friendly = MapPlatformName (name);
+					if (!platforms.Contains (friendly))
+						platforms.Add (friendly);
+				}
+			} catch (UnauthorizedAccessException ex) {
+				log.LogInfo ("Could not read platforms directory: {0}", ex.Message);
+			}
+
+			return platforms;
+		}
+
+		/// <summary>
+		/// Maps Apple platform directory names to friendly names.
+		/// </summary>
+		public static string MapPlatformName (string sdkName)
+		{
+			switch (sdkName) {
+			case "iPhoneOS":
+			case "iPhoneSimulator":
+				return "iOS";
+			case "AppleTVOS":
+			case "AppleTVSimulator":
+				return "tvOS";
+			case "WatchOS":
+			case "WatchSimulator":
+				return "watchOS";
+			case "XROS":
+			case "XRSimulator":
+				return "visionOS";
+			case "MacOSX":
+				return "macOS";
+			default:
+				return sdkName;
+			}
+		}
+	}
+}

Xamarin.MacDev/RuntimeService.cs

@@ -0,0 +1,151 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+
+using Xamarin.MacDev.Models;
+
+#nullable enable
+
+namespace Xamarin.MacDev {
+
+	/// <summary>
+	/// Manages simulator runtimes via <c>xcrun simctl</c> and <c>xcodebuild</c>.
+	/// Lists installed runtimes and supports downloading new platform runtimes.
+	/// Download approach from ClientTools.Platform: <c>xcodebuild -downloadPlatform iOS</c>.
+	/// </summary>
+	public class RuntimeService {
+
+		static readonly string XcrunPath = "/usr/bin/xcrun";
+		static readonly string XcodebuildRelativePath = "Contents/Developer/usr/bin/xcodebuild";
+
+		readonly ICustomLogger log;
+
+		public RuntimeService (ICustomLogger log)
+		{
+			this.log = log ?? throw new ArgumentNullException (nameof (log));
+		}
+
+		/// <summary>
+		/// Lists installed simulator runtimes. Optionally filters by availability.
+		/// Uses <c>xcrun simctl list runtimes --json</c>.
+		/// </summary>
+		public List<SimulatorRuntimeInfo> List (bool availableOnly = false)
+		{
+			var json = RunSimctl ("list", "runtimes", "--json");
+			if (json is null)
+				return new List<SimulatorRuntimeInfo> ();
+
+			var runtimes = SimctlOutputParser.ParseRuntimes (json);
+
+			if (availableOnly)
+				runtimes.RemoveAll (r => !r.IsAvailable);
+
+			log.LogInfo ("Found {0} simulator runtime(s).", runtimes.Count);
+			return runtimes;
+		}
+
+		/// <summary>
+		/// Lists runtimes for a specific platform (e.g. "iOS", "tvOS", "watchOS", "visionOS").
+		/// </summary>
+		public List<SimulatorRuntimeInfo> ListByPlatform (string platform, bool availableOnly = false)
+		{
+			var all = List (availableOnly);
+			return all.Where (r => string.Equals (r.Platform, platform, StringComparison.OrdinalIgnoreCase)).ToList ();
+		}
+
+		/// <summary>
+		/// Downloads a platform runtime using <c>xcodebuild -downloadPlatform</c>.
+		/// Pattern from ClientTools.Platform RemoteSimulatorValidator.
+		/// </summary>
+		/// <param name="platform">The platform to download (e.g. "iOS", "tvOS", "watchOS", "visionOS").</param>
+		/// <param name="xcodePath">The Xcode.app path. If null, looks for xcodebuild in PATH via xcrun.</param>
+		/// <returns>True if the download command succeeded.</returns>
+		public bool DownloadPlatform (string platform, string? xcodePath = null)
+		{
+			if (string.IsNullOrEmpty (platform))
+				throw new ArgumentException ("Platform must not be null or empty.", nameof (platform));
+
+			var xcodebuildPath = ResolveXcodebuild (xcodePath);
+			if (xcodebuildPath is null) {
+				log.LogInfo ("Cannot download platform: xcodebuild not found.");
+				return false;
+			}
+
+			log.LogInfo ("Downloading {0} platform runtime via xcodebuild...", platform);
+
+			try {
+				var (exitCode, stdout, stderr) = ProcessUtils.Exec (xcodebuildPath, "-downloadPlatform", platform);
+				if (exitCode != 0) {
+					log.LogInfo ("xcodebuild -downloadPlatform {0} failed (exit {1}): {2}", platform, exitCode, stderr.Trim ());
+					return false;
+				}
+
+				log.LogInfo ("Successfully downloaded {0} platform runtime.", platform);
+				return true;
+			} catch (System.ComponentModel.Win32Exception ex) {
+				log.LogInfo ("Could not run xcodebuild: {0}", ex.Message);
+				return false;
+			}
+		}
+
+		/// <summary>
+		/// Resolves the path to xcodebuild. If xcodePath is given, looks inside the Xcode bundle.
+		/// Otherwise falls back to /usr/bin/xcrun xcodebuild.
+		/// </summary>
+		string? ResolveXcodebuild (string? xcodePath)
+		{
+			if (!string.IsNullOrEmpty (xcodePath)) {
+				var path = Path.Combine (xcodePath!, XcodebuildRelativePath);
+				if (File.Exists (path))
+					return path;
+			}
+
+			// Fall back to xcrun to find xcodebuild
+			if (File.Exists (XcrunPath)) {
+				try {
+					var (exitCode, stdout, _) = ProcessUtils.Exec (XcrunPath, "--find", "xcodebuild");
+					if (exitCode == 0) {
+						var path = stdout.Trim ();
+						if (File.Exists (path))
+							return path;
+					}
+				} catch (System.ComponentModel.Win32Exception) {
+					// fall through
+				}
+			}
+
+			return null;
+		}
+
+		/// <summary>
+		/// Runs a simctl subcommand and returns stdout, or null on failure.
+		/// </summary>
+		string? RunSimctl (params string [] args)
+		{
+			if (!File.Exists (XcrunPath)) {
+				log.LogInfo ("xcrun not found at '{0}'.", XcrunPath);
+				return null;
+			}
+
+			var fullArgs = new string [args.Length + 1];
+			fullArgs [0] = "simctl";
+			Array.Copy (args, 0, fullArgs, 1, args.Length);
+
+			try {
+				var (exitCode, stdout, stderr) = ProcessUtils.Exec (XcrunPath, fullArgs);
+				if (exitCode != 0) {
+					log.LogInfo ("simctl {0} failed (exit {1}): {2}", args [0], exitCode, stderr.Trim ());
+					return null;
+				}
+				return stdout;
+			} catch (System.ComponentModel.Win32Exception ex) {
+				log.LogInfo ("Could not run xcrun: {0}", ex.Message);
+				return null;
+			}
+		}
+	}
+}