Anitrack/docs/V3_MIGRATION.md

AniTrack v3 Migration — What Changed and What's Next

This document summarizes the wailsv3 branch (Wails v2.15.0 → v3.0.0-beta.20, desktop-only) and the plan going forward. It’s written for a future me and for anyone following the migration.

What we did (desktop, no mobile yet)

Goal: get the existing app running on Wails v3 with the same structure and behavior — no rewrites of AniList / MAL / Simkl logic, no mobile, no stores.

Backend — single App service preserved:

• main.go: wails.Run(options.App{ Bind: app }) → application.New( Services: [app] ) + Window.NewWithOptions(...) + app.Run(). Same window (1024×768, title AniTrack <version>, RGBA background, Linux ProgramName/Icon/GpuPolicyNever), same SingleInstance lock/ID and onSecondInstanceLaunch (now SecondInstanceData{ Args, WorkingDir } + Window.Current().Restore/Focus + Event.Emit("launchArgs")).
• app.go: App now holds *application.App instead of a context. startup(ctx) / global wailsContext removed; version title moved into the window options. ShowVersion and the three OAuth callbacks now use app.Dialog.Info() / app.Browser.OpenURL() (errors logged, not ignored).
• AniListUserFunctions.go / MALUserFunctions.go / SimklUserFunctions.go: 11 runtime calls migrated (BrowserOpenURL ×3, MessageDialog ×3/4, EventsEmit ×1, window calls) to v3 managers (Browser, Dialog, Event, Window). OAuth servers on :6734/callback unchanged. Per-file key constants unchanged.

Secrets — 99designs/keyring → zalando/go-keyring:

• go.mod: wails/v2 + 99designs v1.2.2 dropped (stale replace removed), wails/v3 v3.0.0-beta.20 (pinned to the local wails3 CLI) + zalando v0.2.8 added — what v3 itself depends on.
• Same service name AniTrack and same 11 key names (anilist*, MyAnimeList*, Simkl*), so intent is the same wallet. On Linux the underlying collection differs (AniTrack vs login) — see “Stale keys” below — so first v3 run requires re-logging into the 3 services once.

Frontend — bindings + runtime:

• wails3 generate bindings → frontend/bindings/AniTrack/*.ts (1 service, 29 methods, 25 models), verified byte-deterministic. frontend/wailsjs/ removed. 10 Svelte files updated: wailsjs/go/main/App → bindings/AniTrack (App.* call prefixes), WebsiteLink.svelte → Browser.OpenURL, AvatarMenu.svelte → Application.Quit, both from @wailsio/runtime 3.0.0-beta.20.
• frontend/vite.config.ts: added @wailsio/runtime vite plugin (wails('./bindings')) + server.host/port/strictPort (5173). frontend/package.json: added build:dev (vite build --minify false --mode development, required by the v3 dev taskflow) and @wailsio/runtime dep.

Build + CI:

• Taskfile.yml + build/Taskfile.yml (stock common) + build/linux/Taskfile.yml (stock minus common:generate:icons — macOS/Windows icon generation targets build/appicon.png which this Linux-only project doesn’t have) + build/config.yml (AniTrack metadata, Version 1.6.8). Root output stays build/bin/AniTrack so release packaging is untouched. wails.json → v3 frontend block, info.productVersion retained.
• Makefile: wails dev/build -tags webkit2_41 → wails3 dev -port 5173 / wails3 build (no tags; v3 defaults to GTK4/WebKitGTK 6.0, same 2.52.x engine generation). Added .task/ to .gitignore. Removed build/darwin/, build/windows/, frontend/package.json.md5. make release bumps both wails.json and build/config.yml:info.version (TEMP until wails.json is retired).
• .gitea/workflows/release.yml: Wails CLI wails@v2.15.0 → wails3@v3.0.0-beta.20 (path + cache key), apt libgtk-3-dev/libwebkit2gtk-4.1-dev → libgtk-4-dev/libwebkitgtk-6.0-dev, make build unchanged. Go/npm/go-build/Wails-CLI caches remain valid (npm cache now resolves since frontend/package-lock.json is committed).

Verification: go vet clean, wails3 build green (build/bin/AniTrack ~13 MB), wails3 dev boots end-to-end (bindings regen → build:dev → vite on :5173 → Connected to frontend dev server → AniTrack 1.6.8 window), second instance exits 0 via the lock. svelte-check was already red on main (wailsjs/go/models.ts anonymous structs) and remains so — not introduced by the migration.

Commits on wailsv3: chore(wailsv3): migrate Go backend…, chore(wailsv3): migrate frontend…, chore(wailsv3): add v3 Taskfile…, ci(release): build releases with the Wails v3 toolchain, plus chore(wailsv3): v3 conformance pass….

Stale keys — what a v2 user will see

On Linux, v2 tokens lived in an AniTrack Secret Service collection as labeled JSON items; v3 (zalando) uses the login collection with service/username attributes. Same OS keyring, different collections — so after migrating, the old AniTrack collection is orphaned.

In practice: running both versions side-by-side works fine — each reads its own collection, neither overwrites the other. If you fully move to v3, just log into AniList / MAL / Simkl once there; the v2 entries become stale but harmless (11 small items). See the notice in README.md: Migrating from v2 — no automatic deletion, on purpose.

Self-updates (desktop Linux, 1.99.x)

Releases self-update in place via the Wails v3 updater (app.Updater): a custom Gitea provider (updater/gitea — Wails ships none for Gitea) checks the Gitea releases API, and CI publishes a signed bare-binary asset (AniTrack-linux-amd64 + .sha512/.sig sidecars from wails3 updater sign) next to the user tarball. Verification is fail-closed; a release missing any of the three files is skipped. Gated to desktop production builds (application.System.IsDesktop() + -tags production) — mobile stays on Obtainium, dev builds never check. The startup check is headless; the builtin window opens only when an update is found. ANITRACK_UPDATER_CHANNEL=beta includes -rc pre-releases (testing only). Only the binary self-swaps; icons/.desktop still come from the tarball's install_linux.sh. Signing: public half updater.pub is embedded; the private key lives in the password manager + the UPDATER_SIGNING_KEY CI secret, never in the repo (see .gitignore).

Future plans on v3

Not yet done — staged after the desktop migration, in order (each with its home branch, so nothing lands in the wrong place):

1. Stabilize desktop v3: real-world dogfooding of main (logins, watchlist sync, error modals). Merged to main as the 1.99.x beta series while Wails v3 is still beta upstream.
2. Frontend toolchain refresh (on wailsv3, before the merge): Svelte 4 → 5, Vite 4 → 8, vite-plugin-svelte 2 → 7, Tailwind 3 → 4 — majors deferred intentionally; they pair naturally with v3’s Svelte 5 templates and touch the same desktop files, so no separate branch.
3. Android (short-lived feature branch off wailsv3, e.g. wailsv3-android, merged back): personal sideload, no Play/official F-Droid. Per-file //go:build android shims — zalando → Android.Secure* (EncryptedSharedPreferences), and localhost:6734 OAuth callbacks → deep-link anitrack://callback + intent filter; start with one provider (AniList) to prove the pattern. Responsive / safe-area polish. Distribution via adb install + GitHub Releases + Obtainium. Kept off wailsv3 proper so the mobile scaffolding (build/android/, manifests, gradle files) doesn't pollute the desktop-to-main merge.
4. CI follow-ups (wherever the work they support lives): none required for desktop; the current 4 caches + the fixed runner cache backend already bring releases from ~12 min to ~3 min. Builder image only if the 2 min apt floor becomes annoying.

Branch map

• main — v3 desktop, ships 1.99.x beta-series releases.
• wailsv3 — retained as an alias tracking main for now.