generate-sparkle-appcast

Use this skill when the user wants to publish a new Mos release (stable or beta) and needs:

• Sparkle appcast.xml generated from the notarized .zip in build/
• Two hosted release notes pages (Chinese + English)
• Sparkle to show Chinese for all zh* locales (Simplified/Traditional/HK/TW), and English for everything else

Inputs

• --since <commit>: the previous release commit (exclusive). Used to generate release notes from changes since that commit.
  • If not provided, reads from .last-release-commit file automatically.
• A notarized+zipped app in build/ named:
  • Mos.Versions.<version>-<YYYYMMDD>.<num>.zip (stable)
  • Mos.Versions.<version>-beta-<YYYYMMDD>.<num>.zip (beta)
• Sparkle Ed25519 private key at sparkle_private_key.txt (gitignored).
• .last-release-commit: stores the previous release commit hash (auto-read if --since not provided).
• Optional env:
  • RELEASE_NOTES_BASE_URL (default https://mos.caldis.me/release-notes)
  • RELEASE_NOTES_ZH_FILE / RELEASE_NOTES_EN_FILE to point to pre-written HTML files (otherwise the script writes to build/release-notes/<tag>.*.html)

What to do

1. Run the skill script:
   • bash .codex/skills/generate-sparkle-appcast/scripts/generate_appcast.sh
   • (Optional) Override commit: bash .codex/skills/generate-sparkle-appcast/scripts/generate_appcast.sh --since <commit>
2. Confirm outputs:
   • build/appcast.xml (generated)
   • docs/appcast.xml (copied for mos.caldis.me/appcast.xml)
   • build/release-notes/<tag>.zh.html + build/release-notes/<tag>.en.html (generated)
   • docs/release-notes/<tag>.zh.html + docs/release-notes/<tag>.en.html (copied for hosting)
   • build/release-notes/{beta|stable}.zh.html + build/release-notes/{beta|stable}.en.html (generated, version history for Sparkle)
   • docs/release-notes/{beta|stable}.zh.html + docs/release-notes/{beta|stable}.en.html (copied for hosting)
3. Ensure the GitHub Release tag and asset name match the URL inside the generated appcast.

Notes

• The script preserves existing <item> entries in docs/appcast.xml and prepends the new release item (deduped by sparkle:version), so new releases don't overwrite old ones.
• The appcast includes two <sparkle:releaseNotesLink> entries: xml:lang="zh" points to the Chinese page, and the default link points to the English page.
• For cross-version upgrades, the appcast points releaseNotesLink to a channel history page (release-notes/{beta|stable}.*.html) that contains multiple version sections wrapped in data-sparkle-version="<CFBundleVersion>". Sparkle will mark the installed version in the HTML, and the page CSS hides versions older than the installed one.
• You can pre-create/edit build/release-notes/<tag>.zh.html and build/release-notes/<tag>.en.html before running the script; the script will reuse them if present, otherwise it generates a default template from git history.
• If the zip changes in any way (repacked/re-signed), you must re-run the script to regenerate sparkle:edSignature.
• After a successful release, update .last-release-commit with the new release commit hash for the next release.