Version the settings file so it can be upgraded

The schema is the single source of truth for what a setting IS. It cannot express what a setting USED to be -- and renaming a key, changing its units, or splitting one setting into two all leave a stored value the new schema does not recognise. Unrecognised keys are deliberately carried through untouched so that rolling back to an older Panama does not discard a newer version's settings, which means the user's choice silently stops taking effect with nothing to explain it. settings.json now carries a schemaVersion, and load() runs every pending migration before anything reads a value. The list is empty: the point is that the first breaking schema change becomes a routine edit rather than an emergency, and Omarchy carries eighty of these. The behaviours that make it safe to run against a real user's file: A file with no schemaVersion predates this and is STAMPED, not migrated -- running the list against it would apply upgrades designed for schemas it never had. A file from a NEWER Panama is left completely alone. Downgrading keys is not something this can do correctly, and unknown keys already survive, so an older build simply ignores what it does not understand. A step that throws stops at the last good version. Skipping past it would lose that conversion forever; failing the whole load would cost the user every setting. The list being empty is exactly why this is tested now: the first time it runs for real will be against somebody's actual settings during an upgrade, which is a poor moment to find out how it behaves. The harness supplies fixture steps including one that throws, and the contract pins all four behaviours above plus the promise that unknown keys survive. One thing the contract earned its place on: stamping a pre-versioning file changes it without running any step, so writing only on "migrated" left the stamp in memory to be redone on every launch. It now writes whenever the version moves, and explicitly does not write a file from the future. Claude-Session: https://claude.ai/code/session_01BRvzt4H8XXLPVH5MyYdk9L
2026-08-18 10:59:34 -04:00
parent 4279da999a
commit b16834fea6
5 changed files with 270 additions and 1 deletions
@@ -0,0 +1,56 @@
+// Exercises Migrations.applyWith against fixture steps and prints a verdict per
+// case. Run by tests/quickshell/migrations-contract.sh.
+//
+// Fixture steps rather than the real list: the real one is empty until the
+// first breaking schema change, and a mechanism that has never been run against
+// a failing step is not one to discover the behaviour of during an upgrade.
+
+import Quickshell
+import QtQuick
+import qs.config
+
+ShellRoot {
+    Component.onCompleted: {
+        const steps = [
+            { version: 2, describe: "add b", migrate: v => { v.b = (v.a ?? 0) + 1; return v; } },
+            { version: 3, describe: "add c", migrate: v => { v.c = "three"; return v; } },
+            { version: 4, describe: "explode", migrate: v => { throw new Error("boom"); } }
+        ];
+        const results = {};
+
+        // No version at all: a file written before versioning. Stamped, never
+        // migrated.
+        let r = Migrations.applyWith({ a: 1 }, steps, 3, 1);
+        results.unversioned = { v: r.values.schemaVersion, migrated: r.migrated,
+                                changed: r.changed, untouched: r.values.b === undefined };
+
+        // Older file: every step above its version runs, in order.
+        r = Migrations.applyWith({ a: 1, schemaVersion: 1 }, steps, 3, 1);
+        results.upgrade = { v: r.values.schemaVersion, b: r.values.b, c: r.values.c,
+                            count: r.applied.length, migrated: r.migrated };
+
+        // Already current: nothing runs.
+        r = Migrations.applyWith({ schemaVersion: 3, keep: "me" }, steps, 3, 1);
+        results.current = { v: r.values.schemaVersion, migrated: r.migrated,
+                            kept: r.values.keep === "me", b: r.values.b === undefined };
+
+        // From the future: left completely alone, including its unknown keys.
+        r = Migrations.applyWith({ schemaVersion: 9, futureKey: "x" }, steps, 3, 1);
+        results.future = { v: r.values.schemaVersion, migrated: r.migrated,
+                           changed: r.changed, kept: r.values.futureKey === "x" };
+
+        // A failing step stops at the last good version rather than losing the
+        // file or skipping past the failure forever.
+        r = Migrations.applyWith({ schemaVersion: 1, a: 5 }, steps, 4, 1);
+        results.failure = { v: r.values.schemaVersion, b: r.values.b, c: r.values.c,
+                            kept: r.values.a === 5, count: r.applied.length };
+
+        // Unknown keys survive a migration: rolling back to an older Panama
+        // must not discard a newer version's settings.
+        r = Migrations.applyWith({ schemaVersion: 1, unknownFromFuture: true }, steps, 3, 1);
+        results.preserved = { kept: r.values.unknownFromFuture === true };
+
+        console.info("PANAMA-MIGRATIONS " + JSON.stringify(results));
+        Qt.callLater(() => Qt.quit());
+    }
+}