@hank-warren/pi-statusline 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @hank-warren/pi-statusline
 
+## 0.4.2
+
+### Patch Changes
+
+- 1e25d6b: Guard against a setting being added without being registered for persistence. `SETTING_KEYS` feeds the per-key diff behind every save, so a key missing from it applied live and then silently failed to persist. Omitting one is now a `tsc` error naming the key, plus a test asserting the list matches `defaultSettings()`. Adds an "Adding a setting" checklist and the cross-version compatibility rules to the README.
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -30,6 +30,26 @@ Settings live in a single global file, `~/.pi/agent/statusline-settings.json`, w
 
 Saves are per-key rather than whole-file: a change writes only the fields it actually touched over whatever is on disk at that moment. Sessions load settings once at startup, so a whole-file write would let a session that started hours ago revert edits it never saw — including hand edits and changes made in another session. Opening `/statusline` also re-reads the file first, so the menu always edits current state. Two sessions changing the *same* field are still last-writer-wins; everything else merges.
 
+### Adding a setting
+
+A setting is persisted, validated, diffed, and rendered in separate places, so add it to all of them:
+
+1. `StatuslineSettings` in `settings.ts` — plus `BOOLEAN_SETTING_KEYS` if it is a toggle.
+2. `defaultSettings()`.
+3. `normalizeSettings()` — the `known` key set, and a parse branch that falls back to the default for an invalid value rather than discarding the whole file.
+4. `serializeSettings()` — write it only when it differs from its default, keeping the file sparse.
+5. `SETTING_KEYS`.
+6. A row in `buildSettingItems()` and a branch in `applySettingChange()` in `settings-menu.ts`, placed in the order the element renders.
+7. Live-apply handling in `applySettings()` in `index.ts`, if the change needs more than a repaint (disposing a poller, forcing a full redraw on a row-count change).
+
+Steps 1 and 5 are enforced: omitting the key from `SETTING_KEYS` fails `npm run typecheck` by name, and a test asserts it matches the keys of `defaultSettings()`. Nothing enforces steps 3, 4, 6 or 7 — a setting missing from `serializeSettings` applies live and never persists.
+
+Compatibility rules, because old and new versions share one file:
+
+- **Never change a key's type or meaning — add a sibling key.** This is why `showCacheCelebration` stayed a boolean when it gained animation styles: an older version reading a repurposed key falls back to its default and can write that fallback back.
+- **Unknown keys survive an older version; unknown *values* do not.** A theme name a reader does not recognise falls back to `default`, and a whole-file write from that reader drops the choice. Extending a cosmetic enum is fine; encoding behaviour in one is riskier than adding a key.
+- **Keep settings independent.** Per-key saves mean two fields can be written by different sessions at different times, so resolve any relationship between settings at render time, not on disk.
+
 ## Themes
 
 | Name | Notes |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-statusline",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Compact Pi footer statusline with Git/worktree context, token usage, and neon celebrations for exceptional prompt-cache hits.",
   "type": "module",
   "keywords": [

package/settings.ts

@@ -176,6 +176,17 @@ export const SETTING_KEYS = [
 
 export type SettingKey = (typeof SETTING_KEYS)[number];
 
+/**
+ * Compile-time completeness guard.
+ *
+ * `satisfies readonly (keyof StatuslineSettings)[]` above only proves the listed
+ * keys are real; it does not prove every key is listed. That gap is silent and
+ * expensive: SETTING_KEYS feeds changedSettingKeys, which feeds every save, so a
+ * setting missing from it works all session and then vanishes on restart.
+ */
+type Unlisted<Key extends never> = Key;
+type _EverySettingKeyIsListed = Unlisted<Exclude<keyof StatuslineSettings, SettingKey>>;
+
 /** The keys one edit actually touched; the unit of a merging save. */
 export function changedSettingKeys(
 	previous: StatuslineSettings,