openclaw - 💡(How to fix) Fix [Feature]: Make the macOS updater/release pipeline fully Sparkle-native and atomic [1 participants]

Summary

Make the macOS companion app's release/update path fully standardized around sparkle-project/Sparkle, with one atomic publishing flow so the appcast can never advertise a missing or mismatched asset.

Problem to solve

OpenClaw already uses Sparkle in the macOS app (apps/macos/Package.swift) and the release docs are already Sparkle-centric (docs/platforms/mac/release.md). But the current release path still appears able to enter invalid intermediate states where:

• the Sparkle appcast points at a missing GitHub asset
• a recovery tag/release exists without the macOS asset attached
• the app updater offers an update that cannot actually be installed
• the app and CLI/gateway drift into different versions, creating confusing or noisy local behavior

That means the project has effectively adopted Sparkle in code, but not yet fully made Sparkle the single, reliable source of truth for macOS release publication.

Issue #48306 is a concrete example of this class of failure: the updater advertised a release via appcast, but the referenced asset path was dead, leaving users stuck on an older app while the gateway/CLI continued moving.

Proposed solution

Treat Sparkle as the canonical macOS update mechanism end-to-end, and make release publication atomic.

Concretely:

1. Single source of truth for macOS release metadata

   • Generate the appcast entry from the exact artifact set that was actually built for the release.
   • Avoid any path where tag names, asset names, appcast enclosure URLs, and build metadata can drift independently.

2. Atomic publish flow

   • Build/sign/notarize the macOS app artifacts.
   • Upload the zip/dmg/dSYM assets to the intended GitHub release.
   • Verify the uploaded enclosure URLs return 200.
   • Only then publish/update appcast.xml.
   • If any step fails, do not advertise the release to Sparkle clients.

3. CI / release guardrails

   • Fail release automation if the appcast references a missing GitHub asset.
   • Fail if the appcast points at a tag/release that is not the one actually holding the uploaded macOS artifact.
   • Fail if a "recovery" or re-cut release changes the effective asset location without regenerating the Sparkle entry.
   • Keep existing monotonic sparkle:version checks, but extend them to enclosure reachability + release/asset consistency.

4. Safer client behavior when release state is invalid

   • If the project cannot guarantee a valid downloadable artifact, the updater should not advertise that build.
   • Prefer "no update offered" over "update offered but download fails".

5. Documentation and release tooling cleanup

   • Update the macOS release docs/scripts so there is one blessed Sparkle release path, not a partially manual chain that can leave the appcast ahead of the assets.

Alternatives considered

• Keep the current approach and patch failures ad hoc
  This fixes individual broken releases but not the class of failure.

• Rely on manual checklist discipline only
  The docs already describe the right checks, but the system still seems able to publish invalid update state. This should be enforced by tooling, not memory.

• Move away from Sparkle
  That does not seem necessary. The repo is already using Sparkle; the gap appears to be release/process consistency, not the updater library choice.

Impact

• Affected: macOS companion app users and anyone operating mixed app + CLI/gateway versions
• Severity: High when it happens, because self-update breaks and recovery becomes confusing
• Frequency: Likely release-pipeline dependent rather than constant, but severe enough that one bad release is costly
• Consequence: failed in-app updates, manual recovery friction, and possible split-brain behavior between the macOS app and newer gateway/CLI installs

Evidence/examples

• apps/macos/Package.swift already depends on https://github.com/sparkle-project/Sparkle
• docs/platforms/mac/release.md already documents a Sparkle-based release flow
• #48306 shows a real failure mode where the appcast advertised an update whose asset was not actually downloadable

Additional information

This request is intentionally not "switch to Sparkle" — that part already happened. The ask is to finish the job by making the macOS release/update system truly Sparkle-native, deterministic, and impossible to publish in a half-broken state.