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. Version flow: single source build/config.yml:info.version, make release bumps it and regenerates version.go (compiled-in copy) in the same commit — wails.json retired entirely (proof: wails3 build + wails3 dev both green without it; a first-boot dev failure turned out to be Vite 8 cold-start vs the app retry budget, fixed by rerunning warm, not by the file).
• .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: done on wailsv3 — Svelte 4.2 → 5.57, Vite 4.5 → 8.3, vite-plugin-svelte 2 → 7, Tailwind 3 → 4 (CSS-first), flowbite-svelte 0.46 → 1.33, router 4 → 5. svelte-check went 453 errors → 0/0; stores retyped to the generated bindings models; AnimeTable rewritten dependency-free (svelte-headless-table peers Svelte 4 only). Deliberately held: TypeScript at 5.9 (svelte-check peers ^5||^6), @wailsio/runtime pinned to the Go framework version (lockstep upgrades only).
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.