Add a permanent, in-place backup of opensak.json before the macOS #825 migration touches it

[AgreeDK]

While following up on #867, a real macOS user (Mike, Sep 2026) reported that his fully-migrated opensak.json disappeared entirely after upgrading to 1.19.0 — not just the stale-path issue #867 fixed, but the entire settings file (username, home coordinates, etc.), even though nothing in migrate_macos_default_paths() should delete it outright.

Mike's own diagnosis (his words): "OpenSAK deleted [opensak.json] when the new version ran." He was only able to recover fully because he happened to have a Time Machine backup that included the hidden ~/.local/share/opensak/ path — his other backup methods (Syncthing, iDrive) didn't cover it.

We have not yet root-caused why the migrated file went missing — the file-move logic itself was traced step-by-step and behaves correctly for his scenario in isolation, so something after a successful migration is the more likely culprit (e.g. a second run under different conditions). That investigation is ongoing and needs real macOS hardware to pursue properly (see #867's discussion).

What this issue covers

Independent of root-causing the disappearance, there's no reason a user should ever need a system backup to recover from it: the migration already has the original file in hand for a brief moment before it does anything destructive. This issue is about making that moment count.

Fix implemented

Before migrate_macos_default_paths() moves or touches anything, it now leaves a permanent copy of the original opensak.json behind, in place, in the old directory (opensak.json.pre-825-migration-backup) — explicitly excluded from the move/cleanup logic so it can never be swept away by the same process, or by whatever happens afterward. Idempotent (won't overwrite an existing backup on a second/interrupted run). Scoped to opensak.json only (typically <1MB) — not database files, which are already handled by the existing move logic and can be far larger.

Testing

Reproduced Mike's scenario end-to-end, including simulating the migrated copy being lost afterward — confirmed the backup survives untouched
Full unit suite: 3270 passed; mypy clean across 229 files
4 new dedicated tests for the backup helper, plus one existing test updated (it previously asserted the old directory gets fully removed once empty — that's now intentionally no longer the case, since the backup keeps it non-empty)

Not covered by this issue — tracked separately once we have real hardware to investigate: the actual root cause of why the settings file disappeared for Mike in the first place.

[AgreeDK]

Reproduced this on real Mac hardware (Mac mini M1, macOS, fresh install) and found solid evidence pointing at a specific failure point.

Setup used to reproduce:

1. Installed v1.18.0 (pre-macOS: fix data-path bug in settings_store.py (writes to wrong directory) #825-fix) on a clean macOS user account.
2. Created a database and moved it to a custom location (Documents), matching the original reporter's setup. Left Default.db untouched in the default location. Entered geocacher name + home coordinates.
3. Quit, then installed v1.19.0 directly on top (the exact version the original report was on).
4. On first launch, got the same symptom: prompted for name/home location again, as if brand new.

Evidence: file timestamps in the new install dir

Sep 17 06:35:38  Default.db          <- original mtime preserved (correctly moved)
Sep 17 07:47:08  Default.db-shm/-wal <- expected, regenerated on every DB open
Sep 17 07:47:08  opensak.json        <- matches migration run time exactly, NOT preserved

Default.db kept its original modification time from earlier in the day, confirming shutil.move() correctly preserved it during migration. opensak.json, by contrast, has a timestamp matching the exact moment migration ran — not an earlier one. That's consistent with the file being freshly created (by SettingsStore._load() finding nothing at the destination), not moved.

Root cause hypothesis

In migrate_macos_default_paths(), the move loop iterates old_default_install.iterdir() and does shutil.move(entry, target) per file, catching OSError and only print()-ing it (not going through logger, so it never shows up in opensak.log). If shutil.move() fails specifically for opensak.json (permissions, or some macOS-specific I/O quirk — haven't pinned down the exact OSError yet), the original file would be left behind in the old directory, and the migration would silently continue. Separately, setup_logging() calls get_install_dir() (via get_log_path() → get_app_data_dir()) before migrate_macos_default_paths() runs, which means the new install dir already exists (and a fresh opensak.log is already being written into it) by the time migration's collision-skip logic runs — that part's confirmed to cause the old log to be skipped, though it doesn't by itself explain the opensak.json behavior.

I wasn't able to catch the actual OSError message from static code reading alone — worth adding a logger.warning() (not just print()) around that specific shutil.move() call so the real exception surfaces in opensak.log next time this happens, rather than reasoning from timestamps after the fact.

Suggested next steps

• Change the except OSError as exc branch in the migration's move loop to logger.warning(...) in addition to (or instead of) print(...), so the actual error is captured.
• Once that's in a build, reproduce again with the same steps above — should give the exact OSError this time instead of just timestamps.
• Worth checking specifically whether it's something about the filename opensak.json (e.g. concurrent open by another process at that exact moment, since it's the file the app itself is about to read right after) vs. general permissions, since Default.db moved fine in the same loop, same iteration, same permissions context.