[Epic] Installation, Uninstallation & Auto-Upgrade (Roadmap #1)

[AgreeDK]

Placeholder/tracking issue for roadmap item 1: a clean install/uninstall path on
every platform (Windows, macOS, Linux), plus automatic upgrade to new versions
(user-selectable). On uninstall, data/database removal must always be an explicit
opt-in action — never the default.

This issue tracks the overall scope and links to the individual implementation
issues below, which will be filed one at a time as work on each begins.

Background/proposal doc: see install-uninstall-upgrade-proposal.md (shared
internally, based on the platform-by-platform review with Fabio).

Note: the numbering below (1–7) is just an internal reference label for each
step, not a priority order — see "Suggested order" below for that, and feel free
to renumber if it's clearer to do so once issues start getting filed.

Steps

• 1. macOS: fix data-path bug in settings_store.py
os.name currently branches the same way on Linux and macOS (both "posix"),
  so app data lands in ~/.config / ~/.local/share instead of the intended
  ~/Library/Application Support/opensak. Needs a darwin-specific branch plus a
  migration step for existing users' data. Blocks step 4.

• 2. Windows: version-mapping scheme for beta releases (effectively done — verify and land)
  Already implemented on feature/msix-packaging: scripts/derive_msix_version.py
  converts __version__ to a valid 4-part MSIX version (e.g. 1.17.2-beta.3 →
  1.17.2003.0), with revision always 0 (a real Partner Center submission
  rejected non-zero revisions on 27 Aug 2026) and patch+beta folded into the
  Build component instead. 12 unit tests, already wired into
  build-msix.yml's "Determine MSIX version" step. Remaining work: fix a
  stale line in packaging/msix/README.md ("beta number becomes the
  revision" — no longer true, contradicts the script's own docstring) once
  this branch lands on beta. No new design work needed.

• 3. Windows: empirical verification pass for Implement MSIX packaging and Microsoft Store distribution #786 (done — found a real bug, tracked as MSIX/Store build: database path shown to user doesn't match actual file location #820)
  This verification already happened: a private Partner Center submission
  (25 Aug 2026) passed Store certification and installed successfully via
  the Store app. However, it also surfaced a real issue, not just a
  formality: Windows applies automatic filesystem virtualization to
  MSIX/Desktop Bridge apps writing to %AppData%/%LocalAppData% —
  independent of which API is used (this applies even to plain Win32 file
  I/O, not just the UWP ApplicationData API). OpenSAK's displayed
  database path doesn't match where Windows actually stores the file. See
  MSIX/Store build: database path shown to user doesn't match actual file location #820 for the confirmed root cause and proposed two-part fix (show the
  real physical path; default new MSIX installs to Documents\OpenSAK\
  instead of %AppData%). This issue is the empirical verification
  finding for this step — no separate verification issue needed, just
  MSIX/Store build: database path shown to user doesn't match actual file location #820 getting implemented.

• 4. macOS: uninstall helper
  App bundle removal + explicit opt-in prompt for deleting Application
  Support data/databases (default: no). Depends on step 1.

• 5. macOS: Sparkle integration for auto-upgrade
  Appcast feed, EdDSA signing key (separate from the Developer ID cert),
  update-channel support (stable/beta). Net-new work, no existing integration.

• 6. Linux: self-administration (redesigned — no terminal, no AppImageUpdate) — Done, shipped in v1.19.0-beta.3.
  Original plan (external uninstall.sh + AppImageUpdate) had an internal
  contradiction — a separate uninstall script still requires opening a
  terminal, undermining the terminal-free goal — and AppImageUpdate/zsync
  was heavier than actually needed. Redesigned and implemented directly in
  OpenSAK's own Python code instead:

  • Self-integration on first run (Linux AppImage: self-integration on first run #835) — offers to install itself into
    the application menu; manual trigger also added under Settings →
    Advanced so declining once isn't a dead end.
  • Self-update (Linux AppImage: self-update #836) — in-app "Upgrade now": full download, ELF-magic
    validation, atomic replace. No zsync/AppImageUpdate dependency.
  • In-app uninstall (Linux AppImage: in-app uninstall #837) — remove-only vs. remove-and-purge-data
    choice, using the exact paths settings_store tracks (no guessing).

• 7. Coordinate shared update-check with platform-native auto-update flows
  updater.py already implements a working cross-platform "check for updates"
  flow (background + manual check, beta-notify setting, skip-version, changelog
  link) — this already works today, nothing to build here. What's needed once
  Sparkle (macOS) and AppImageUpdate (Linux) land is to avoid duplicate update
  notifications, by deciding per platform which mechanism is authoritative and
  detecting the running build variant at runtime. Should be finalized after
  steps 5 and 6 have a working prototype. Related: Auto-detect and auto-download correct update asset (no code signing required) #572 (auto-download UX,
  separate issue, not superseded by this), MSIX/Store build: database path shown to user doesn't match actual file location #820 (Windows build-variant context).

Suggested order

Based on dependencies and available time, not a hard requirement. Revised: steps
2 and 3 turned out to be already resolved or redirected during investigation (see
their updated descriptions above), which frees up time for the remaining steps.

1. Step 1 — macOS path fix + migration. In progress: fix implemented and
   merged, awaiting Fabio's manual verification on real hardware (see macOS: fix data-path bug in settings_store.py (writes to wrong directory) #825).
   Blocks steps 4 and 5, so worth confirming before moving on to those.
2. MSIX/Store build: database path shown to user doesn't match actual file location #820 (was step 3) — Windows MSIX database path virtualization bug. Real,
   confirmed issue with a clear two-part fix already scoped. Independent of
   step 1, can start any time.
3. Step 2 doc fix — correct the stale version-numbering line in
   packaging/msix/README.md. Trivial, can be folded into whichever PR touches
   that branch next (e.g. alongside MSIX/Store build: database path shown to user doesn't match actual file location #820 or the feature/msix-packaging merge).
4. Step 6 — Linux uninstall script + AppImageUpdate Done
   (redesigned as self-integration/-update/-uninstall, Linux AppImage: self-integration on first run #835/Linux AppImage: self-update #836/Linux AppImage: in-app uninstall #837,
   shipped in v1.19.0-beta.3).
5. Step 4 — macOS uninstall helper. After step 1 is confirmed working.
6. Step 5 — Sparkle integration. Largest single piece of work; where
   Fabio's testing on real hardware adds the most value along the way.
7. Step 7 — coordinate shared update-check with platform-native flows.
   Needs working prototypes of steps 5 and 6 first to know what it's
   coordinating against.

Notes

• Individual issues will be filed with full detail as work on each step starts.