@cats-inc/cats-platform 0.1.1 → 0.1.5

package/build/desktop/updateIpc.js

@@ -0,0 +1,71 @@
+import { DESKTOP_UPDATE_CHECK_CHANNEL, DESKTOP_UPDATE_DOWNLOAD_CHANNEL, DESKTOP_UPDATE_EVENT_CHANNEL, DESKTOP_UPDATE_INSTALL_CHANNEL, DESKTOP_UPDATE_SNAPSHOT_CHANNEL, } from './contracts.js';
+/**
+ * Bounded IPC surface for the host-owned update manager.
+ *
+ * SPEC-111 section 3: every command takes no arguments, so a renderer cannot
+ * supply a feed URL, filesystem destination, shell command, executable path, or
+ * installer flag. Every handler also verifies the sender is the current Cats
+ * main window before touching the manager.
+ */
+export const DESKTOP_UPDATE_IPC_CHANNELS = {
+    snapshot: DESKTOP_UPDATE_SNAPSHOT_CHANNEL,
+    check: DESKTOP_UPDATE_CHECK_CHANNEL,
+    download: DESKTOP_UPDATE_DOWNLOAD_CHANNEL,
+    install: DESKTOP_UPDATE_INSTALL_CHANNEL,
+    event: DESKTOP_UPDATE_EVENT_CHANNEL,
+};
+export function isDesktopUpdateIpcSenderTrusted(event, mainWindowWebContents) {
+    if (mainWindowWebContents === null || mainWindowWebContents === undefined) {
+        return false;
+    }
+    return event.sender === mainWindowWebContents;
+}
+export function createDesktopUpdateIpcHandlers(input) {
+    const { manager, resolveMainWindowWebContents } = input;
+    const logger = input.logger ?? (() => { });
+    function assertTrusted(event, channel) {
+        if (isDesktopUpdateIpcSenderTrusted(event, resolveMainWindowWebContents())) {
+            return;
+        }
+        logger(`[desktop-update] rejected ${channel} from an untrusted sender.`);
+        // Deliberately generic: the renderer learns the command was refused and
+        // nothing about the host window topology.
+        throw new Error('Update command rejected.');
+    }
+    return {
+        [DESKTOP_UPDATE_IPC_CHANNELS.snapshot]: async (event) => {
+            assertTrusted(event, DESKTOP_UPDATE_IPC_CHANNELS.snapshot);
+            return manager.getSnapshot();
+        },
+        [DESKTOP_UPDATE_IPC_CHANNELS.check]: async (event) => {
+            assertTrusted(event, DESKTOP_UPDATE_IPC_CHANNELS.check);
+            return manager.checkForUpdates();
+        },
+        [DESKTOP_UPDATE_IPC_CHANNELS.download]: async (event) => {
+            assertTrusted(event, DESKTOP_UPDATE_IPC_CHANNELS.download);
+            return manager.downloadUpdate();
+        },
+        [DESKTOP_UPDATE_IPC_CHANNELS.install]: async (event) => {
+            assertTrusted(event, DESKTOP_UPDATE_IPC_CHANNELS.install);
+            await manager.restartAndInstall();
+        },
+    };
+}
+/**
+ * Streams manager snapshots to the main window. Returns the unsubscribe
+ * function so the caller can detach deterministically during shutdown.
+ */
+export function createDesktopUpdateSnapshotBroadcast(input) {
+    const { manager, resolveMainWindowWebContents } = input;
+    return manager.subscribe((snapshot) => {
+        const webContents = resolveMainWindowWebContents();
+        if (webContents === null || webContents === undefined) {
+            return;
+        }
+        if (webContents.isDestroyed?.() === true) {
+            return;
+        }
+        webContents.send(DESKTOP_UPDATE_IPC_CHANNELS.event, snapshot);
+    });
+}
+//# sourceMappingURL=updateIpc.js.map

package/build/desktop/updateIpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateIpc.js","sourceRoot":"","sources":["../../desktop/host/updateIpc.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,+BAA+B,EAC/B,4BAA4B,EAC5B,8BAA8B,EAC9B,+BAA+B,GAChC,MAAM,gBAAgB,CAAC;AAIxB;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,QAAQ,EAAE,+BAA+B;IACzC,KAAK,EAAE,4BAA4B;IACnC,QAAQ,EAAE,+BAA+B;IACzC,OAAO,EAAE,8BAA8B;IACvC,KAAK,EAAE,4BAA4B;CAC3B,CAAC;AAWX,MAAM,UAAU,+BAA+B,CAC7C,KAA4B,EAC5B,qBAA8B;IAE9B,IAAI,qBAAqB,KAAK,IAAI,IAAI,qBAAqB,KAAK,SAAS,EAAE,CAAC;QAC1E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,KAAK,qBAAqB,CAAC;AAChD,CAAC;AAaD,MAAM,UAAU,8BAA8B,CAC5C,KAA0C;IAE1C,MAAM,EAAE,OAAO,EAAE,4BAA4B,EAAE,GAAG,KAAK,CAAC;IACxD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAE1C,SAAS,aAAa,CAAC,KAA4B,EAAE,OAAe;QAClE,IAAI,+BAA+B,CAAC,KAAK,EAAE,4BAA4B,EAAE,CAAC,EAAE,CAAC;YAC3E,OAAO;QACT,CAAC;QACD,MAAM,CAAC,6BAA6B,OAAO,4BAA4B,CAAC,CAAC;QACzE,wEAAwE;QACxE,0CAA0C;QAC1C,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO;QACL,CAAC,2BAA2B,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YACtD,aAAa,CAAC,KAAK,EAAE,2BAA2B,CAAC,QAAQ,CAAC,CAAC;YAC3D,OAAO,OAAO,CAAC,WAAW,EAAE,CAAC;QAC/B,CAAC;QACD,CAAC,2BAA2B,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YACnD,aAAa,CAAC,KAAK,EAAE,2BAA2B,CAAC,KAAK,CAAC,CAAC;YACxD,OAAO,OAAO,CAAC,eAAe,EAAE,CAAC;QACnC,CAAC;QACD,CAAC,2BAA2B,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YACtD,aAAa,CAAC,KAAK,EAAE,2BAA2B,CAAC,QAAQ,CAAC,CAAC;YAC3D,OAAO,OAAO,CAAC,cAAc,EAAE,CAAC;QAClC,CAAC;QACD,CAAC,2BAA2B,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YACrD,aAAa,CAAC,KAAK,EAAE,2BAA2B,CAAC,OAAO,CAAC,CAAC;YAC1D,MAAM,OAAO,CAAC,iBAAiB,EAAE,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC;AAOD;;;GAGG;AACH,MAAM,UAAU,oCAAoC,CAClD,KAAgD;IAEhD,MAAM,EAAE,OAAO,EAAE,4BAA4B,EAAE,GAAG,KAAK,CAAC;IAExD,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE;QACpC,MAAM,WAAW,GAAG,4BAA4B,EAAE,CAAC;QACnD,IAAI,WAAW,KAAK,IAAI,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YACtD,OAAO;QACT,CAAC;QACD,IAAI,WAAW,CAAC,WAAW,EAAE,EAAE,KAAK,IAAI,EAAE,CAAC;YACzC,OAAO;QACT,CAAC;QACD,WAAW,CAAC,IAAI,CAAC,2BAA2B,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAChE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/build/desktop/updateManager.d.ts

@@ -0,0 +1,76 @@
+import type { DesktopUpdateCapability, DesktopUpdateError, DesktopUpdateNextAction, DesktopUpdateProgress, DesktopUpdateSnapshot, DesktopUpdateStatus } from './contracts.js';
+import type { DesktopDistributionIdentity, DesktopReleasePlatform } from './releaseDescriptor.js';
+/**
+ * Host-owned update state machine.
+ *
+ * The renderer and tray are presentation surfaces over this one manager. They
+ * request bounded actions and observe snapshots; they never choose a feed, a
+ * URL, a file, or installer arguments.
+ *
+ * The provider is reached through an injected adapter so tests exercise the
+ * lifecycle without live GitHub requests.
+ */
+/**
+ * Platforms whose signed old-version-to-new-version upgrade path has passed.
+ *
+ * PLAN-101 gate G3 admits one platform at a time, and SPEC-111 section 9 keeps
+ * Windows and macOS self-update disabled until signing is validated. The list
+ * is empty on purpose: no platform has passed yet, so no build advertises
+ * self-update even when it carries a valid release descriptor.
+ */
+export declare const DESKTOP_RELEASE_READY_PLATFORMS: readonly DesktopReleasePlatform[];
+export interface DesktopUpdaterCheckResult {
+    updateAvailable: boolean;
+    version: string | null;
+    releaseSummary: string | null;
+}
+export interface DesktopUpdaterAdapter {
+    checkForUpdates(): Promise<DesktopUpdaterCheckResult>;
+    downloadUpdate(onProgress: (progress: DesktopUpdateProgress) => void): Promise<void>;
+    quitAndInstall(): Promise<void>;
+}
+export interface CreateDesktopUpdateCapabilityInput {
+    identity: DesktopDistributionIdentity;
+    nodePlatform: NodeJS.Platform | string;
+    releaseReadyPlatforms?: readonly DesktopReleasePlatform[];
+}
+export declare function createDesktopUpdateCapability(input: CreateDesktopUpdateCapabilityInput): DesktopUpdateCapability;
+/**
+ * The snapshot a build without update capability publishes.
+ *
+ * Used as the fallback wherever a snapshot is required before the manager
+ * exists, so those code paths cannot accidentally imply an update is possible.
+ */
+export declare function createUnavailableDesktopUpdateSnapshot(currentVersion: string): DesktopUpdateSnapshot;
+export declare function resolveDesktopUpdateNextAction(status: DesktopUpdateStatus, capability: DesktopUpdateCapability): DesktopUpdateNextAction;
+/**
+ * Maps a provider error to a stable code plus copy that is safe to render.
+ *
+ * The returned summary is an English fallback only. Renderer surfaces localize
+ * from the code through the shared i18n catalogs, so the raw provider message
+ * never reaches the UI.
+ */
+export declare function mapDesktopUpdateError(error: unknown): DesktopUpdateError;
+export declare function redactDesktopUpdateDiagnostic(message: string): string;
+export interface CreateDesktopUpdateManagerInput {
+    capability: DesktopUpdateCapability;
+    adapter: DesktopUpdaterAdapter | null;
+    now?: () => Date;
+    logger?: (message: string) => void;
+    /**
+     * Restored from the host state file. It is the only update fact worth
+     * carrying across a restart: a provider-dependent status such as
+     * update_available cannot be acted on in a new process without checking
+     * again, so restoring it would offer a download the manager cannot perform.
+     */
+    initialLastCheckedAt?: string | null;
+}
+export interface DesktopUpdateManager {
+    getSnapshot(): DesktopUpdateSnapshot;
+    subscribe(listener: (snapshot: DesktopUpdateSnapshot) => void): () => void;
+    checkForUpdates(): Promise<DesktopUpdateSnapshot>;
+    downloadUpdate(): Promise<DesktopUpdateSnapshot>;
+    restartAndInstall(): Promise<DesktopUpdateSnapshot>;
+}
+export declare function createDesktopUpdateManager(input: CreateDesktopUpdateManagerInput): DesktopUpdateManager;
+//# sourceMappingURL=updateManager.d.ts.map

package/build/desktop/updateManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateManager.d.ts","sourceRoot":"","sources":["../../desktop/host/updateManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,kBAAkB,EAElB,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EACV,2BAA2B,EAC3B,sBAAsB,EACvB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,EAAE,SAAS,sBAAsB,EAAO,CAAC;AAErF,MAAM,WAAW,yBAAyB;IACxC,eAAe,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,eAAe,IAAI,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACtD,cAAc,CACZ,UAAU,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK,IAAI,GACpD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,EAAE,2BAA2B,CAAC;IACtC,YAAY,EAAE,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC;IACvC,qBAAqB,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;CAC3D;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,kCAAkC,GACxC,uBAAuB,CA0DzB;AAED;;;;;GAKG;AACH,wBAAgB,sCAAsC,CACpD,cAAc,EAAE,MAAM,GACrB,qBAAqB,CAqBvB;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,mBAAmB,EAC3B,UAAU,EAAE,uBAAuB,GAClC,uBAAuB,CAiBzB;AA0BD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAcxE;AAQD,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKrE;AAMD,MAAM,WAAW,+BAA+B;IAC9C,UAAU,EAAE,uBAAuB,CAAC;IACpC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,IAAI,qBAAqB,CAAC;IACrC,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC3E,eAAe,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAClD,cAAc,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjD,iBAAiB,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACrD;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,+BAA+B,GACrC,oBAAoB,CAkMtB"}

package/build/desktop/updateManager.js

@@ -0,0 +1,342 @@
+import { resolveDesktopReleasePlatform } from './releaseDescriptor.js';
+/**
+ * Host-owned update state machine.
+ *
+ * The renderer and tray are presentation surfaces over this one manager. They
+ * request bounded actions and observe snapshots; they never choose a feed, a
+ * URL, a file, or installer arguments.
+ *
+ * The provider is reached through an injected adapter so tests exercise the
+ * lifecycle without live GitHub requests.
+ */
+/**
+ * Platforms whose signed old-version-to-new-version upgrade path has passed.
+ *
+ * PLAN-101 gate G3 admits one platform at a time, and SPEC-111 section 9 keeps
+ * Windows and macOS self-update disabled until signing is validated. The list
+ * is empty on purpose: no platform has passed yet, so no build advertises
+ * self-update even when it carries a valid release descriptor.
+ */
+export const DESKTOP_RELEASE_READY_PLATFORMS = [];
+export function createDesktopUpdateCapability(input) {
+    const { identity, nodePlatform } = input;
+    const releaseReadyPlatforms = input.releaseReadyPlatforms ?? DESKTOP_RELEASE_READY_PLATFORMS;
+    const base = {
+        distribution: identity.distribution,
+        channel: identity.channel,
+        currentVersion: identity.currentVersion,
+    };
+    const packagedFromWorkflow = identity.distribution === 'official_packaged'
+        || identity.distribution === 'preview_packaged';
+    if (!packagedFromWorkflow || identity.provider !== 'github_release') {
+        return {
+            ...base,
+            provider: 'none',
+            canCheck: false,
+            canDownload: false,
+            canInstall: false,
+            unavailableReason: identity.unavailableReason,
+        };
+    }
+    const platform = resolveDesktopReleasePlatform(nodePlatform);
+    if (platform === null) {
+        return {
+            ...base,
+            provider: 'github_release',
+            canCheck: false,
+            canDownload: false,
+            canInstall: false,
+            unavailableReason: 'platform_not_release_ready',
+        };
+    }
+    // The release-ready gate exists so a stable build cannot advertise
+    // self-update before its signed upgrade test passes. A preview build is how
+    // that test is run, so the gate does not apply to it.
+    if (identity.distribution === 'official_packaged' && !releaseReadyPlatforms.includes(platform)) {
+        return {
+            ...base,
+            provider: 'github_release',
+            canCheck: false,
+            canDownload: false,
+            canInstall: false,
+            unavailableReason: 'platform_not_release_ready',
+        };
+    }
+    return {
+        ...base,
+        provider: 'github_release',
+        canCheck: true,
+        canDownload: true,
+        canInstall: true,
+        unavailableReason: null,
+    };
+}
+/**
+ * The snapshot a build without update capability publishes.
+ *
+ * Used as the fallback wherever a snapshot is required before the manager
+ * exists, so those code paths cannot accidentally imply an update is possible.
+ */
+export function createUnavailableDesktopUpdateSnapshot(currentVersion) {
+    return {
+        capability: {
+            distribution: 'unofficial_packaged',
+            provider: 'none',
+            channel: 'stable',
+            currentVersion,
+            canCheck: false,
+            canDownload: false,
+            canInstall: false,
+            unavailableReason: 'descriptor_missing',
+        },
+        status: 'unavailable',
+        currentVersion,
+        availableVersion: null,
+        releaseSummary: null,
+        lastCheckedAt: null,
+        progress: null,
+        error: null,
+        nextAction: 'none',
+    };
+}
+export function resolveDesktopUpdateNextAction(status, capability) {
+    if (!capability.canCheck) {
+        return 'none';
+    }
+    switch (status) {
+        case 'idle':
+        case 'up_to_date':
+        case 'failed':
+            return 'check';
+        case 'update_available':
+            return capability.canDownload ? 'download' : 'none';
+        case 'downloaded':
+            return capability.canInstall ? 'restart_install' : 'none';
+        default:
+            return 'none';
+    }
+}
+const ERROR_SUMMARIES = {
+    offline: 'Cats could not reach the update service.',
+    timeout: 'The update service did not respond in time.',
+    provider_rejected: 'The update service rejected the request.',
+    metadata_invalid: 'The update information could not be read.',
+    checksum_mismatch: 'The downloaded update failed its integrity check.',
+    signature_rejected: 'The downloaded update failed its signature check.',
+    unsupported_package: 'This installation cannot update itself.',
+    download_cancelled: 'The update download was cancelled.',
+    install_handoff_failed: 'Cats could not hand off to the installer.',
+    unknown: 'The update could not be completed.',
+};
+const ERROR_CODE_PATTERNS = [
+    ['offline', /enotfound|eai_again|econnrefused|econnreset|enetunreach|offline|dns/iu],
+    ['timeout', /etimedout|timed? ?out|esockettimedout/iu],
+    ['checksum_mismatch', /sha512|sha256|checksum|integrity/iu],
+    ['signature_rejected', /signature|publishername|not signed|authenticode/iu],
+    ['download_cancelled', /cancel/iu],
+    ['unsupported_package', /unsupported|not supported|no published versions|dev-app-update/iu],
+    ['metadata_invalid', /latest\.yml|latest-mac\.yml|metadata|unable to parse|invalid yml/iu],
+    ['provider_rejected', /http (4|5)\d\d|status code (4|5)\d\d|forbidden|not found|rate limit/iu],
+];
+/**
+ * Maps a provider error to a stable code plus copy that is safe to render.
+ *
+ * The returned summary is an English fallback only. Renderer surfaces localize
+ * from the code through the shared i18n catalogs, so the raw provider message
+ * never reaches the UI.
+ */
+export function mapDesktopUpdateError(error) {
+    const haystack = [
+        typeof error === 'string' ? error : '',
+        error instanceof Error ? error.message : '',
+        isRecord(error) && typeof error.code === 'string' ? error.code : '',
+    ].join(' ');
+    for (const [code, pattern] of ERROR_CODE_PATTERNS) {
+        if (pattern.test(haystack)) {
+            return { code, summary: ERROR_SUMMARIES[code] };
+        }
+    }
+    return { code: 'unknown', summary: ERROR_SUMMARIES.unknown };
+}
+const SECRET_PATTERNS = [
+    /gh[pousr]_[A-Za-z0-9_]{16,}/gu,
+    /github_pat_[A-Za-z0-9_]{20,}/gu,
+    /(authorization|token|password|secret)"?\s*[:=]\s*"?[^\s",}]+/giu,
+];
+export function redactDesktopUpdateDiagnostic(message) {
+    return SECRET_PATTERNS.reduce((redacted, pattern) => redacted.replace(pattern, '[redacted]'), message);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function createDesktopUpdateManager(input) {
+    const { capability, adapter } = input;
+    const now = input.now ?? (() => new Date());
+    const logger = input.logger ?? (() => { });
+    const usable = capability.canCheck && adapter !== null;
+    let status = usable ? 'idle' : 'unavailable';
+    let availableVersion = null;
+    let releaseSummary = null;
+    let lastCheckedAt = input.initialLastCheckedAt ?? null;
+    let progress = null;
+    let error = null;
+    // SPEC-111 section 2 allows one check or download at a time. Repeated
+    // requests join the in-flight operation instead of starting a second
+    // provider request.
+    let pendingCheck = null;
+    let pendingDownload = null;
+    const listeners = new Set();
+    function snapshot() {
+        return {
+            capability,
+            status,
+            currentVersion: capability.currentVersion,
+            availableVersion,
+            releaseSummary,
+            lastCheckedAt,
+            progress,
+            error,
+            nextAction: resolveDesktopUpdateNextAction(status, capability),
+        };
+    }
+    function publish() {
+        const current = snapshot();
+        for (const listener of listeners) {
+            listener(current);
+        }
+        return current;
+    }
+    function log(message) {
+        logger(redactDesktopUpdateDiagnostic(message));
+    }
+    function fail(cause, stage) {
+        error = mapDesktopUpdateError(cause);
+        status = 'failed';
+        progress = null;
+        log(`[desktop-update] ${stage} failed (${error.code}): `
+            + `${cause instanceof Error ? cause.message : String(cause)}`);
+        return publish();
+    }
+    async function runCheck(activeAdapter) {
+        status = 'checking';
+        error = null;
+        publish();
+        try {
+            const result = await activeAdapter.checkForUpdates();
+            lastCheckedAt = now().toISOString();
+            if (!result.updateAvailable) {
+                status = 'up_to_date';
+                availableVersion = null;
+                releaseSummary = null;
+                return publish();
+            }
+            if (result.version === null || result.version.trim() === '') {
+                throw new Error('Provider reported an available update without a version.');
+            }
+            status = 'update_available';
+            availableVersion = result.version;
+            releaseSummary = result.releaseSummary;
+            return publish();
+        }
+        catch (cause) {
+            lastCheckedAt = now().toISOString();
+            return fail(cause, 'check');
+        }
+    }
+    async function runDownload(activeAdapter) {
+        status = 'downloading';
+        error = null;
+        progress = { percent: 0, transferredBytes: 0, totalBytes: 0, bytesPerSecond: 0 };
+        publish();
+        try {
+            await activeAdapter.downloadUpdate((next) => {
+                // A late progress event after a failure must not resurrect the
+                // downloading state.
+                if (status !== 'downloading') {
+                    return;
+                }
+                progress = next;
+                publish();
+            });
+            status = 'downloaded';
+            progress = null;
+            return publish();
+        }
+        catch (cause) {
+            return fail(cause, 'download');
+        }
+    }
+    return {
+        getSnapshot: snapshot,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        async checkForUpdates() {
+            if (!usable || adapter === null) {
+                return snapshot();
+            }
+            if (pendingDownload !== null) {
+                return pendingDownload;
+            }
+            if (pendingCheck !== null) {
+                return pendingCheck;
+            }
+            pendingCheck = runCheck(adapter).finally(() => {
+                pendingCheck = null;
+            });
+            return pendingCheck;
+        },
+        async downloadUpdate() {
+            if (!usable || adapter === null || !capability.canDownload) {
+                return snapshot();
+            }
+            if (pendingDownload !== null) {
+                return pendingDownload;
+            }
+            if (pendingCheck !== null) {
+                return pendingCheck;
+            }
+            // Automatic download stays disabled: only an explicit request from a
+            // surface reaches here, and only from update_available.
+            if (status !== 'update_available') {
+                return snapshot();
+            }
+            pendingDownload = runDownload(adapter).finally(() => {
+                pendingDownload = null;
+            });
+            return pendingDownload;
+        },
+        async restartAndInstall() {
+            if (!usable || adapter === null || !capability.canInstall) {
+                return snapshot();
+            }
+            if (status !== 'downloaded') {
+                return snapshot();
+            }
+            status = 'installing';
+            error = null;
+            publish();
+            try {
+                await adapter.quitAndInstall();
+                return snapshot();
+            }
+            catch (cause) {
+                log('[desktop-update] install handoff failed: '
+                    + `${cause instanceof Error ? cause.message : String(cause)}`);
+                // The handoff failed before the process exited, so the downloaded
+                // update is still installable and the user can retry it.
+                status = 'downloaded';
+                progress = null;
+                error = {
+                    code: 'install_handoff_failed',
+                    summary: ERROR_SUMMARIES.install_handoff_failed,
+                };
+                return publish();
+            }
+        },
+    };
+}
+//# sourceMappingURL=updateManager.js.map

package/build/desktop/updateManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateManager.js","sourceRoot":"","sources":["../../desktop/host/updateManager.ts"],"names":[],"mappings":"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"}

package/build/desktop/updateNotifications.d.ts

@@ -0,0 +1,64 @@
+import type { DesktopUpdateErrorCode, DesktopUpdateSnapshot } from './contracts.js';
+import { type DesktopTrayLocale } from './trayMenu.js';
+/**
+ * Native update notifications.
+ *
+ * SPEC-111 section 5 requires a check started outside Settings to report its
+ * result somewhere the user is actually looking. This module owns that policy;
+ * `main.ts` only constructs the native notification the policy asks for, so the
+ * rules stay testable without Electron.
+ */
+/** Where the check that produced the result came from. */
+export declare const DESKTOP_UPDATE_NOTIFICATION_ORIGINS: readonly ["tray", "settings", "startup"];
+export type DesktopUpdateNotificationOrigin = typeof DESKTOP_UPDATE_NOTIFICATION_ORIGINS[number];
+export declare const DESKTOP_UPDATE_SETTINGS_PATH = "/settings/desktop";
+export interface DesktopUpdateNotification {
+    title: string;
+    body: string;
+    /** Where activating the notification shall land the user. */
+    navigatePath: typeof DESKTOP_UPDATE_SETTINGS_PATH;
+}
+export interface DesktopUpdateAnnouncement {
+    notification: DesktopUpdateNotification | null;
+    /**
+     * Where to open the main window when no notification reaches the user —
+     * either because the platform has none or because showing it failed.
+     *
+     * Null when the result does not justify pulling a window forward. Set
+     * independently of `notification` so the caller never has to re-derive the
+     * policy after a failed `show()`.
+     */
+    fallbackNavigatePath: typeof DESKTOP_UPDATE_SETTINGS_PATH | null;
+}
+/**
+ * Error copy for notifications, in the same two locales the tray uses.
+ *
+ * These strings are duplicated from the renderer i18n catalogs because the
+ * main process has no translator. `settings-desktop-update-labels.test.tsx`
+ * asserts they stay identical to the catalog entries, so the duplication cannot
+ * drift silently.
+ */
+export declare const DESKTOP_UPDATE_NOTIFICATION_ERROR_COPY: Record<DesktopTrayLocale, Record<DesktopUpdateErrorCode, string>>;
+export interface ResolveDesktopUpdateAnnouncementInput {
+    origin: DesktopUpdateNotificationOrigin;
+    snapshot: DesktopUpdateSnapshot;
+    locale?: string | null;
+    /** `Notification.isSupported()`, resolved by the caller. */
+    notificationsSupported: boolean;
+}
+/**
+ * Decides what a finished check should tell the user, and how.
+ *
+ * A result is announced only when the user cannot already see it:
+ *
+ * - `settings` never announces. The section shows the state directly and
+ *   routes manual results through the shared toast system, so a native
+ *   notification would report the same check twice.
+ * - `tray` announces up-to-date, available, and failed. The menu closes on
+ *   click, so without this the command looks like it did nothing.
+ * - `startup` announces only an available update. The user did not ask for
+ *   that check, so an up-to-date or offline result has nothing to say and
+ *   would nag on every launch.
+ */
+export declare function resolveDesktopUpdateAnnouncement(input: ResolveDesktopUpdateAnnouncementInput): DesktopUpdateAnnouncement;
+//# sourceMappingURL=updateNotifications.d.ts.map

package/build/desktop/updateNotifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateNotifications.d.ts","sourceRoot":"","sources":["../../desktop/host/updateNotifications.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAIxB,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAEvB;;;;;;;GAOG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,mCAAmC,0CAA2C,CAAC;AAC5F,MAAM,MAAM,+BAA+B,GACzC,OAAO,mCAAmC,CAAC,MAAM,CAAC,CAAC;AAErD,eAAO,MAAM,4BAA4B,sBAAsB,CAAC;AAEhE,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,YAAY,EAAE,OAAO,4BAA4B,CAAC;CACnD;AAED,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC/C;;;;;;;OAOG;IACH,oBAAoB,EAAE,OAAO,4BAA4B,GAAG,IAAI,CAAC;CAClE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sCAAsC,EAAE,MAAM,CACzD,iBAAiB,EACjB,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAAC,CA0BvC,CAAC;AAmCF,MAAM,WAAW,qCAAqC;IACpD,MAAM,EAAE,+BAA+B,CAAC;IACxC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,4DAA4D;IAC5D,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,qCAAqC,GAC3C,yBAAyB,CA2B3B"}