fix(#390): Add admin elevation check to fail fast with clear error me…

src/Infrastructure/AppRunner.cs

@@ -1,3 +1,4 @@
+using WinHome.Infrastructure.Helpers;
 using WinHome.Interfaces;
 using WinHome.Models;
 using WinHome.Services.Logging;
@@ -37,6 +38,8 @@ public async Task<int> RunAsync(FileInfo configFile, bool dryRun, string? profil
   {
     try
     {
+      AdminGuard.EnsureAdministrator();
+
       if (!configFile.Exists)
       {
         _logger.LogError($"[Error] Configuration file not found: {configFile.FullName}");

src/Infrastructure/Helpers/AdminGuard.cs

@@ -0,0 +1,39 @@
+using System.Security.Principal;
+using System.Runtime.Versioning;
+
+namespace WinHome.Infrastructure.Helpers;
+
+/// <summary>Validates that the current process has administrative privileges.</summary>
+[SupportedOSPlatform("windows")]
+public static class AdminGuard
+{
+    internal static Func<bool> IsAdministrator = () =>
+    {
+        using var identity = WindowsIdentity.GetCurrent();
+        var principal = new WindowsPrincipal(identity);
+        return principal.IsInRole(WindowsBuiltInRole.Administrator);
+    };
+
+    /// <summary>Throws if the current process is not running as Administrator.</summary>
+    /// <exception cref="UnauthorizedAccessException">Thrown when not running with admin privileges.</exception>
+    public static void EnsureAdministrator()
+    {
+        if (!IsAdministrator())
+        {
+            throw new UnauthorizedAccessException(
+                "Error: WinHome requires Administrative Privileges to manage system configurations. " +
+                "Please re-run this command from an elevated (Administrator) terminal.");
+        }
+    }
+
+    /// <summary>Resets the administrator check delegate to its default implementation (used for testing).</summary>
+    internal static void ResetAdminCheck()
+    {
+        IsAdministrator = () =>
+        {
+            using var identity = WindowsIdentity.GetCurrent();
+            var principal = new WindowsPrincipal(identity);
+            return principal.IsInRole(WindowsBuiltInRole.Administrator);
+        };
+    }
+}

tests/WinHome.Tests/AdminGuardTests.cs

@@ -0,0 +1,32 @@
+using WinHome.Infrastructure.Helpers;
+using Xunit;
+
+namespace WinHome.Tests;
+
+[Collection("SequentialTests")]
+public class AdminGuardTests
+{
+    [Fact]
+    public void EnsureAdministrator_DoesNotThrow_WhenAdmin()
+    {
+        AdminGuard.IsAdministrator = () => true;
+        var ex = Record.Exception(() => AdminGuard.EnsureAdministrator());
+        Assert.Null(ex);
+    }
+
+    [Fact]
+    public void EnsureAdministrator_ThrowsUnauthorizedAccessException_WhenNotAdmin()
+    {
+        AdminGuard.IsAdministrator = () => false;
+        var ex = Assert.Throws<UnauthorizedAccessException>(() => AdminGuard.EnsureAdministrator());
+        Assert.Contains("Administrative Privileges", ex.Message);
+    }
+
+    [Fact]
+    public void ResetAdminCheck_RestoresDefaultDelegate()
+    {
+        AdminGuard.IsAdministrator = () => false;
+        AdminGuard.ResetAdminCheck();
+        Assert.NotNull(AdminGuard.IsAdministrator);
+    }
+}