[hahn-kev-bot]

---

AI summary

Fixes #1391 for Windows. MSIX installs kept projects in the package's LocalState, and Windows deletes that folder on uninstall. Builds on the Harmony update in #2788 (merged).

Summary

 %LOCALAPPDATA%\Packages\FwLiteDesktop_<hash>\LocalState\   (deleted on uninstall)
   app.log, msal.cache                       # stays here
-  example.sqlite
-  localResourcesCache\example\…
-  failedSyncs\
+  example.sqlite.migrated                   # retired after a verified copy
+C:\ProgramData\SIL\FieldWorks Lite\<user>\   (MSIX doesn't virtualize ProgramData; survives uninstall)
+  projects\example\example.sqlite
+  localResourcesCache\example\…
+  failedSyncs\
+  fwlite-data-migration.json                # marker

One-time migration at startup (ProjectDataFolderMigration), resolved before any project path is used:

TryMigrate(LocalState, ProgramData\…\<user>)
  marker present                          -> use new root
  take migration lock (no timeout)
  take exclusive legacy lease             -> fails if another instance still runs on LocalState -> stay on legacy
  copy to <user>.migrating-<guid>
    media + failedSyncs (size-checked)
    each db: SQLite backup API (includes WAL) -> rewrite LocalResource.LocalPath prefix
             -> quick_check + per-table row counts + every referenced media file exists
  write marker, Directory.Move(staging, target)   # single commit point
  rename legacy *.sqlite -> *.sqlite.migrated     # a stale copy can't sync under the same ClientId
  any failure -> stay on LocalState (holding a shared lease), retry next start

• LcmCrdtConfig.UseProjectFolders: new projects go in projects/{code}/{code}.sqlite. Discovery always finds both layouts, and the folder wins on a duplicate code. Only Windows MSIX turns it on, so other platforms, FwLiteWeb and Platform.Bible are unchanged.
• FwLiteMauiConfig.ProjectDataDir defaults to ProgramData on packaged Windows unless BaseDataDir is overridden. Troubleshooting's "data folder" now opens the project root.
• No startup-task mechanism (Startup tasks #1949) needed: this is a file copy before the app opens any project, not an in-database task.

Evidence

• Unit tests (LcmCrdt.Tests): ProjectFolderLayoutTests (7) and ProjectDataFolderMigrationTests (10).
  • A real example project with saved media migrates. Entries and media are readable from the new root, and the legacy files are unchanged apart from the rename.
  • Covered: changes still in the WAL are included; only cache paths are rewritten; a corrupt db fails cleanly; a target that wasn't created by a migration is left alone; a re-run is a no-op; a crash leftover is cleaned up; concurrent starts all land on the new root; an instance still on LocalState blocks the migration.
  • Mutation-checked: removing the path rewrite fails 2 tests, and removing the lease check fails the instance-blocking test.
• Manual MSIX check (Windows 11, harness identity FwLiteDesktopTest, so no real install was touched):
  • Before: a seeded flat project with media in LocalState.
  • After launch: the log says Migrated 1 projects from …\LocalState to C:\ProgramData\SIL\FieldWorks Lite\<user>. The files are visible from outside the package (not virtualized), the legacy db became .sqlite.migrated, the media path was rewritten, and the log has no errors. Creating an example project in-app wrote projects\example-project\example-project.sqlite.
  • After uninstall: the package folder is gone, and ProgramData kept both projects (quick_check ok, all entries present).

Merge Danger

Door: one-way, per user.

Once an install has migrated, an older build looks in LocalState, finds only .sqlite.migrated files and shows no projects. The data is intact, but a rollback would need a reverse migration or manual renames.

Blast Radius: Windows-MSIX.

Every MSIX user runs the migration on first start after updating.

• It runs synchronously with no progress UI, so a large media cache means a slow first launch.
• The folder is keyed by Windows user name, so renaming the account hides projects (they stay on disk).
• The marker is per user folder, not per package: a second package identity (e.g. a future beta channel) that migrates first would make production skip its own LocalState.
• Other local accounts can read the ProgramData folder (default ACL).

Test plan

• dotnet test backend/FwLite/LcmCrdt.Tests --filter "FullyQualifiedName~ProjectDataFolderMigrationTests|FullyQualifiedName~ProjectFolderLayoutTests|FullyQualifiedName~OpenProjectTests|FullyQualifiedName~MediaTests" (45 pass on develop)
• FwLiteMaui.Tests MauiTroubleshootingServiceTests; Windows MAUI head and FwLiteWeb build
• Manual MSIX install → migrate → create project → uninstall → ProgramData survives
• Upgrade an existing real install (release build → this build) and check its projects and media

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[hahn-kev]

what else is this used for now? It feels like it would be too easy to use the wrong data dir without guidance.

[hahn-kev-bot]

Now it only holds app-local state: app.log, msal.cache, the new fw-lite-settings.json from develop, and the WebView profile. It's also where the old flat projects sit until they're migrated. Projects, media and failed syncs moved to ProjectDataDir.

Agreed it was too easy to grab the wrong one, and ProjectDataDir is a trap too: it's the intended folder, but a failed migration falls back to BaseDataDir. In 8e833c5:

• Both properties now say what they're for, and ProjectDataDir says to read the folder in use from LcmCrdtConfig.ProjectPath / HarmonyConfig, never from the property.
• The kernel no longer keeps a baseDataPath local, so nothing invites reuse.
• The two-folder layout is in backend/FwLite/AGENTS.md and the troubleshooting guide.

If you'd rather the name carry it, I can rename the property to something like AppStateDir and keep BaseDataDir as the config key ([ConfigurationKeyName]), so env vars, CI and settings files keep working.

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
e2e (Inspect)	✅ No changes detected	-	Nov 6, 2026, 8:51 AM