@cats-inc/cats-platform 0.1.1 → 0.1.7

package/build/desktop/main.js

@@ -1,14 +1,16 @@
 import { dirname, join } from 'node:path';
-import { app, BrowserWindow, ipcMain, session, shell, systemPreferences } from 'electron';
+import { app, BrowserWindow, ipcMain, Notification, session, shell, systemPreferences, } from 'electron';
 import { buildDesktopBootstrapPage } from './bootstrapPage.js';
 import { resolveDesktopBootstrapNavigation, shouldRevealDesktopBootstrapRecovery, shouldNavigateDesktopBootstrap, resolveDesktopWindowRevealNavigation, shouldAllowDesktopBootstrapWindowNavigation, } from './bootstrapNavigation.js';
 import { resolveCatsHomeDir, resolveDesktopHostConfig, resolveDesktopUserDataDir, } from './config.js';
+import { DESKTOP_BROWSER_HANDOFF_OPEN_CHANNEL } from './contracts.js';
 import { appendHostEvent, appendRuntimeEvent, buildDesktopAggregationBundle, createBootstrapAttemptId, createDesktopBootstrapEvent, createEmptyDesktopDiagnosticsState, toDesktopBootstrapError, toDesktopBootstrapStatus, updateServiceLogs, } from './bootstrapDiagnostics.js';
-import { createDesktopBackgroundState, DesktopHostStateStore } from './hostState.js';
+import { createDesktopBackgroundState, DesktopHostStateStore, readPersistedUpdateLastCheckedAt, } from './hostState.js';
 import { createDesktopPackagingPlan } from './packaging.js';
 import { ManagedServiceSupervisor } from './processSupervisor.js';
 import { buildDesktopBootstrapSnapshot, fetchJson, } from './readiness.js';
-import { isDesktopHostActionId, validateDesktopUrl } from './security.js';
+import { isDesktopAppOriginUrl, isDesktopHostActionId, resolveDesktopBrowserHandoffUrl, validateDesktopUrl, } from './security.js';
+import { assertMainWindowIpcSender } from './ipcSecurity.js';
 import { readPersistedSetupCompletionState, } from './persistedSetupState.js';
 import { buildDesktopSetupSnapshot, createEmptyDesktopSetupState, runDesktopSetupHelper, shouldAutoRunSetupAudit, } from './setupBridge.js';
 import { isDesktopBootstrapLoadingPhase, resolveDesktopBootstrapError, shouldAttemptDesktopLateReadyRecovery, } from './startupRecovery.js';
@@ -18,7 +20,13 @@ import { createDesktopTrayController, } from './tray.js';
 import { buildDesktopTrayMenuState as buildElectronTrayMenuState, buildDesktopTrayQuittingMenuState, } from './trayMenu.js';
 import { applyDesktopHostPlatformShellUpdate, normalizePlatformShellSetupState, parseDesktopHostPlatformShellUpdate, } from './platformShellUpdate.js';
 import { enableDesktopMobilePairingEnv } from './mobilePairingEnv.js';
-import { checkForDesktopUpdates, createDefaultDesktopUpdateState } from './update.js';
+import { DESKTOP_APP_USER_MODEL_ID, DESKTOP_HOST_VERSION } from './hostVersion.js';
+import { loadDesktopReleaseDescriptor, resolveDesktopDistributionIdentity, } from './releaseDescriptor.js';
+import { createDesktopUpdateCapability, createDesktopUpdateManager, createUnavailableDesktopUpdateSnapshot, } from './updateManager.js';
+import { configureElectronUpdater, createElectronUpdaterAdapter, resolveAutoUpdaterExport, } from './updaterAdapter.js';
+import { createDesktopUpdateIpcHandlers, createDesktopUpdateSnapshotBroadcast, } from './updateIpc.js';
+import { withDesktopInstallHandoff } from './updateInstallHandoff.js';
+import { DESKTOP_UPDATE_SETTINGS_PATH, resolveDesktopUpdateAnnouncement, } from './updateNotifications.js';
 import { applyDesktopWindowChrome, resolveDesktopWindowChromeOptions, } from './windowChrome.js';
 import { resolveDesktopWindowIconPath } from './windowIcon.js';
 import { readDesktopStartupPreferences, resolveDesktopStartupLaunchContext, syncDesktopStartupPreferences, updateDesktopStartupPreferences, DESKTOP_LAUNCH_AT_LOGIN_ARG, } from './desktopStartup.js';
@@ -64,6 +72,8 @@ let trayController = null;
 let stateStore = null;
 let backgroundState = null;
 let updateState = null;
+let updateManager = null;
+let detachUpdateBroadcast = null;
 let packagingState = null;
 let setupState = null;
 let diagnosticsState = null;
@@ -229,16 +239,29 @@ function resolveAllowedAppHosts(config) {
     return Array.from(new Set([config.appHost, appBaseHost]));
 }
 function shouldAllowInAppNavigation(rawUrl, config) {
-    try {
-        const currentAppUrl = new URL(config.appBaseUrl);
-        const nextUrl = new URL(validateDesktopUrl(rawUrl, {
-            allowedHosts: resolveAllowedAppHosts(config),
-        }));
-        return nextUrl.origin === currentAppUrl.origin;
-    }
-    catch {
-        return false;
-    }
+    return isDesktopAppOriginUrl(rawUrl, {
+        appBaseUrl: config.appBaseUrl,
+        allowedHosts: resolveAllowedAppHosts(config),
+    });
+}
+function configureDesktopWindowNavigation(window, config) {
+    window.webContents.setWindowOpenHandler(({ url }) => {
+        if (shouldAllowInAppNavigation(url, config)) {
+            return { action: 'allow' };
+        }
+        void openExternalDesktopUrl(url).catch(reportExternalUrlOpenFailure);
+        return { action: 'deny' };
+    });
+    window.webContents.on('will-navigate', (event, url) => {
+        if (shouldAllowInAppNavigation(url, config)) {
+            return;
+        }
+        event.preventDefault();
+        void openExternalDesktopUrl(url).catch(reportExternalUrlOpenFailure);
+    });
+    window.webContents.on('did-create-window', (childWindow) => {
+        configureDesktopWindowNavigation(childWindow, config);
+    });
 }
 async function ensureBootstrapPageVisible() {
     if (!mainWindow) {
@@ -582,6 +605,7 @@ function resolveDesktopTrayMenuState(snapshot) {
         actions: snapshot.actions,
         products: latestAppShellPayload?.products,
         locale: app.getLocale(),
+        updates: updateState,
     });
 }
 function isSystemTrayEnabled() {
@@ -707,6 +731,14 @@ function buildTrayControllerOptions() {
             void shutdownHost();
         },
         canInteract: () => !shuttingDown,
+        onCheckForUpdates: async () => {
+            if (shuttingDown) {
+                return;
+            }
+            // The menu closes on click, so this result has to reach the user through
+            // a notification or by opening Settings.
+            await refreshUpdateState('tray');
+        },
     };
 }
 async function syncTrayController() {
@@ -1197,24 +1229,151 @@ async function maybeRecoverFromLateReadyStateChange() {
     })();
     await lateReadyRecoveryPromise;
 }
-async function refreshUpdateState() {
-    if (!hostConfig) {
-        throw new Error('Desktop host is not initialized.');
+/**
+ * Builds the update manager for this launch.
+ *
+ * Capability is derived from the embedded release descriptor plus the running
+ * package, never from the environment. When the build is not an official
+ * release the adapter is omitted entirely, so no provider is ever configured.
+ */
+async function createUpdateManagerForLaunch(config, initialLastCheckedAt = null) {
+    const descriptor = await loadDesktopReleaseDescriptor();
+    const identity = resolveDesktopDistributionIdentity({
+        isPackaged: config.packaged,
+        currentVersion: DESKTOP_HOST_VERSION,
+        nodePlatform: process.platform,
+        descriptor,
+    });
+    const capability = createDesktopUpdateCapability({
+        identity,
+        nodePlatform: process.platform,
+    });
+    let adapter = null;
+    if (capability.canCheck && identity.repository !== null) {
+        // Self-update is a feature, not a startup requirement. If the provider
+        // cannot be constructed the app must still open with update capability
+        // switched off, rather than failing to launch at all.
+        try {
+            const autoUpdater = resolveAutoUpdaterExport(await import('electron-updater'));
+            configureElectronUpdater(autoUpdater, {
+                repository: identity.repository,
+                channel: capability.channel,
+                distribution: capability.distribution,
+            });
+            adapter = withDesktopInstallHandoff(createElectronUpdaterAdapter(autoUpdater), {
+                drainManagedServices: async () => {
+                    // The tray says "Quitting" for the same reason shutdown does: from
+                    // here the app is on its way out, and a menu offering to open Cats
+                    // would be a lie while the sidecars are stopping. This also locks the
+                    // menu against repeated interaction without touching `shuttingDown`,
+                    // which gates far more behaviour and is never designed to be reset.
+                    trayController?.updateMenu(buildDesktopTrayQuittingMenuState(app.getLocale()));
+                    await drainManagedServices();
+                    // electron-updater quits the app itself. Without this the before-quit
+                    // handler would cancel that quit and run a second drain, delaying the
+                    // exit the installer is waiting on. The drain above already satisfied
+                    // the contract that flag stands for.
+                    exitingAfterShutdown = true;
+                },
+                restartManagedServices: async () => {
+                    // The handoff failed but the process survived, so the exit is no
+                    // longer prepared, the sidecars have to come back, and the tray has to
+                    // stop claiming we are quitting. startAll() intentionally reuses the
+                    // supervisor-lifetime environment snapshot populated during the first
+                    // bootstrap, including the Desktop-provisioned platform auth secret.
+                    exitingAfterShutdown = false;
+                    await supervisor?.startAll();
+                    await syncTrayController();
+                },
+                logger: (message) => {
+                    process.stdout.write(`${message}\n`);
+                },
+            });
+        }
+        catch (error) {
+            process.stderr.write('[desktop-update] updater unavailable, continuing without self-update: '
+                + `${error instanceof Error ? error.message : String(error)}\n`);
+            adapter = null;
+        }
     }
-    updateState = {
-        ...(updateState ?? createDefaultDesktopUpdateState(hostConfig.update)),
-        status: hostConfig.update.manifestUrl ? 'checking' : 'disabled',
-        summary: hostConfig.update.manifestUrl
-            ? 'Checking for desktop updates.'
-            : 'Update checks are disabled until a manifest URL is configured.',
-    };
-    if (latestSnapshot) {
-        publishSnapshot(latestSnapshot);
+    return createDesktopUpdateManager({
+        capability,
+        adapter,
+        initialLastCheckedAt,
+        logger: (message) => {
+            process.stdout.write(`${message}\n`);
+        },
+    });
+}
+async function openDesktopUpdateSettings() {
+    if (shuttingDown || !hostConfig) {
+        return;
     }
-    updateState = await checkForDesktopUpdates(hostConfig.update);
-    if (latestSnapshot) {
-        publishSnapshot(latestSnapshot);
+    await showMainWindow(`${hostConfig.appBaseUrl}${DESKTOP_UPDATE_SETTINGS_PATH}`);
+}
+/**
+ * Shows a native notification, reporting whether the user will actually see it.
+ *
+ * A false return sends the caller to the navigation fallback. Notifying is not
+ * worth failing a check over, so a throwing platform is treated the same as one
+ * without notification support.
+ */
+function showDesktopUpdateNotification(notification) {
+    try {
+        const native = new Notification({
+            title: notification.title,
+            body: notification.body,
+        });
+        native.on('click', () => {
+            void openDesktopUpdateSettings();
+        });
+        native.show();
+        return true;
+    }
+    catch (error) {
+        process.stderr.write('[desktop-update] native notification unavailable: '
+            + `${error instanceof Error ? error.message : String(error)}\n`);
+        return false;
+    }
+}
+function areNativeNotificationsSupported() {
+    try {
+        return Notification.isSupported();
+    }
+    catch {
+        return false;
+    }
+}
+async function announceDesktopUpdateResult(origin, snapshot) {
+    if (!snapshot || shuttingDown) {
+        return;
+    }
+    const announcement = resolveDesktopUpdateAnnouncement({
+        origin,
+        snapshot,
+        locale: app.getLocale(),
+        notificationsSupported: areNativeNotificationsSupported(),
+    });
+    if (announcement.notification && showDesktopUpdateNotification(announcement.notification)) {
+        return;
+    }
+    if (announcement.fallbackNavigatePath) {
+        await openDesktopUpdateSettings();
     }
+}
+/**
+ * Runs a check and reports its result to whoever asked for it.
+ *
+ * The origin is required rather than defaulted: it decides whether the result
+ * is announced at all, and a new caller silently inheriting another surface's
+ * policy is the failure this signature exists to prevent.
+ */
+async function refreshUpdateState(origin) {
+    if (!updateManager) {
+        return null;
+    }
+    updateState = await updateManager.checkForUpdates();
+    await announceDesktopUpdateResult(origin, updateState);
     return updateState;
 }
 async function bootstrapDesktopHost(restartServices = false) {
@@ -1448,17 +1607,7 @@ async function createMainWindow(config, options) {
             sandbox: true,
         },
     });
-    window.webContents.setWindowOpenHandler(({ url }) => {
-        void openExternalDesktopUrl(url).catch(reportExternalUrlOpenFailure);
-        return { action: 'deny' };
-    });
-    window.webContents.on('will-navigate', (event, url) => {
-        if (shouldAllowInAppNavigation(url, config)) {
-            return;
-        }
-        event.preventDefault();
-        void openExternalDesktopUrl(url).catch(reportExternalUrlOpenFailure);
-    });
+    configureDesktopWindowNavigation(window, config);
     applyDesktopWindowChrome(window);
     const showBootstrapWindow = () => {
         if (!options.showWindowOnStartup || window.isDestroyed() || window.isVisible()) {
@@ -1488,6 +1637,33 @@ function waitForShutdownDeadline(ms) {
         timer.unref?.();
     });
 }
+/**
+ * Stops managed services, forcing them down if the graceful path overruns.
+ *
+ * Shared by host shutdown and the update installer handoff, because both need
+ * the sidecars actually gone — the installer for the same reason the exit path
+ * does, plus the Windows upgrade running the old uninstaller over files a
+ * surviving sidecar may still hold.
+ */
+async function drainManagedServices() {
+    const drain = supervisor?.stopAll() ?? Promise.resolve();
+    const shutdownWatchdogMs = hostConfig
+        ? resolveShutdownWatchdogMs(hostConfig, supervisor?.getManagedServiceCount() ?? 0)
+        : SHUTDOWN_WATCHDOG_BUFFER_MS;
+    const result = await Promise.race([
+        drain.then(() => 'drained'),
+        waitForShutdownDeadline(shutdownWatchdogMs),
+    ]);
+    if (result !== 'timed_out') {
+        return { timedOut: false };
+    }
+    process.stderr.write(`Desktop host shutdown watchdog tripped after ${shutdownWatchdogMs}ms; forcing managed services down.\n`);
+    await supervisor?.forceStopAll();
+    void drain.catch((error) => {
+        process.stderr.write(`Desktop host graceful shutdown failed after watchdog: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+    });
+    return { timedOut: true };
+}
 async function shutdownHost() {
     if (shutdownPromise) {
         return shutdownPromise;
@@ -1502,22 +1678,10 @@ async function shutdownHost() {
             voiceCaptureController?.dispose();
             voiceCaptureController = null;
             activeTrayController?.updateMenu(buildDesktopTrayQuittingMenuState(app.getLocale()));
-            const drain = supervisor?.stopAll() ?? Promise.resolve();
-            const shutdownWatchdogMs = hostConfig
-                ? resolveShutdownWatchdogMs(hostConfig, supervisor?.getManagedServiceCount() ?? 0)
-                : SHUTDOWN_WATCHDOG_BUFFER_MS;
-            const result = await Promise.race([
-                drain.then(() => 'drained'),
-                waitForShutdownDeadline(shutdownWatchdogMs),
-            ]);
-            if (result === 'timed_out') {
+            const { timedOut } = await drainManagedServices();
+            if (timedOut) {
                 shutdownExitCode = 1;
-                process.stderr.write(`Desktop host shutdown watchdog tripped after ${shutdownWatchdogMs}ms; forcing managed services down.\n`);
                 forcedStopAttempted = true;
-                await supervisor?.forceStopAll();
-                void drain.catch((error) => {
-                    process.stderr.write(`Desktop host graceful shutdown failed after watchdog: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
-                });
             }
         }
         catch (error) {
@@ -1551,6 +1715,14 @@ async function main() {
         return;
     }
     app.setPath('userData', resolveDesktopUserDataDir(app.getPath('appData')));
+    // Windows routes a notification through the Start Menu shortcut whose
+    // Application User Model ID matches the running process. The installer writes
+    // that shortcut with the electron-builder appId, so claiming it here is what
+    // makes update notifications visible at all. Unpackaged runs have no such
+    // shortcut, so the claim would buy nothing.
+    if (process.platform === 'win32' && app.isPackaged && DESKTOP_APP_USER_MODEL_ID) {
+        app.setAppUserModelId(DESKTOP_APP_USER_MODEL_ID);
+    }
     await app.whenReady();
     const nodeProcess = process;
     hostConfig = resolveDesktopHostConfig({
@@ -1580,12 +1752,14 @@ async function main() {
     stateStore = new DesktopHostStateStore(hostConfig.paths.hostStatePath);
     {
         const defaultBackground = applyEffectiveBackgroundPreferences(createDesktopBackgroundState(hostConfig));
-        const defaultUpdates = createDefaultDesktopUpdateState(hostConfig.update);
+        // Built once with no restored history so the state file can be read; the
+        // manager is rebuilt below with the restored last-check time.
+        const provisionalUpdates = createUnavailableDesktopUpdateSnapshot(DESKTOP_HOST_VERSION);
         const defaultPackaging = buildHostPackagingPlan(hostConfig);
         const defaultSetup = createEmptyDesktopSetupState();
         const restoredState = await stateStore.load(hostConfig, {
             background: defaultBackground,
-            updates: defaultUpdates,
+            updates: provisionalUpdates,
             packaging: defaultPackaging,
             setup: defaultSetup,
         });
@@ -1598,7 +1772,21 @@ async function main() {
                 lastHiddenAt: new Date().toISOString(),
             };
         }
-        updateState = restoredState?.updates ?? defaultUpdates;
+        // One owner: the manager holds update state and the host snapshot mirrors
+        // it. Only the last-check time crosses a restart, because every status is
+        // provider-dependent and cannot be acted on without checking again.
+        updateManager = await createUpdateManagerForLaunch(hostConfig, readPersistedUpdateLastCheckedAt(restoredState?.updates));
+        updateState = updateManager.getSnapshot();
+        detachUpdateBroadcast = createDesktopUpdateSnapshotBroadcast({
+            manager: updateManager,
+            resolveMainWindowWebContents: () => mainWindow?.webContents ?? null,
+        });
+        updateManager.subscribe((snapshot) => {
+            updateState = snapshot;
+            if (latestSnapshot) {
+                publishSnapshot(latestSnapshot);
+            }
+        });
         packagingState = defaultPackaging;
         setupState = normalizePlatformShellSetupState(restoredState?.setup ?? defaultSetup, Boolean(latestPersistedSetupState.setupCompleteAt
             || latestPersistedSetupState.productSetupCompleted));
@@ -1626,6 +1814,18 @@ async function main() {
     ipcMain.handle('cats-host:get-snapshot', async () => {
         return latestSnapshot ?? buildSnapshot(null);
     });
+    if (updateManager) {
+        const updateHandlers = createDesktopUpdateIpcHandlers({
+            manager: updateManager,
+            resolveMainWindowWebContents: () => mainWindow?.webContents ?? null,
+            logger: (message) => {
+                process.stdout.write(`${message}\n`);
+            },
+        });
+        for (const [channel, handler] of Object.entries(updateHandlers)) {
+            ipcMain.handle(channel, async (event) => handler(event));
+        }
+    }
     ipcMain.handle('cats-host:get-setup-snapshot', async () => {
         return await getSetupSnapshot();
     });
@@ -1663,6 +1863,17 @@ async function main() {
     ipcMain.handle('cats-host:resume-setup', async () => {
         return await resumeSetupAction();
     });
+    ipcMain.handle(DESKTOP_BROWSER_HANDOFF_OPEN_CHANNEL, async (event, launchPath) => {
+        assertMainWindowIpcSender(event, mainWindow, 'Browser handoff is only available to the main Cats window.');
+        if (!hostConfig || typeof launchPath !== 'string') {
+            throw new Error('Desktop browser handoff is not initialized.');
+        }
+        const url = resolveDesktopBrowserHandoffUrl(launchPath, {
+            appBaseUrl: hostConfig.appBaseUrl,
+            allowedHosts: resolveAllowedAppHosts(hostConfig),
+        });
+        await openExternalDesktopUrl(url);
+    });
     ipcMain.handle(DESKTOP_SCREENSHOT_IPC_CHANNEL, async (event, payload) => {
         assertMainWindowScreenshotIpcSender(event, mainWindow);
         return await captureScreenshotRegion({
@@ -1808,8 +2019,10 @@ async function main() {
         void showMainWindow();
     });
     await bootstrapDesktopHost(false);
-    if (hostConfig.update.checkOnStartup && hostConfig.update.manifestUrl) {
-        void refreshUpdateState();
+    // SPEC-111 section 6: at most one silent check per launch, and only when the
+    // build actually has update capability.
+    if (hostConfig.update.checkOnStartup && updateManager?.getSnapshot().capability.canCheck) {
+        void refreshUpdateState('startup');
     }
 }
 void main().catch((error) => {