@hank-warren/pi-statusline 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @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
+
+- 2dbfc7a: Stop settings saves from clobbering the file. Sessions load settings once at startup and used to persist their entire in-memory snapshot, so changing any row in a session that started before an edit silently reverted that edit — losing hand-written config and other sessions' changes, and collapsing the file to `{}` because serialization is sparse. Saves now write only the keys a change actually touched, merged over the current file contents, and opening `/statusline` re-reads the file first.
+
+  Also moves the **Cache celebration** row after **Subscription usage** so the menu follows the order elements render in.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -26,7 +26,29 @@ Colors come from a selectable [theme](#themes), with context warning thresholds.
 - **Worktree root** — the directory whose immediate children are tracked as session worktrees (default `~/repos/worktrees`). `~` and `$HOME` are expanded; a relative path is rejected and the previous value kept.
 - **Repo aliases** — short display names for repositories on the worktree line. Enter edits the selected `repo → alias` pair, `d` deletes it, and `Add alias…` creates one from a `repo=alias` line.
 
-Settings live in a single global file, `~/.pi/agent/statusline-settings.json`, written atomically. Only values differing from the defaults are stored, unknown keys from a newer version are preserved, and a missing or malformed file simply yields defaults. The file is read once at session start and is not watched, so hand edits apply to the next session. Concurrent pi sessions are last-writer-wins.
+Settings live in a single global file, `~/.pi/agent/statusline-settings.json`, written atomically. Only values differing from the defaults are stored, unknown keys from a newer version are preserved, and a missing or malformed file simply yields defaults.
+
+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
 

package/index.ts

@@ -22,7 +22,13 @@ import {
 	createAliasSubmenu,
 	createWorktreeRootSubmenu,
 } from "./settings-menu.ts";
-import { defaultSettings, repoAlias, SettingsStore, type StatuslineSettings } from "./settings.ts";
+import {
+	changedSettingKeys,
+	defaultSettings,
+	repoAlias,
+	SettingsStore,
+	type StatuslineSettings,
+} from "./settings.ts";
 import { resolvePalette, type StatuslinePalette, STATUSLINE_THEMES } from "./themes.ts";
 import { type UsageSnapshot, usageBand, UsageTracker } from "./usage.ts";
 import {
@@ -293,7 +299,9 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 		requestRender?.();
 
 		if (!persist) return;
-		settingsStore.save(next).catch((error: unknown) => {
+		const changed = changedSettingKeys(previous, next);
+		if (changed.length === 0) return;
+		settingsStore.save(next, changed).catch((error: unknown) => {
 			ctx.ui.notify(
 				`Could not save statusline settings: ${error instanceof Error ? error.message : String(error)}`,
 				"warning",
@@ -309,6 +317,11 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 				return;
 			}
 
+			// Settings load once per session; refresh before editing so the menu
+			// starts from what is on disk rather than a snapshot that may be hours
+			// old and missing another session's changes.
+			applySettings(ctx, await settingsStore.load(), false);
+
 			await ctx.ui.custom<void>((tui, _theme, _keybindings, done) => {
 				const tracked = trackSelectedLabel(getSettingsListTheme());
 				const settingsTheme = tracked.theme;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-statusline",
-  "version": "0.4.0",
+  "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-menu.ts

@@ -75,21 +75,28 @@ export function buildSettingItems(
 			currentValue: settings.theme,
 			values: [...THEME_NAMES],
 		},
-		{
-			id: CACHE_CELEBRATION_ID,
-			label: CACHE_CELEBRATION_LABEL,
-			description: "Badge animation after an exceptional prompt-cache hit; previews in the statusline below.",
-			currentValue: celebrationValue(settings),
-			values: [OFF, ...CELEBRATION_STYLE_NAMES],
-		},
-		...BOOLEAN_ROWS.map((row) => ({
+	];
+
+	// Rows follow the order their elements render in, so the celebration sits
+	// after the usage meters it is appended to on line 1.
+	for (const row of BOOLEAN_ROWS) {
+		items.push({
 			id: row.id,
 			label: row.label,
 			description: row.description,
 			currentValue: toggleValue(settings[row.id]),
 			values: TOGGLE_VALUES,
-		})),
-	];
+		});
+		if (row.id === "showUsage") {
+			items.push({
+				id: CACHE_CELEBRATION_ID,
+				label: CACHE_CELEBRATION_LABEL,
+				description: "Badge animation after an exceptional prompt-cache hit; previews in the statusline below.",
+				currentValue: celebrationValue(settings),
+				values: [OFF, ...CELEBRATION_STYLE_NAMES],
+			});
+		}
+	}
 
 	items.push({
 		id: WORKTREE_ROOT_ID,

package/settings.ts

@@ -165,6 +165,40 @@ function sameAliases(a: Record<string, string>, b: Record<string, string>): bool
 	return aKeys.every((key) => a[key] === b[key]);
 }
 
+/** Every persisted top-level key, so a diff can enumerate them exhaustively. */
+export const SETTING_KEYS = [
+	...BOOLEAN_SETTING_KEYS,
+	"theme",
+	"cacheCelebrationStyle",
+	"worktreeRoot",
+	"repoAliases",
+] as const satisfies readonly (keyof StatuslineSettings)[];
+
+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,
+	next: StatuslineSettings,
+): SettingKey[] {
+	return SETTING_KEYS.filter((key) =>
+		key === "repoAliases"
+			? !sameAliases(previous.repoAliases, next.repoAliases)
+			: previous[key] !== next[key],
+	);
+}
+
 /**
  * Sparse serialization: only values differing from the defaults are written, so
  * a later default change still reaches hosts that never touched that key.
@@ -235,10 +269,30 @@ export class SettingsStore {
 		return settings;
 	}
 
-	/** Atomic write via temp file + rename. Rejects so the caller can notify. */
-	async save(settings: StatuslineSettings = this.current): Promise<void> {
+	/** Re-read the file as a plain object; anything unusable reads as empty. */
+	private async readRaw(): Promise<Record<string, unknown>> {
+		try {
+			const parsed: unknown = JSON.parse(await readFile(this.path, "utf8"));
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+			return { ...(parsed as Record<string, unknown>) };
+		} catch {
+			return {};
+		}
+	}
+
+	/**
+	 * Atomic write via temp file + rename. Rejects so the caller can notify.
+	 *
+	 * With `changed`, only those keys are written over whatever is on disk right
+	 * now. Settings load once per session, so a full-snapshot write would let a
+	 * session started before an edit silently revert it — including edits made by
+	 * hand or by another session. Passing the keys one change actually touched
+	 * keeps a writer from claiming fields it was never asked about.
+	 */
+	async save(settings: StatuslineSettings = this.current, changed?: readonly SettingKey[]): Promise<void> {
 		this.current = settings;
-		const payload = `${JSON.stringify(serializeSettings(settings, this.extra, this.home), null, "\t")}\n`;
+		const object = changed ? await this.merge(settings, changed) : serializeSettings(settings, this.extra, this.home);
+		const payload = `${JSON.stringify(object, null, "\t")}\n`;
 		const temporary = `${this.path}.${pid}.tmp`;
 		await mkdir(dirname(this.path), { recursive: true });
 		try {
@@ -249,4 +303,19 @@ export class SettingsStore {
 			throw error;
 		}
 	}
+
+	private async merge(
+		settings: StatuslineSettings,
+		changed: readonly SettingKey[],
+	): Promise<Record<string, unknown>> {
+		const merged = await this.readRaw();
+		// Serialization is sparse, so a key absent here is back at its default and
+		// must be removed rather than written.
+		const desired = serializeSettings(settings, {}, this.home);
+		for (const key of changed) {
+			if (Object.hasOwn(desired, key)) merged[key] = desired[key];
+			else delete merged[key];
+		}
+		return merged;
+	}
 }