Add app lifecycle automation parity

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

Author: mamoreau-devolutions

cli-arguments.md

@@ -19,6 +19,10 @@
 | `--[enable\|disable]-secure-setting key` | Enables/disables the given secure setting<sup>2</sup> for current user. This will generate a UAC prompt  | 3.2.1+ | 
 | `--headless` | Starts the Avalonia host as a pure automation daemon with **no UI** and no requirement for a working graphical environment. Compatible with `--background-api-*` transport arguments. | 2026.1+ |
 | `--automation status` | Queries the local automation service and returns machine-readable status, including the configured background API transport | 2026.1+ |
+| `--automation get-app-state` | Returns app/session automation state including headless mode, current page when a window exists, and which app-level actions are supported by the current host | 2026.1+ |
+| `--automation show-app` | Asks the running UniGetUI instance to show and focus its main window when a UI session exists | 2026.1+ |
+| `--automation navigate-app --page {discover\|updates\|installed\|bundles\|settings\|managers\|own-log\|manager-log\|operation-history\|help\|release-notes\|about} [--manager name] [--help-attachment path]` | Navigates the running UI session to a top-level destination, with optional manager-specific or help-page context where supported | 2026.1+ |
+| `--automation quit-app` | Gracefully shuts down the current UniGetUI session, including the headless automation daemon | 2026.1+ |
 | `--automation get-version` | Reads the local automation service build number through the background API | 2026.1+ |
 | `--automation get-updates` | Reads the currently available updates through the local automation service and returns structured JSON | 2026.1+ |
 | `--automation list-managers` | Lists package managers, readiness, executable metadata, and automation-relevant capability flags | 2026.1+ |
@@ -70,8 +74,8 @@
 | `--automation install-package --manager name --package-id id [--version v] [--scope scope] [--pre-release] [--elevated true\|false] [--interactive true\|false] [--skip-hash true\|false] [--architecture value] [--location path]` | Installs a package through the automation service and waits for completion, honoring the same core install options exposed by the UI | 2026.1+ |
 | `--automation download-package --manager name --package-id id --output path` | Downloads a package installer or artifact to the specified file or directory and returns the resolved saved path | 2026.1+ |
 | `--automation reinstall-package --manager name --package-id id [--version v] [--scope scope] [--pre-release] [--elevated true\|false] [--interactive true\|false] [--skip-hash true\|false] [--architecture value] [--location path]` | Re-runs package installation for an installed package using the requested install options | 2026.1+ |
-| `--automation open-window` | Asks the running UniGetUI instance to show the main window | 2026.1+ |
-| `--automation open-updates` | Asks the running UniGetUI instance to show the Updates page | 2026.1+ |
+| `--automation open-window` | Legacy alias for `--automation show-app` | 2026.1+ |
+| `--automation open-updates` | Legacy alias for `--automation navigate-app --page updates` | 2026.1+ |
 | `--automation show-package --package-id id --package-source source` | Opens the package details flow for the specified package | 2026.1+ |
 | `--automation list-ignored-updates` | Lists ignored update rules tracked by UniGetUI | 2026.1+ |
 | `--automation ignore-package --manager name --package-id id [--version v]` | Adds an ignored-update rule for a package and refreshes the updates view | 2026.1+ |
@@ -98,7 +102,7 @@
 
 - `dotnet src\UniGetUI.Avalonia\bin\Release\net10.0\UniGetUI.Avalonia.dll --headless` starts the local automation daemon without opening any window or requiring a graphical desktop session.
 - `dotnet src\UniGetUI.Cli\bin\Release\net10.0\UniGetUI.Cli.dll <command>` is the cross-platform CLI wrapper for the automation service. It automatically prepends `--automation`, so `UniGetUI.Cli status` and `UniGetUI.Cli search-packages --manager ".NET Tool" --query dotnetsay` work directly.
-- Current agent-oriented command coverage includes status/version, manager/source inspection plus manager enablement, notification suppression, manager-maintenance and executable-path control, settings and secure-settings inspection/mutation, desktop-shortcut state management, app/history/manager log inspection, local backup creation and GitHub cloud-backup/auth flows, current bundle inspection/import/export/add/remove/install flows, package search/details/version listing, ignored-update management, and package install/update/uninstall flows.
+- Current agent-oriented command coverage includes app/session lifecycle inspection and shutdown, manager/source inspection plus manager enablement, notification suppression, manager-maintenance and executable-path control, settings and secure-settings inspection/mutation, desktop-shortcut state management, app/history/manager log inspection, local backup creation and GitHub cloud-backup/auth flows, current bundle inspection/import/export/add/remove/install flows, package search/details/version listing, ignored-update management, and package install/update/uninstall flows.
 
 <br><br>
 # `unigetui://` deep link

src/UniGetUI.Avalonia/Infrastructure/AvaloniaBootstrapper.cs

@@ -11,6 +11,7 @@
 using UniGetUI.Interface.Telemetry;
 using UniGetUI.PackageEngine;
 using UniGetUI.PackageEngine.Classes.Manager.Classes;
+using UniGetUI.PackageEngine.Interfaces;
 
 namespace UniGetUI.Avalonia.Infrastructure;
 
@@ -97,6 +98,14 @@ private static async Task InitializeBackgroundApiAsync()
                 return;
 
             _backgroundApi = new BackgroundApiRunner();
+            _backgroundApi.AppInfoProvider = () =>
+                Dispatcher.UIThread.InvokeAsync(GetAppInfo).GetAwaiter().GetResult();
+            _backgroundApi.ShowAppHandler = () =>
+                Dispatcher.UIThread.InvokeAsync(ShowApp).GetAwaiter().GetResult();
+            _backgroundApi.NavigateAppHandler = request =>
+                Dispatcher.UIThread.InvokeAsync(() => NavigateApp(request)).GetAwaiter().GetResult();
+            _backgroundApi.QuitAppHandler = () =>
+                Dispatcher.UIThread.InvokeAsync(QuitApp).GetAwaiter().GetResult();
 
             _backgroundApi.OnOpenWindow += (_, _) =>
                 Dispatcher.UIThread.Post(() => MainWindow.Instance?.ShowFromTray());
@@ -138,6 +147,111 @@ private static async Task InitializeBackgroundApiAsync()
 
     public static void StopBackgroundApi() => _backgroundApi?.Stop();
 
+    private static AutomationAppInfo GetAppInfo()
+    {
+        MainWindow? window = MainWindow.Instance;
+        return new AutomationAppInfo
+        {
+            Headless = false,
+            WindowAvailable = window is not null,
+            WindowVisible = window?.IsVisible ?? false,
+            CanShowWindow = window is not null,
+            CanNavigate = window is not null,
+            CanQuit = true,
+            CurrentPage = window is null ? "" : AutomationAppPages.ToPageName(window.CurrentPage.ToString()),
+            SupportedPages = AutomationAppPages.SupportedPages,
+        };
+    }
+
+    private static BackgroundApiCommandResult ShowApp()
+    {
+        MainWindow window = MainWindow.Instance
+            ?? throw new InvalidOperationException("The application window is not available.");
+        window.ShowFromTray();
+        return BackgroundApiCommandResult.Success("show-app");
+    }
+
+    private static BackgroundApiCommandResult NavigateApp(AutomationAppNavigateRequest request)
+    {
+        MainWindow window = MainWindow.Instance
+            ?? throw new InvalidOperationException("The application window is not available.");
+        string page = AutomationAppPages.NormalizePageName(request.Page);
+        var manager = ResolveManager(request.ManagerName);
+
+        switch (page)
+        {
+            case "discover":
+                window.Navigate(PageType.Discover);
+                break;
+            case "updates":
+                window.Navigate(PageType.Updates);
+                break;
+            case "installed":
+                window.Navigate(PageType.Installed);
+                break;
+            case "bundles":
+                window.Navigate(PageType.Bundles);
+                break;
+            case "settings":
+                window.Navigate(PageType.Settings);
+                break;
+            case "managers":
+                window.OpenManagerSettings(manager);
+                break;
+            case "own-log":
+                window.Navigate(PageType.OwnLog);
+                break;
+            case "manager-log":
+                window.OpenManagerLogs(manager);
+                break;
+            case "operation-history":
+                window.Navigate(PageType.OperationHistory);
+                break;
+            case "help":
+                window.ShowHelp(request.HelpAttachment ?? "");
+                break;
+            case "release-notes":
+                window.Navigate(PageType.ReleaseNotes);
+                break;
+            case "about":
+                window.Navigate(PageType.About);
+                break;
+            default:
+                throw new InvalidOperationException(
+                    $"Unsupported app page \"{request.Page}\"."
+                );
+        }
+
+        window.ShowFromTray();
+        return BackgroundApiCommandResult.Success("navigate-app");
+    }
+
+    private static BackgroundApiCommandResult QuitApp()
+    {
+        MainWindow window = MainWindow.Instance
+            ?? throw new InvalidOperationException("The application window is not available.");
+        _ = Task.Run(async () =>
+        {
+            await Task.Delay(150);
+            await Dispatcher.UIThread.InvokeAsync(window.QuitApplication);
+        });
+        return BackgroundApiCommandResult.Success("quit-app");
+    }
+
+    private static IPackageManager? ResolveManager(string? managerName)
+    {
+        if (string.IsNullOrWhiteSpace(managerName))
+        {
+            return null;
+        }
+
+        return PEInterface.Managers.FirstOrDefault(manager =>
+            manager.Name.Equals(managerName, StringComparison.OrdinalIgnoreCase))
+            ?? throw new InvalidOperationException(
+                $"Unknown manager \"{managerName}\"."
+            );
+    }
+
     private static async Task LoadElevatorAsync()
     {
         try

src/UniGetUI.Avalonia/Infrastructure/HeadlessDaemonHost.cs

@@ -10,14 +10,23 @@ public static async Task<int> RunAsync(string[] args)
     {
         BackgroundApiRunner? backgroundApi = null;
         using var shutdown = new CancellationTokenSource();
+        void RequestShutdown()
+        {
+            if (!shutdown.IsCancellationRequested)
+            {
+                shutdown.Cancel();
+            }
+        }
 
-        Console.CancelKeyPress += (_, eventArgs) =>
+        ConsoleCancelEventHandler cancelHandler = (_, eventArgs) =>
         {
             eventArgs.Cancel = true;
-            shutdown.Cancel();
+            RequestShutdown();
         };
+        Console.CancelKeyPress += cancelHandler;
 
-        AppDomain.CurrentDomain.ProcessExit += (_, _) => shutdown.Cancel();
+        EventHandler processExitHandler = (_, _) => RequestShutdown();
+        AppDomain.CurrentDomain.ProcessExit += processExitHandler;
 
         try
         {
@@ -28,6 +37,34 @@ public static async Task<int> RunAsync(string[] args)
             await Task.Run(PEInterface.LoadManagers);
 
             backgroundApi = new BackgroundApiRunner();
+            backgroundApi.AppInfoProvider = () =>
+                new AutomationAppInfo
+                {
+                    Headless = true,
+                    WindowAvailable = false,
+                    WindowVisible = false,
+                    CanShowWindow = false,
+                    CanNavigate = false,
+                    CanQuit = true,
+                    SupportedPages = AutomationAppPages.SupportedPages,
+                };
+            backgroundApi.ShowAppHandler = () =>
+                throw new InvalidOperationException(
+                    "The current UniGetUI session is running headless and has no window to show."
+                );
+            backgroundApi.NavigateAppHandler = _ =>
+                throw new InvalidOperationException(
+                    "The current UniGetUI session is running headless and cannot navigate UI pages."
+                );
+            backgroundApi.QuitAppHandler = () =>
+            {
+                _ = Task.Run(async () =>
+                {
+                    await Task.Delay(150);
+                    shutdown.Cancel();
+                });
+                return BackgroundApiCommandResult.Success("quit-app");
+            };
             await backgroundApi.Start();
 
             Logger.Info("UniGetUI headless daemon is ready");
@@ -42,6 +79,9 @@ public static async Task<int> RunAsync(string[] args)
         }
         finally
         {
+            AppDomain.CurrentDomain.ProcessExit -= processExitHandler;
+            Console.CancelKeyPress -= cancelHandler;
+
             if (backgroundApi is not null)
             {
                 await backgroundApi.Stop();

src/UniGetUI.Avalonia/Views/MainWindow.axaml.cs

@@ -9,6 +9,7 @@
 using UniGetUI.Core.Logging;
 using UniGetUI.Core.SettingsEngine;
 using UniGetUI.Core.Tools;
+using UniGetUI.PackageEngine.Interfaces;
 
 namespace UniGetUI.Avalonia.Views;
 
@@ -42,6 +43,7 @@ public enum RuntimeNotificationLevel
     public static MainWindow? Instance { get; private set; }
 
     private MainWindowViewModel ViewModel => (MainWindowViewModel)DataContext!;
+    public PageType CurrentPage => ViewModel.CurrentPage_t;
 
     public MainWindow()
     {
@@ -148,6 +150,10 @@ private void SearchBox_KeyDown(object? sender, KeyEventArgs e)
 
     // ─── Public navigation API ────────────────────────────────────────────────
     public void Navigate(PageType type) => ViewModel.NavigateTo(type);
+    public void OpenManagerLogs(IPackageManager? manager = null) => ViewModel.OpenManagerLogs(manager);
+    public void OpenManagerSettings(IPackageManager? manager = null) =>
+        ViewModel.OpenManagerSettings(manager);
+    public void ShowHelp(string uriAttachment = "") => ViewModel.ShowHelp(uriAttachment);
 
     // ─── Public API (legacy compat) ───────────────────────────────────────────
     public void ShowBanner(string title, string message, RuntimeNotificationLevel level)

src/UniGetUI.Interface.BackgroundApi/AutomationAppApi.cs

@@ -0,0 +1,89 @@
+namespace UniGetUI.Interface;
+
+public sealed class AutomationAppInfo
+{
+    public bool Headless { get; set; }
+    public bool WindowAvailable { get; set; }
+    public bool WindowVisible { get; set; }
+    public bool CanShowWindow { get; set; }
+    public bool CanNavigate { get; set; }
+    public bool CanQuit { get; set; }
+    public string CurrentPage { get; set; } = "";
+    public IReadOnlyList<string> SupportedPages { get; set; } = AutomationAppPages.SupportedPages;
+}
+
+public sealed class AutomationAppNavigateRequest
+{
+    public string Page { get; set; } = "";
+    public string? ManagerName { get; set; }
+    public string? HelpAttachment { get; set; }
+}
+
+public static class AutomationAppPages
+{
+    public static readonly IReadOnlyList<string> SupportedPages =
+    [
+        "discover",
+        "updates",
+        "installed",
+        "bundles",
+        "settings",
+        "managers",
+        "own-log",
+        "manager-log",
+        "operation-history",
+        "help",
+        "release-notes",
+        "about",
+    ];
+
+    public static string NormalizePageName(string page)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(page);
+
+        string normalized = page.Trim().ToLowerInvariant();
+        return normalized switch
+        {
+            "discover" => normalized,
+            "updates" => normalized,
+            "installed" => normalized,
+            "bundles" => normalized,
+            "settings" => normalized,
+            "managers" => normalized,
+            "own-log" => normalized,
+            "manager-log" => normalized,
+            "operation-history" => normalized,
+            "help" => normalized,
+            "release-notes" => normalized,
+            "about" => normalized,
+            _ => throw new InvalidOperationException(
+                $"Unsupported page \"{page}\". Supported pages: {string.Join(", ", SupportedPages)}."
+            ),
+        };
+    }
+
+    public static string ToPageName(string? pageTypeName)
+    {
+        if (string.IsNullOrWhiteSpace(pageTypeName))
+        {
+            return "";
+        }
+
+        return pageTypeName switch
+        {
+            "Discover" => "discover",
+            "Updates" => "updates",
+            "Installed" => "installed",
+            "Bundles" => "bundles",
+            "Settings" => "settings",
+            "Managers" => "managers",
+            "OwnLog" => "own-log",
+            "ManagerLog" => "manager-log",
+            "OperationHistory" => "operation-history",
+            "Help" => "help",
+            "ReleaseNotes" => "release-notes",
+            "About" => "about",
+            _ => pageTypeName.Trim(),
+        };
+    }
+}

src/UniGetUI.Interface.BackgroundApi/AutomationCliCommandRunner.cs

@@ -41,6 +41,20 @@ TextWriter error
             return subcommand switch
             {
                 "status" => await WriteJsonAsync(output, await client.GetStatusAsync()),
+                "get-app-state" => await WriteJsonAsync(
+                    output,
+                    new
+                    {
+                        status = "success",
+                        app = await client.GetAppInfoAsync(),
+                    }
+                ),
+                "show-app" => await WriteJsonAsync(output, await client.ShowAppAsync()),
+                "navigate-app" => await WriteJsonAsync(
+                    output,
+                    await client.NavigateAppAsync(BuildAppNavigateRequest(args))
+                ),
+                "quit-app" => await WriteJsonAsync(output, await client.QuitAppAsync()),
                 "list-managers" => await WriteJsonAsync(
                     output,
                     new
@@ -515,6 +529,20 @@ private static AutomationPackageActionRequest BuildPackageActionRequest(IReadOnl
         };
     }
 
+    private static AutomationAppNavigateRequest BuildAppNavigateRequest(IReadOnlyList<string> args)
+    {
+        return new AutomationAppNavigateRequest
+        {
+            Page = GetRequiredArgument(
+                args,
+                "--page",
+                "The navigate-app automation command requires --page."
+            ),
+            ManagerName = GetOptionalArgument(args, "--manager"),
+            HelpAttachment = GetOptionalArgument(args, "--help-attachment"),
+        };
+    }
+
     private static AutomationSourceRequest BuildSourceRequest(IReadOnlyList<string> args)
     {
         return new AutomationSourceRequest