codex-island CLAUDE.md

CLAUDE.md

Project-specific guardrails. Read every section before touching this repo.

Release process — MANDATORY

This app ships via Sparkle auto-update. Get any of this wrong and you brick auto-update for everyone who's already installed.

The loop (3 commands)

echo "X.Y.Z" > VERSION                                # 1. Bump
git commit -am "chore(release): bump VERSION to X.Y.Z" \
  && git tag vX.Y.Z                                   # 2. Commit + tag
git push origin main vX.Y.Z                           # 3. Push (fires CI)

The marketing landing site at ericjypark/codex-island-landing has its own VERSION file (the hero chip + footer read it at build time). Bump it in that repo too, in the same release sweep, or the public site keeps showing the prior version even after brew install ships the new one.

That's it. CI does everything else in ~1.5 min:

• Builds the universal DMG
• Signs it with the EdDSA key from the SPARKLE_ED_PRIVATE_KEY secret
• Generates appcast.xml listing the new version
• Uploads DMG + appcast as release assets
• Mirrors the cask to ericjypark/homebrew-tap with the new version + SHA-256

Watch with gh run watch --exit-status if you want confirmation, or just trust it.

Hard rules — break these and you brick auto-update

1. VERSION must be a single-monotonic version like 0.0.X, NOT 1 or 100 or anything weird. build.sh uses $VERSION as both CFBundleVersion and CFBundleShortVersionString. Sparkle compares CFBundleVersion of the running app against sparkle:version in the appcast using Apple's component-wise comparator — so "1" parses as [1] and is larger than "0.0.99". Stay in semver. Always increase.

2. The Sparkle public key in build.sh (SU_PUBLIC_KEY="bz1g...") must NEVER be changed casually. Every existing install verifies updates against this exact key. Change it and every prior install rejects every future update silently. The matching private key lives in (a) the maintainer's macOS Keychain under service https://sparkle-project.org and (b) the SPARKLE_ED_PRIVATE_KEY GitHub Actions secret. To rotate, see the migration note in docs/SPARKLE.md (TL;DR: don't).