[analysis] Auto-update mekanizması — mevcut yapıya entegrasyon ve aşamalı plan

[mertbekci]

Özet

Scrapeman v0.2.0'a kadar her release manuel indirme ile yayılıyor. Kullanıcı yeni sürümü öğrenmek için ya GitHub Releases sayfasına bakmak ya da bizim başka bir kanaldan duyurmamız gerekiyor. Bu issue, mevcut yapıya otomatik güncelleme nasıl eklenir sorusuna mühendislik + PM gözüyle cevap veriyor ve aşamalı bir yol haritası öneriyor.

Mevcut yapı — durum tespiti

Bileşen	Durum
Build	electron-builder@25 — macOS dmg (arm64+x64), Windows NSIS (x64), Linux AppImage + deb (x64)
Release flow	.github/workflows/release.yml — tag-driven (v*.*.*), softprops/action-gh-release ile GitHub Releases'e upload
publish config	publish: null — electron-builder update metadata üretmiyor
DMG update info	dmg.writeUpdateInfo: false
macOS signing	identity: null — afterPack hook'unda codesign --force --deep --sign - ile ad-hoc (Developer ID yok, notarize yok)
Windows signing	signAndEditExecutable: false — imzasız, SmartScreen her yüklemede uyarı
Linux	AppImage ve deb imzasız
electron-updater dep	Yüklü değil
Repo görünürlük	Private (auto-update için kritik — aşağıda)

Auto-update seçenekleri

A. `electron-updater` + GitHub Releases (standart yol)

• `electron-builder.yml`'ye `publish: github` ekleyince her build'de `latest-mac.yml` / `latest.yml` / `latest-linux.yml` manifesti üretilir (SHA512 + boyut + URL).
• Main process'te `autoUpdater.checkForUpdatesAndNotify()` GitHub Releases'i polling eder, delta indirir, prompt eder.
• Blocker: repo private. electron-updater private repo'ya erişmek için `GH_TOKEN` istiyor — token'ı app'e bundle etmek credential leak. Çözümler: (1) repo public, (2) release'leri public kanalda ayna tut, (3) self-hosted update server front-end'i.

B. Self-hosted update server (Hazel / Nuts benzeri)

• Private repo'dan release'leri token ile çekip anonim indirim kanalı sunar.
• Ops yükü + bir başka servis ayakta tutmak gerek. Scrapeman ölçeğinde overkill.

C. Manuel check + banner (no binary swap)

• Uygulama açılışta GitHub Releases API'sine hit atıp `latest` tag'ini okur. Mevcut `app.getVersion()` ile kıyaslar.
• Yeni versiyon varsa: header / status bar'da dismissable banner + "Download" butonu — browser'da Releases sayfası açılır.
• Binary indirmez, signing gerektirmez, private repo için bile kullanıcıya token input'u ile çalıştırılabilir.
• En düşük maliyetli MVP.

Kritik kısıtlar — neden bugün tam auto-update yapamıyoruz

1. macOS Squirrel signing şart. Ad-hoc imza notarize olmadığından Squirrel.Mac updater çalışmaz; güncelleme signature match doğrulamasında fail eder. Auto-update için Apple Developer ID cert ($99/yıl) + notarization şart.
2. Windows NSIS teknik olarak çalışır ama her yeni versiyon SmartScreen "unknown publisher" uyarısı gösterir — kullanıcı deneyimi bozuk. EV cert ile reputation oluşturmak haftalar alır.
3. Linux AppImage auto-update sorunsuz — electron-updater native destekliyor, imza gerekmiyor.
4. Linux deb auto-update mümkün değil — APT repo kurmadan kullanıcılar `dpkg -i` ile reinstall etmeli. Deb kullanıcıları için manuel kalıyor.
5. Private repo. Yukarıda açıklandı.

Önerilen aşamalı plan

🟢 Phase 1 — Manual check + banner (v0.3.0, ~1-2 gün)

• Main process `app-ready` event'inde `https://api.github.com/repos/scrape-do/scrapeman/releases/latest\` çağrısı.
• Private repo ise kullanıcıdan Settings panelinde "GitHub token (optional)" alanı alınır; yoksa 404 al → sessizce geç.
• Renderer'da banner component: "v0.X.Y available — [Download] [Dismiss]".
• Click → `shell.openExternal` ile release sayfası.
• Check cadence: açılışta 1 kez + 4 saatte bir periodic.
• User-facing setting: "Check for updates automatically" toggle.
• Kod signing gerektirmez, mevcut build pipeline'ına hiçbir değişiklik gerekmez.

🟡 Phase 2 — Linux AppImage auto-update (v0.4.0, ~2-3 gün)

• `electron-updater` paketini ekle.
• `electron-builder.yml`: `publish: github` (provider) + `dmg/nsis/appimage` için update metadata üret.
• Release workflow'a `GH_TOKEN` ile asset upload eklenir (zaten `GITHUB_TOKEN` mevcut).
• Main process'te Linux platform check → AppImage kullanıcıları için `autoUpdater` akışı, mac/win için Phase 1 banner devam eder.
• Blocker: repo private. Bu aşamada public'e taşıma veya self-hosted proxy kararı gerek.

🟠 Phase 3 — Windows NSIS auto-update (v0.5.0, ~1-2 gün)

• electron-updater NSIS target native çalışır.
• SmartScreen uyarısını kabul ediyoruz (EV cert ileri bir milestone).
• Delta download (blockmap) açık tutulur, update paketleri küçülür.

🔴 Phase 4 — macOS auto-update (v1.0, ~1 gün kod + haftalar kurulum)

• Ön koşullar: Apple Developer ID sertifikası + notarize akışı (Phase 4.0 = signing milestone).
• Sonra electron-updater Squirrel.Mac + `publish: github` otomatik çalışır.
• Opsiyonel: Homebrew Cask recipe paralelde — `brew upgrade --cask scrapeman` kullanıcılar için otomatik.

Riskler ve açık sorular

• Version rollback stratejisi. Bozuk bir release çıkarsa: GitHub Release'i `prerelease` işaretleriz, electron-updater default olarak pre-release'leri atlar. Dokümante etmek lazım.
• Workspace format migration. `.req.yaml` format'ında breaking change olursa FORMAT_VERSION zaten var (`packages/shared-types/src/index.ts`). Auto-update öncesinde migration planlamak gerek — eski versiyonun yeni format'ı kırmaması için.
• Check endpoint rate limit. Anon GitHub API 60 req/h. 10k+ kullanıcıda yetmez → ya token gerektir ya da Cloudflare cache'li basit bir JSON endpoint (GitHub Pages + workflow).
• Delta download boyutu. electron-builder blockmap üretince ~200KB-2MB delta yeterli; full dmg ~120MB. Blockmap'leri release'e dahil etmek zorundayız (zaten upload path'te var).
• User-controlled update channel. Power user'lar için "beta channel" opsiyonu (`prerelease`) + stable channel ayrımı.

Dokunulacak dosyalar (Phase 1 için)

• `apps/desktop/src/main/updater.ts` — yeni — GitHub Releases API check
• `apps/desktop/src/main/index.ts` — app.whenReady içine updater init
• `apps/desktop/src/preload/index.ts` — bridge: `onUpdateAvailable`, `dismissUpdate`, `openReleasePage`
• `packages/shared-types/src/index.ts` — `ScrapemanBridge` + `UpdateInfo` tipi
• `apps/desktop/src/renderer/src/components/UpdateBanner.tsx` — yeni
• `apps/desktop/src/renderer/src/App.tsx` — banner mount
• `apps/desktop/src/renderer/src/store.ts` — `updateInfo` slice + dismissed flag
• `apps/desktop/src/renderer/src/components/SettingsDialog.tsx` — "Check for updates automatically" toggle + optional token alanı

Success criteria

• Phase 1: v0.3.0 launch sonrası kullanıcı uygulamayı açtığında v0.3.1 release'i 30 sn içinde banner olarak görüyor.
• Banner dismiss'i kalıcı (aynı version için bir daha gösterilmiyor).
• Settings'te toggle ile kapatılabiliyor.
• Private repo durumunda graceful fallback — hata ile crash etmiyor.
• Rate limit aşılırsa 1 saat backoff.

Milestone fit

• M10 release polish — auto-update bu milestone'un merkezi.
• Phase 1 hemen implement edilebilir (bugünkü session'da), Phase 2-4 signing/public release kararlarına bağlı.

Öneri

Phase 1'i şimdi kapatalım — düşük maliyet, yüksek değer, mevcut yapıyla tam uyumlu. Phase 2+ için signing/repo visibility kararını ayrı bir issue'da tartışalım (Apple Developer hesabı + repo public geçiş yol haritası).

[mertbekci]

Triage — Phase 1 shipped, Phase 2-4 açık

apps/desktop/src/main/updater.ts + UpdateBanner.tsx commit 408819d ile merge edildi. Phase 1 (manuel check + banner) v0.2.x'te canlıda.

Kalan phase'ler bu issue altında kalsın:

• 🟡 Phase 2 — Linux AppImage auto-update (electron-updater, repo public geçiş bekliyor)
• 🔴 Phase 3 — Windows NSIS auto-update (imza opsiyonel, SmartScreen uyarısıyla çalışır)
• 🔴 Phase 4 — macOS auto-update (Apple Developer ID + notarize — infra iş)

Phase 2-4 dispatch'e hazır değil (dev task değil — infra + signing + repo visibility kararları). Issue açık kalır, roadmap tracker.

[mertbekci]

Phase 1 — shipped ✓

Manual check + banner flow is live in main:

• apps/desktop/src/main/updater.ts polls GitHub Releases on app ready + every 4 h.
• apps/desktop/src/renderer/src/components/UpdateBanner.tsx renders the 'vX.Y.Z available — Download / Dismiss' banner on top of the tab bar.
• Bridge wires onUpdateAvailable, dismissUpdate, openReleasePage (apps/desktop/src/preload/index.ts).
• Settings toggle for 'Check for updates automatically' is in place.

Released across v0.3.x–v0.4.0.

Remaining

Issue stays open to track Phase 2–4:

• Phase 2 (Linux AppImage electron-updater)
• Phase 3 (Windows NSIS electron-updater)
• Phase 4 (macOS Developer ID + notarize + Squirrel.Mac)

Needs a decision on whether the repo moves to public or we stand up a self-hosted proxy before Phase 2 starts.