Setup and restore wizards
Goal: a stranger installs Lifeboat, clicks through a few standard GNOME screens and is backed up, with no rclone, no TOML. On a new laptop the same app brings everything back. Screens follow the mockups (~/.lavish/lifeboat-mockups.html), rebuilt with stock libadwaita widgets the way Pika Backup and Secrets do it.
How it fits together
All decisions and rclone calls live in a new GTK-free module, so the CLI could grow lifeboat setup later and tests run in CI without a display. The wizard is a thin view.
One account, several laptops
Each laptop gets its own folder, Lifeboat/<device>/ (device = host name, editable in setup), with its own manifest.json. Encrypted data lives under Lifeboat/secure/<device>/ behind one passphrase per Google account. Without this, a second laptop's daily sync would move the first laptop's files into old versions and prune would delete them. Your current hand-made layout (Lifeboat/Documents) keeps working; the wizard only ever creates the per-device layout.
After sign-in, setup always looks for existing manifests. If any exist it asks: Restore from <device> or Add this laptop (asks for the existing passphrase and checks it, never mints a second one).
The flows (GNOME patterns)
Setup — shown instead of "Create example config"
- Welcome StatusPage: "Set up backup" (suggested, pill) / "Restore from a backup".
- Sign in: button opens Google in the browser (Gtk.UriLauncher); spinner + Cancel while waiting; Banner on failure or timeout.
- What to back up: SwitchRows for XDG folders with sizes (computed in a thread), "Keys and secrets" (
~/.ssh,~/.gnupg, always encrypted), "Add a folder…" (FileDialog). Daily time ComboRow. - Recovery kit: generated passphrase (6×5 chars), Save PDF (outside backed-up folders; the kit name is excluded from every job) / Copy (clipboard cleared after 30 s), "I've stored it" check enables Next. The kit also lists the client ID and manual-decrypt steps, so the backup stays readable even if Lifeboat or its Google project disappears.
- Backing up: progress dialog (existing stream view), then "You're covered" StatusPage. Timer installed.
Restore — from Welcome or the Restore page
- Sign in (same as setup).
- Found a backup: reads
Lifeboat/.lifeboat/manifest.json(host name, last run, jobs). None found → StatusPage explaining why. - Passphrase: PasswordEntryRow; checked by reading a probe file through the crypt remote (a wrong one fails clearly — rclone's root listing would wrongly succeed).
- Choose what to restore: CheckButton rows per job, target = original folders. Restore never deletes and never overwrites a newer local file (
--update);~/.sshand~/.gnupgget 700/600 permissions back (Drive does not store them). - Restoring → "All done", config + remotes written so backups continue on this laptop.
Build slices
| # | Slice | Ships as | Test |
|---|---|---|---|
| 0 | Ubuntu 24.04 fix: spinner fallback, README states libadwaita ≥ 1.5 | shipped as 0.3.2 | unit test + e2e |
| 1 | Real Google login first (you, ~5 min, into a throwaway Drive folder): capture rclone's real sign-in output as a test fixture | — | fixture file |
| 2 | Per-device layout + manifest + probe file, written each run | feat: | engine tests with local remotes, two "devices" |
| 3 | setup.py: sign-in (drive.file forced, parse URL + token from the fixture, cancel, timeout, port busy), discovery, remotes, folder suggestions, config writer, passphrase check, restore with --update + permissions, PDF kit | feat: | fake rclone for sign-in; real rclone with local + crypt remotes for the rest |
| 4 | Setup wizard UI (incl. "Add this laptop" branch) | feat: | Broadway walk-through with browser and file picker stubbed |
| 5 | Restore wizard UI | feat: | same, plus wrong passphrase and two-device paths |
| 6 | End-to-end on your account in the throwaway folder, then release 0.4.0 | release PR | scripted checklist |
Fable audits slices 1–2 (they touch remotes, secrets and your Drive) and the finished UI before the release. Your real setup is never touched by tests: everything runs in throwaway HOMEs; the real-login check uses a Drive folder named Lifeboat-test.
Risks and guards
| Risk | Guard |
|---|---|
| rclone's default sign-in asks for full Drive access | Force drive.file via env; a test asserts the scope in the auth URL |
Token output format of rclone authorize not yet seen with a real login | Parser tolerant to the documented block; slice 5 verifies before release |
| Fixed callback port 53682 (another rclone sign-in running) | Detect, show "close the other sign-in and retry" |
| drive.file only sees files made by this exact client ID — changing it orphans every backup | Client ID is a constant with a "never change" comment; maintainer note in CONTRIBUTING |
| Your Google project lost or deleted → nobody can read their backup through Lifeboat | Second project owner + deletion lien (you, 5 min in Cloud Console); recovery kit lists the client ID and a "download from drive.google.com, decrypt locally with rclone + passphrase" path, which works even without the project |
| Wrong passphrase looks OK at the crypt root | Probe file check |
| pycairo missing on Debian/Ubuntu/Arch | Stdlib PDF writer, no dependency |
| Wizard run on a laptop that already has a config (like yours) | Wizard only appears when there is no config; never overwrites one |
| Two laptops on one account delete each other's files | Per-device folders and manifests (see above) |
| "Set up" on an account that already has backups mints a second passphrase | Discovery after sign-in; "Add this laptop" reuses and verifies the existing one |
| Recovery kit backed up in plain text, or left in clipboard history | Kit file excluded from all jobs; clipboard cleared after 30 s |
Restore overwrites newer files or breaks ~/.ssh | --update; permissions fixed after restore |
Decisions (made by Fable on the owner's request, 2026-10-23)
| Decision | Pick | Why / condition |
|---|---|---|
| Google client | Ship the lifeboat-app client ID + secret in the code | Installed-app secrets aren't confidential; drive.file needs no Google verification. Constant marked "never change"; never rotate the secret in Cloud Console (it would orphan every backup). |
| Ubuntu 24.04 | Keep supporting it | Spinner fallback shipped in 0.3.2; every wizard widget exists in libadwaita 1.5. CI runs on ubuntu-latest (24.04). |
| "Settings" row | Leave out of v1 | A partial dotfile list under-delivers on the word "Settings"; restoring ~/.config across app versions is untested. Revisit in 0.5 with the list visible in the UI. |
Owner, before release: the 5-minute Google login (slice 1), and a second owner + deletion lien on project lifeboat-app.