Merge pull request #22 from levelcodeai/feat/auto-update-signed-zip

feat(release): emit a signed .app.zip update asset (auto-update S1)

Author: ndemianc

.github/workflows/release.yml

@@ -106,8 +106,11 @@ jobs:
             1. `gh release download ${{ github.ref_name }} --pattern 'UNSIGNED-*.app.zip'`
             2. For each arch — unzip into `VSCode-darwin-<arch>/`, then
                `CODESIGN_IDENTITY="Developer ID Application: …" NOTARY_PROFILE=levelcode-notary ./scripts/make-dmg.sh <arch>`
-               (signs → dmg → notarizes → staples → `LevelCode-<arch>.dmg`).
-            3. `gh release upload ${{ github.ref_name }} LevelCode-arm64.dmg LevelCode-x64.dmg`
+               (signs → notarizes → staples → `LevelCode-<arch>.dmg` **and** `LevelCode-<arch>.app.zip`).
+            3. `gh release upload ${{ github.ref_name }} LevelCode-arm64.dmg LevelCode-x64.dmg LevelCode-arm64.app.zip LevelCode-x64.app.zip`
+               — the `.dmg`s are for humans, the `.app.zip`s are the auto-update feed assets (`docs/AUTO-UPDATE.md`).
+               Upload exactly these four; the `.app.zip.sha256` files `make-dmg.sh` writes stay **local**
+               (the feed reads GitHub's own asset `digest`, never a sidecar).
             4. **Delete the `UNSIGNED-*.app.zip` assets**, add real notes, and publish.
 
             Full runbook: `docs/RELEASING.md`.

docs/AUTO-UPDATE.md

@@ -0,0 +1,96 @@
+# LevelCode — Signed auto-update (Squirrel `.zip`) — scope
+
+**Goal:** make the editor's built-in **Check for Updates…** actually install a new build, instead of
+always reporting "There are currently no updates available."
+
+**Today:** that dialog is *correct behaviour*, not a bug. `Api::UpdatesController` (thin.ly) serves
+**204** to every client except the notify-only extension — a deliberate **unsigned-build guard**,
+because the built-in Squirrel updater *auto-downloads and installs* whatever `url` a 200 returns, and
+today that `url` is a GitHub **release page**, not a signed `.zip`. Squirrel would download it and fail.
+
+Verified against production while scoping:
+
+| Client | Request | Response |
+|---|---|---|
+| Built-in Squirrel updater | `GET /api/update/darwin-arm64/stable/<commit>` | **204** (guard) |
+| Notify-only extension (`User-Agent: LevelCode Updater`) | same | **200** `productVersion: 0.7.2` |
+
+## What already exists (most of the hard part)
+
+- **`scripts/notarize.sh sign`** — Developer ID signing with **hardened runtime** + `levelcode.entitlements`.
+- **`scripts/notarize.sh notarize-app`** — notarizes **and staples the `.app` itself**, precisely so a
+  copied-out app validates offline. **This is exactly the artifact Squirrel needs.**
+- **CI already zips an app** with `ditto -c -k --sequesterRsrc --keepParent` (for the UNSIGNED artifact) —
+  the same command, applied to the *signed* app, produces the feed asset.
+- **`Api::UpdatesController`** already implements the full Code-OSS feed contract, the guard, and
+  `LEVELCODE_UPDATE_FEED` (a JSON env override) — which doubles as the **rollback/pin lever**.
+- **`Levelcode::EditorReleaseFeed`** already resolves tag → commit, `product_version`, and timestamp.
+
+So this is **not** a new signing pipeline. It is: publish one more asset, teach the feed to point at it,
+then lift the guard.
+
+## The gap
+
+1. **Release artifact.** Produce `LevelCode-<arch>.app.zip` from the **signed + notarized + stapled**
+   `.app` (a `ditto` after `make-dmg.sh`'s signing step) and publish it on the release. The `.dmg` stays —
+   it remains the fresh-install path; the `.zip` is update-only.
+   *The zip is the only new release asset.* `make-dmg.sh` also writes a `.app.zip.sha256` beside it, but
+   that stays **local**: the feed's `sha256hash` comes from GitHub's API-computed asset `digest`
+   (`"sha256:<hex>"`), so no sidecar is ever fetched. The file is for verifying by hand that the zip you
+   published is the zip you built.
+2. **Feed asset resolution.** `EditorReleaseFeed#fetch_release` currently returns `url: rel["html_url"]`
+   (the release page) and `sha256hash: nil`. It must select the **right asset** from `rel["assets"]` by
+   arch and return its `browser_download_url` plus the hash from that asset's own `digest` field.
+3. **Arch mapping.** Feed targets are `darwin-arm64` and `darwin` (Intel). Map to the arm64 / x64 zips
+   respectively — **never serve a cross-arch zip**.
+4. **Lift the guard.** Set `LEVELCODE_UPDATE_FEED_SIGNED=1` on Elastic Beanstalk — **only after 1–3**.
+5. **Notify-only Download button.** `extensions/levelcode-updater/extension.js:96` is
+   `feed.url || product.downloadUrl || base`. Once `feed.url` is a raw `.zip`, that button would hand
+   users a zip instead of the release page. Reorder to prefer `product.downloadUrl` / the release page.
+
+## Slices
+
+**S1 — publish the signed zip (client).** Add the `ditto` + `shasum` step to `make-dmg.sh` (or a
+`make-update-zip.sh`), update `docs/RELEASING.md`, and upload `LevelCode-<arch>.app.zip` with the dmg.
+*Ship this alone first — it is inert until the feed points at it.*
+
+**S2 — serve it (server).** Teach `EditorReleaseFeed` to pick the arch-matched asset + hash. Guard stays
+on, so behaviour is unchanged; assert the new shape in `spec/requests/api/updates_spec.rb`.
+
+**S3 — extension URL fix.** Reorder the Download preference so it never opens a raw zip.
+
+**S4 — flip the flag + verify.** Set `LEVELCODE_UPDATE_FEED_SIGNED=1`, then run the end-to-end test below.
+
+## Risks (the ones that actually bite)
+
+- **Sequencing.** Flipping the flag before S1–S2 makes things *worse* — Squirrel would download a web
+  page and fail loudly. S4 must be last.
+- **Signing-identity continuity.** Squirrel.Mac refuses an update whose Developer ID doesn't match the
+  running app. **Rotating or changing the signing cert breaks auto-update for every installed build**,
+  with no in-app recovery — those users must re-download manually. Treat the identity as long-lived.
+- **No staged rollout.** Publishing a release auto-installs for everyone on the next check. The rollback
+  lever is `LEVELCODE_UPDATE_FEED` (pin the previous commit) — but installs that already updated are
+  *not* reverted. Consider a canary/percentage gate before this is a large install base.
+- **Unverifiable by inspection.** Auto-update can only be proven by actually doing it on a real Mac
+  (install N, publish N+1, watch the swap). Budget a real test cycle, not a code review.
+- **Stapling must survive the zip.** `ditto --sequesterRsrc --keepParent` preserves the stapled ticket;
+  re-zipping with `zip(1)` can drop extended attributes. Keep using `ditto`.
+- **Notarization latency.** Apple's notarization is minutes, occasionally longer — the zip must be cut
+  *after* `notarize-app` completes, or you publish an unstapled app.
+
+## Exit test
+
+1. Install **N** (e.g. v0.7.2) from the dmg, confirm `About` shows its commit.
+2. Publish **N+1** with the signed zip attached and the feed serving it.
+3. In N: **Check for Updates…** → it offers, downloads, and **relaunches into N+1**; `About` shows the
+   new commit. No Gatekeeper prompt.
+4. Confirm the Intel build receives the x64 zip (not arm64).
+5. Pin `LEVELCODE_UPDATE_FEED` back to N's commit → a fresh N+1 install reports "up to date"
+   (proves the rollback lever).
+
+## Not doing (explicitly)
+
+- Windows/Linux feeds — `EditorReleaseFeed::TARGETS` is macOS-only by design; announcing a build that
+  doesn't exist is worse than silence.
+- Delta updates. Full-zip replacement is fine at this size.
+- Auto-update for the notify-only extension — it stays notify-only by design.

docs/RELEASING.md

@@ -81,16 +81,46 @@ Build **both architectures** on matching hardware (Apple silicon → `arm64`, In
 
 ```bash
 gh release create v0.1.0 --title "LevelCode v0.1.0" --notes "First public build. …" \
-  LevelCode-arm64.dmg LevelCode-x64.dmg
+  LevelCode-arm64.dmg LevelCode-x64.dmg \
+  LevelCode-arm64.app.zip LevelCode-x64.app.zip
 ```
+Upload **both kinds**: the `.dmg` is what humans install; the `.app.zip` is what the built-in updater
+installs (Squirrel takes a zip, never a dmg). `make-dmg.sh` also writes a `.app.zip.sha256` next to each
+zip — that one is **not** a release asset; it stays local. See §5.
 Stable URL: `https://github.com/levelcodeai/levelcode/releases/latest/download/LevelCode-arm64.dmg` — link it
 from **levelcode.ai/download**.
 
-## 5. Point the update feed at the release
+## 5. The update feed
 
-The notify-only updater (`extensions/levelcode-updater`) polls a feed from `tools/update-server`. After
-publishing, update the feed's release entry (version + the release-asset URLs above) so running installs
-see the new version. Keep the feed version in lockstep with the tag.
+Publishing the GitHub release **is** the announcement — `Levelcode::EditorReleaseFeed` (thin.ly) reads
+`releases/latest` and serves `/api/update/{target}/{quality}/{commit}`. There is no feed file to
+hand-maintain per release.
+
+Two assets, **not** interchangeable:
+
+| Asset | Consumer |
+| --- | --- |
+| `LevelCode-<arch>.dmg` | Humans — fresh install, drag to Applications. |
+| `LevelCode-<arch>.app.zip` | The built-in **Squirrel** updater — it installs from a zip, never a dmg. |
+
+`make-dmg.sh` emits the `.app.zip` **only on the Developer-ID path**, because Squirrel refuses an update
+whose signing identity doesn't match the running app — an ad-hoc build must never be served as an update.
+
+**Only those two files get uploaded per arch.** `make-dmg.sh` also writes `LevelCode-<arch>.app.zip.sha256`,
+but that is a **local verification convenience, not a release asset**: the feed reads `sha256hash` from
+GitHub's own API-computed asset `digest` (`"sha256:<hex>"`), so nothing ever fetches a sidecar file.
+Uploading one is harmless — `EditorReleaseFeed` matches assets by exact filename and ignores anything
+else — just unnecessary. Use it to confirm the zip you published is the zip you built:
+```bash
+Z=LevelCode-arm64.app.zip
+[ "$(shasum -a 256 "$Z" | cut -d' ' -f1)" = "$(cat "$Z.sha256")" ] && echo "$Z OK" || echo "$Z MISMATCH"
+```
+
+`LEVELCODE_UPDATE_FEED` (env JSON on the server) overrides the GitHub lookup and is the **rollback pin**:
+point it at the previous commit to stop a bad release propagating. Note it can't un-update anyone who
+already took the release.
+
+Full contract, rollout order, and risks: **`docs/AUTO-UPDATE.md`**.
 
 ## 6. Troubleshooting *(the ones that actually bit us are marked ⚑)*
 
@@ -130,11 +160,13 @@ gh release download v0.1.0 --pattern 'UNSIGNED-*.app.zip'
 for A in arm64 x64; do
   rm -rf "VSCode-darwin-$A" && ditto -x -k "UNSIGNED-LevelCode-$A.app.zip" "VSCode-darwin-$A"
   CODESIGN_IDENTITY="Developer ID Application: SERGII DEMIANCHUK (AJ27Y4Z2HS)" \
-    NOTARY_PROFILE=levelcode-notary ./scripts/make-dmg.sh "$A"     # → LevelCode-$A.dmg (signed+notarized+stapled)
+    NOTARY_PROFILE=levelcode-notary ./scripts/make-dmg.sh "$A"     # → LevelCode-$A.dmg + LevelCode-$A.app.zip
 done
 
-# 3. Verify (§3), then attach the dmgs, drop the unsigned zips, and publish
-gh release upload v0.1.0 LevelCode-arm64.dmg LevelCode-x64.dmg
+# 3. Verify (§3), then attach the dmgs AND the update zips, drop the unsigned zips, and publish.
+#    The .app.zip.sha256 files stay local on purpose — the feed uses GitHub's own asset digest (§5).
+gh release upload v0.1.0 LevelCode-arm64.dmg LevelCode-x64.dmg \
+                         LevelCode-arm64.app.zip LevelCode-x64.app.zip
 # `gh release delete-asset` takes ONE asset per call — drop each unsigned zip separately (`-y` skips the prompt).
 gh release delete-asset v0.1.0 UNSIGNED-LevelCode-arm64.app.zip -y
 gh release delete-asset v0.1.0 UNSIGNED-LevelCode-x64.app.zip -y

scripts/make-dmg.sh

@@ -6,16 +6,24 @@
 # loose files and it can't be "installed". A .dmg wraps the whole app into one
 # compressed file you can upload, download, and drag-to-install.
 #
-# This script:
-#   1. Locates VSCode-darwin-<arch>/LevelCode.app (run ./scripts/build-macos.sh first).
-#   2. Ad-hoc code-signs it. arm64 macOS refuses to launch *unsigned* binaries at all,
-#      so even for personal use the app must carry at least an ad-hoc signature.
-#   3. Builds a compressed .dmg containing the app + an /Applications symlink.
+# It operates on VSCode-darwin-<arch>/LevelCode.app (run ./scripts/build-macos.sh first).
+# Steps below are numbered to match the `# N.` markers in the script body:
+#   0. De-Microsoft the bundle + hide not-yet-ready features, before signing covers the result.
+#   1. Sign the app. Ad-hoc by default (arm64 macOS refuses to launch *unsigned* binaries at all);
+#      with CODESIGN_IDENTITY set, real Developer ID signing + notarize + staple.
+#   2. Stage a clean folder: the app + an /Applications symlink.
+#   3. Build the compressed .dmg from it.
+#   4. Developer ID path only — sign, notarize + staple the .dmg itself.
+#   5. Developer ID path only — emit LevelCode-<arch>.app.zip, the auto-update feed asset the
+#      built-in Squirrel updater installs. See docs/AUTO-UPDATE.md.
 #
-# The result is UNNOTARIZED. On another Mac, Gatekeeper will still warn on first launch:
+# Gatekeeper: on the DEFAULT (ad-hoc) path the result is UNNOTARIZED, so on another Mac Gatekeeper
+# warns on first launch:
 #   - Right-click the app > Open (once), OR
 #   - clear quarantine after copying out of the dmg:
 #       xattr -dr com.apple.quarantine "/Applications/LevelCode.app"
+# With CODESIGN_IDENTITY set, steps 1 + 4 notarize and staple both the app and the dmg — a plain
+# double-click then works on any Mac, offline, with no warning.
 #
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -98,11 +106,34 @@ if [ "$NOTARIZE" = "1" ]; then
   "$SCRIPT_DIR/notarize.sh" submit "$DMG_OUT"
 fi
 
+# 5. Squirrel update asset — a .zip of the SIGNED + NOTARIZED + STAPLED .app.
+# The built-in updater (Squirrel.Mac) installs from a .zip, never a .dmg, and refuses an update whose
+# Developer ID doesn't match the running app — so this is produced ONLY on the signed path; an ad-hoc
+# build must never masquerade as an update asset. Use `ditto` (not `zip`): it preserves the stapled
+# notarization ticket, so the updated app still validates offline. Feed + rollout: docs/AUTO-UPDATE.md.
+#
+# The `.sha256` sidecar is LOCAL ONLY — do not upload it as a release asset. The update feed reads the
+# hash from GitHub's own API-computed asset `digest` ("sha256:<hex>"), not from a sidecar file; see
+# Levelcode::EditorReleaseFeed#build_assets in thin.ly. It exists so a releaser can verify by hand
+# that the zip they published is the zip they built.
+ZIP_OUT=""
+if [ "$NOTARIZE" = "1" ]; then
+  ZIP_OUT="$ROOT_DIR/LevelCode-$ARCH.app.zip"
+  echo "[make-dmg] Creating the signed update asset (Squirrel .zip) …"
+  rm -f "$ZIP_OUT" "$ZIP_OUT.sha256"
+  ditto -c -k --sequesterRsrc --keepParent "$APP" "$ZIP_OUT"
+  shasum -a 256 "$ZIP_OUT" | cut -d' ' -f1 > "$ZIP_OUT.sha256"
+fi
+
 SIZE="$(du -sh "$DMG_OUT" | cut -f1)"
 echo "[make-dmg] Done."
 echo "[make-dmg]   Output: $DMG_OUT  ($SIZE)"
 if [ "$NOTARIZE" = "1" ]; then
   echo "[make-dmg]   Signed + notarized — upload it; users just open the dmg and drag to Applications."
+  echo "[make-dmg]   Update asset: $ZIP_OUT  ($(du -sh "$ZIP_OUT" | cut -f1))"
+  echo "[make-dmg]   sha256: $(cat "$ZIP_OUT.sha256")  (local check only — the feed uses GitHub's own digest)"
+  echo "[make-dmg]   Upload EXACTLY these two: the .dmg (fresh installs) and the .app.zip (auto-update"
+  echo "[make-dmg]   feed). The .sha256 stays local — uploading it is harmless but pointless."
 else
   echo "[make-dmg]   Upload this single file. On the other Mac: open the dmg, drag LevelCode to"
   echo "[make-dmg]   Applications, then right-click > Open the first time (it's unnotarized)."