Makes long-running Apps tool APIs run properly in background (BL-16350)

Several Apps tool APIs, especially Build, were made to kick off a background task and then return; task completion signaled by websocket.
Enhanced so if you return to the tool and build is still running, it gets back into a state indicating the progress of the build.
Also, Build is now more appropriately enabled; you don't have to do Customize first if all the required settings are already known.

Author: JohnThomson

src/BloomBrowserUI/publish/Apps/AppPublisherScreen.tsx

@@ -460,11 +460,7 @@ const AppPublisherScreenContents: React.FunctionComponent<{
                         <Step expanded={true} completed={false}>
                             <StepLabel>
                                 <AppActionButton
-                                    enabled={
-                                        prepareIsReady &&
-                                        buildIsNeeded &&
-                                        canRunBuild
-                                    }
+                                    enabled={prepareIsReady && canRunBuild}
                                     l10nKey="PublishTab.Apps.Build"
                                     onClick={() =>
                                         screenState.runAction("build")

src/BloomBrowserUI/publish/Apps/appBuilderShared.ts

@@ -34,6 +34,12 @@ export interface IAppBuilderStatus {
     rabRoot?: string;
     trackedBookTitles?: string[];
     trackedBooks: IAppBuilderTrackedBook[];
+    /** The action currently running on the server, or undefined if idle. */
+    activeAction?: AppBuilderAction;
+    /** Last progress stage reported by the server (e.g. "building-android-app"). */
+    activeActionProgressStage?: string;
+    /** Last progress percent (0–100) reported by the server. */
+    activeActionProgressPercent?: number;
 }
 
 export type AppBuilderPrepareStepId =
@@ -74,6 +80,12 @@ export interface IAppBuilderStatusApi {
     apkSizeBytes?: number;
     rabRoot?: string;
     trackedBookTitles?: string[];
+    activeAction?: string;
+    activeActionProgressStage?: string;
+    activeActionProgressPercent?: number;
+    ActiveAction?: string;
+    ActiveActionProgressStage?: string;
+    ActiveActionProgressPercent?: number;
     RabInstalled?: boolean;
     ProjectExists?: boolean;
     ApkExists?: boolean;
@@ -129,6 +141,10 @@ export interface IProgressStageLabels {
 
 export const kAppBuilderWebSocketContext = "publish-rab";
 
+/// Websocket event id sent by the C# side when a prepare/build/install completes.
+/// The message payload is "{action}:success" or "{action}:failure".
+export const kAppBuilderActionCompleteEventId = "actionComplete";
+
 export type AppBuilderAction = "prepare" | "build" | "install";
 
 export const defaultStatus: IAppBuilderStatus = {
@@ -209,6 +225,16 @@ export function normalizeStatus(
         getDefaultPrepareSteps()
     ).map(normalizePrepareStepStatus);
 
+    const rawActiveAction =
+        status?.activeAction ?? status?.ActiveAction ?? undefined;
+    const rawProgressStage =
+        status?.activeActionProgressStage ??
+        status?.ActiveActionProgressStage ??
+        undefined;
+    const rawProgressPercent =
+        status?.activeActionProgressPercent ??
+        status?.ActiveActionProgressPercent ??
+        undefined;
     return {
         rabInstalled: status?.rabInstalled ?? status?.RabInstalled ?? false,
         projectExists: status?.projectExists ?? status?.ProjectExists ?? false,
@@ -230,6 +256,9 @@ export function normalizeStatus(
         trackedBooks: (status?.trackedBooks ?? status?.TrackedBooks ?? []).map(
             normalizeTrackedBook,
         ),
+        activeAction: rawActiveAction as AppBuilderAction | undefined,
+        activeActionProgressStage: rawProgressStage,
+        activeActionProgressPercent: rawProgressPercent,
     };
 }
 

src/BloomBrowserUI/publish/Apps/useAppBuilderPublisherScreen.ts

@@ -1,5 +1,11 @@
 import * as React from "react";
-import { get, getWithPromise, postData, postJson } from "../../utils/bloomApi";
+import {
+    get,
+    getWithPromise,
+    post,
+    postData,
+    postJson,
+} from "../../utils/bloomApi";
 import {
     IBloomWebSocketProgressEvent,
     useSubscribeToWebSocketForEvent,
@@ -16,6 +22,7 @@ import {
     IAppBuilderStatusApi,
     IAppBuilderSizeEstimatesApi,
     kAppBuilderWebSocketContext,
+    kAppBuilderActionCompleteEventId,
     normalizeSizeEstimates,
     normalizeStatus,
     AppBuilderAction,
@@ -158,6 +165,27 @@ export function useAppBuilderPublisherScreen(
                 statusRetryTimeoutRef.current = undefined;
             }
             setStatus(nextStatus);
+            // If the backend reports an action is running but we have no local busyAction
+            // (e.g. after a remount mid-build), restore the action and its last-known progress
+            // so the indicator appears immediately without waiting for a websocket event.
+            if (nextStatus.activeAction) {
+                const isRestoringFromBlank = !busyActionRef.current;
+                setBusyAction(
+                    (current) =>
+                        current ??
+                        (nextStatus.activeAction as AppBuilderAction),
+                );
+                if (isRestoringFromBlank) {
+                    if (nextStatus.activeActionProgressStage) {
+                        setProgressStageCode(
+                            nextStatus.activeActionProgressStage,
+                        );
+                    }
+                    setProgressPercent(
+                        nextStatus.activeActionProgressPercent ?? 0,
+                    );
+                }
+            }
 
             if (initializeSettingsAfterPrepare && nextStatus.appDefPath) {
                 const initializedSettings = await initializeAppBuilderSettings(
@@ -198,18 +226,73 @@ export function useAppBuilderPublisherScreen(
         }
     }
 
-    // This effect is warranted because tab activation is an external UI lifecycle boundary,
-    // and we need to reset the ephemeral BloomPUB cache plus re-read the RAB project whenever the Apps screen becomes active.
+    // Track busyAction in a ref so async callbacks can read the latest value
+    // without closing over a stale render's state.
+    const busyActionRef = React.useRef(busyAction);
+    busyActionRef.current = busyAction;
+
+    // This effect is warranted because tab activation is an external UI lifecycle boundary.
+    // We fetch status first so any active build, its current stage, and its progress are
+    // shown immediately — without waiting for the next websocket event — and so we know
+    // whether it's safe to reset the ephemeral BloomPUB cache.
     React.useEffect(() => {
         if (!isActive) {
             return;
         }
 
-        void postData("publish/rab/reset-bloompub-cache", {}).then(() => {
+        void (async () => {
+            // Snapshot the current server state right away.
+            let activeActionFromServer: AppBuilderAction | undefined;
+            try {
+                const nextStatus = await fetchStatusAsync();
+                if (!isMountedRef.current) {
+                    return;
+                }
+                setStatus(nextStatus);
+                activeActionFromServer = nextStatus.activeAction;
+                if (activeActionFromServer) {
+                    setBusyAction(
+                        (current) => current ?? activeActionFromServer!,
+                    );
+                    // Restore the last-known stage and progress so the indicator
+                    // appears immediately rather than waiting for the next websocket event.
+                    if (nextStatus.activeActionProgressStage) {
+                        setProgressStageCode(
+                            nextStatus.activeActionProgressStage,
+                        );
+                    }
+                    setProgressPercent(
+                        nextStatus.activeActionProgressPercent ?? 0,
+                    );
+                }
+                void refreshSettings(nextStatus.appDefPath);
+            } catch {
+                // Status fetch failed; fall through to the cache-reset path which
+                // will call refreshStatus() for its own retry handling.
+            }
+
+            if (!isMountedRef.current) {
+                return;
+            }
+            refreshSizeEstimates();
+
+            if (activeActionFromServer) {
+                // A background action is running — skip the cache reset to avoid
+                // deleting BloomPUBs the build is actively using.
+                return;
+            }
+
+            // No active action: clear the stale per-session BloomPUB cache, then
+            // do a full status refresh to pick up any changes since the last visit.
+            await postData("publish/rab/reset-bloompub-cache", {});
+            if (!isMountedRef.current) {
+                return;
+            }
             void refreshStatus();
             refreshSizeEstimates();
-        });
-        // refreshStatus and refreshSizeEstimates are intentionally omitted so this only reruns when the tab activation boundary changes.
+        })();
+        // fetchStatusAsync, refreshSettings, refreshSizeEstimates, and refreshStatus
+        // are intentionally omitted — this only reruns at the tab-activation boundary.
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [isActive]);
 
@@ -298,18 +381,35 @@ export function useAppBuilderPublisherScreen(
                     : undefined,
         );
         setBusyAction(action);
-        postData(
-            `publish/rab/${action}`,
-            {},
-            () => {
-                void handleActionCompleted(action, action === "prepare");
-            },
-            () => {
-                void handleActionCompleted(action, false);
-            },
-        );
+        // The endpoint returns immediately; actual completion arrives via the
+        // "actionComplete" websocket event handled by the subscription below.
+        post(`publish/rab/${action}`);
     }
 
+    // Listen for background-task completion from the server.
+    // useWebSocketListener keeps the callback reference current on every render
+    // so handleActionCompleted always has a fresh closure.
+    useSubscribeToWebSocketForStringMessage(
+        kAppBuilderWebSocketContext,
+        kAppBuilderActionCompleteEventId,
+        (result) => {
+            const separatorIndex = result.indexOf(":");
+            if (separatorIndex < 0) {
+                return;
+            }
+            const completedAction = result.substring(
+                0,
+                separatorIndex,
+            ) as AppBuilderAction;
+            const succeeded =
+                result.substring(separatorIndex + 1) === "success";
+            void handleActionCompleted(
+                completedAction,
+                completedAction === "prepare" && succeeded,
+            );
+        },
+    );
+
     function showApkInExplorerInShell(): void {
         if (!status.apkPath) {
             return;

src/BloomBrowserUI/react_components/requiresSubscription.tsx

@@ -165,7 +165,7 @@ export const RequiresSubscriptionOverlayWrapper: React.FunctionComponent<{
             >
                 {props.children}
             </div>
-            {featureStatus?.enabled || (
+            {featureStatus === undefined || featureStatus.enabled || (
                 <div
                     css={css`
                         position: absolute;

src/BloomExe/Publish/Rab/RabProjectModels.cs

@@ -28,6 +28,26 @@ public class RabProjectStatus
         public RabTrackedBookInfo[] TrackedBooks { get; set; } = Array.Empty<RabTrackedBookInfo>();
         public RabPrepareStepStatus[] PrepareSteps { get; set; } =
             Array.Empty<RabPrepareStepStatus>();
+
+        /// <summary>
+        /// The action currently running ("prepare", "build", or "install"), or null if idle.
+        /// Lets the UI restore its busy indicator when switching back to the Apps tab mid-action.
+        /// </summary>
+        public string ActiveAction { get; set; }
+
+        /// <summary>
+        /// The most-recently reported progress stage code for the active action (e.g.
+        /// "building-android-app"), or null when idle.  Sent with the status so the UI can
+        /// show the correct stage label immediately on tab re-activation, without waiting for
+        /// the next websocket progress event.
+        /// </summary>
+        public string ActiveActionProgressStage { get; set; }
+
+        /// <summary>
+        /// The most-recently reported progress percentage (0–100) for the active action, or
+        /// 0 when idle.  Paired with <see cref="ActiveActionProgressStage"/> for the same reason.
+        /// </summary>
+        public int ActiveActionProgressPercent { get; set; }
     }
 
     /// <summary>

src/BloomExe/Publish/Rab/RabProjectService.cs

@@ -80,7 +80,7 @@ string packageSegment
         private readonly CollectionSettings _collectionSettings;
         private readonly BloomWebSocketServer _webSocketServer;
         private readonly IWebSocketProgress _progress;
-        private string _activeProgressAction;
+        private volatile string _activeProgressAction;
         private int _lastBuildProgressPercent;
         private string _lastLoggedProgressStage;
         private int? _lastLoggedProgressPercent;
@@ -379,6 +379,11 @@ public RabProjectStatus GetStatus()
                 TrackedBooks = trackedBooks,
                 TrackedBookTitles = trackedBooks.Select(book => book.Title).ToArray(),
                 PrepareSteps = prepareSteps,
+                ActiveAction = _activeProgressAction,
+                ActiveActionProgressStage =
+                    _activeProgressAction != null ? _lastLoggedProgressStage : null,
+                ActiveActionProgressPercent =
+                    _activeProgressAction != null ? (_lastLoggedProgressPercent ?? 0) : 0,
             };
 
             if (status.ProjectExists)
@@ -432,6 +437,19 @@ public RabAppSizeEstimates GetSizeEstimates()
             };
         }
 
+        /// <summary>
+        /// Sends an "actionComplete" websocket event so the Apps screen knows when a background
+        /// prepare/build/install has finished.  Called from the finally block of each action.
+        /// </summary>
+        private void SendActionCompleteEvent(string action, bool succeeded)
+        {
+            _webSocketServer.SendString(
+                kWebSocketContext,
+                RabPublishApi.kWebSocketEventId_ActionComplete,
+                $"{action}:{(succeeded ? "success" : "failure")}"
+            );
+        }
+
         /// <summary>
         /// Reports an App Builder failure to Bloom's log and the progress channel used by the Apps screen.
         /// </summary>
@@ -450,6 +468,7 @@ private void Prepare()
         {
             var paths = GetPaths();
             _activeProgressAction = "prepare";
+            var succeeded = false;
             try
             {
                 ReportProgressStage("checking-installer", 0);
@@ -544,10 +563,12 @@ private void Prepare()
                 ReportProgressStage("complete", 100);
                 _progress.MessageWithoutLocalizing("Prepare complete.", ProgressKind.Heading);
                 _progress.MessageWithoutLocalizing($"Project file: {existingProjectPath}");
+                succeeded = true;
             }
             finally
             {
                 _activeProgressAction = null;
+                SendActionCompleteEvent("prepare", succeeded);
             }
         }
 
@@ -655,6 +676,7 @@ private void Build()
             EnsureWorkspaceFolders(paths);
             _activeProgressAction = "build";
             _lastBuildProgressPercent = 0;
+            var succeeded = false;
             try
             {
                 ReportProgressStage("preparing-build", 0);
@@ -735,10 +757,12 @@ private void Build()
                 );
                 state.LastBuiltApkPath = apkPath;
                 SaveState(paths, state);
+                succeeded = true;
             }
             finally
             {
                 _activeProgressAction = null;
+                SendActionCompleteEvent("build", succeeded);
             }
         }
 
@@ -747,6 +771,7 @@ private void Install()
             // Install re-reads package/app metadata from the project so launching uses the same identity that was built.
             var paths = GetPaths();
             _activeProgressAction = "install";
+            var succeeded = false;
             try
             {
                 var apkPath = FindLatestApkPath(paths);
@@ -825,10 +850,12 @@ private void Install()
                     $"Install complete. Opened {appName} on {device.DisplayName}.",
                     ProgressKind.Heading
                 );
+                succeeded = true;
             }
             finally
             {
                 _activeProgressAction = null;
+                SendActionCompleteEvent("install", succeeded);
             }
         }