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.

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 (on wailsv3 — this branch's whole purpose): real-world dogfooding (logins, watchlist sync, error modals), then merge to main when Wails v3 hits stable.
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 — still v2, stable, ships 1.6.8 releases.
• wailsv3 — v3 desktop, unpushed until dogfooding passes, ahead of main by the commits above plus 2bf8d38 (frontend/package-lock.json) and efe45f3/a19080e/336a1f3 from the CI/cache work. Merge main forward before each v3 push.