[devswha]

Change

A damaged preferences.json or seen.json was read as empty and then silently replaced by the
next change, so the only copy of what was lost disappeared. Both stores now keep it aside first,
through one small helper (server/state-document.ts) that tells a missing file from an
unreadable one, from malformed JSON and from a document of the wrong shape.

• Reading (startup, GET /api/preferences, GET /api/seen) never renames or writes anything.
  Parse and shape failures log a diagnostic naming the kind of failure, never the content.
  Preferences whose settings is not an object (or with invalid pins), and a seen document that
  is not a list or holds rows that are not finishes, count as damaged. Valid seen rows are still
  used.
• Until a store has replaced its file, every write re-reads it in the same synchronous section,
  whether it was valid, damaged, unreadable or missing at startup, so the decision never rests on
  a stale flag from startup and a file damaged after a valid start is kept too:
  • a file repaired by hand meanwhile is reloaded and the change merged over it, with no backup;
    nothing of the repair is held in memory until the replacement succeeds;
  • damaged bytes (the ones on disk now, not the sample from startup) are moved untouched to
    <file>.bad with mode 0600, replacing the previous .bad only when this move succeeds, and
    then the new document is renamed into place. There is one recovery generation, never a
    growing series of timestamped copies.
• Failure receipts:
  • a read failure (permissions, a directory in place of the file) refuses the write and replaces
    nothing;
  • if the damaged file cannot be kept aside (chmod or rename fails), the write is refused with an
    explicit 500 (preferences_unwritable / seen_unwritable) naming the .bad file, and the
    original, the older .bad, the held state and the listeners are all unchanged;
  • if the final replacement fails after the move, the complete original stays in .bad, nothing
    is published, the held state is unchanged, and a retry checks the file again: it writes the
    new document while keeping those bytes, or keeps newer damaged bytes found on disk.
• A missing file behaves as before. Devices and VAPID handling are untouched. No HTTP/WS shape,
  demo response or UI string changes.

The exclusion this relies on is within one server process. Several servers sharing one state
directory, or another program editing the file during the final rename, are out of scope.

Validation

• bun test ./server/preferences.test.ts ./server/seen.test.ts ./server/devices.test.ts ./server/push.test.ts:
  89 pass, 0 fail. This includes the existing devices and malformed-VAPID fail-closed tests.
• New cases in both store test files: "preserves malformed bytes only on first effective write",
  "preserves wrong-shaped documents privately", "keeps a manual repair rather than quarantining
  it", "refuses overwrite when preservation fails", "retains one bad generation across
  replacement failure", "refuses to write over a file it cannot read", "preserves a file damaged
  after a valid start on the first write" (both stores) and, for seen, "holds nothing of a repair
  whose replacement failed, and checks the file again on retry". They assert exact byte
  equality of .bad, mode 0600 on POSIX, at most one .bad, and no listener call before a
  successful replacement. The replacement failure is injected with spyOn(fs, "renameSync"); the
  preservation failure uses a real non-empty directory at .bad. All 19 new cases fail against
  the stores on main (bun test exits 1).
• The existing damaged-seen test, which expected the damaged file to be replaced, became
  "preserves malformed bytes only on first effective write".
• bun run check fast exits 0: workflow syntax, generated types and themes, typecheck, build,
  and unit tests (5791 pass, 0 fail, 8 skip).

Ready for maintainer review; do not merge.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: devswha/herdr-web-ui/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: b1c48ab5-74a7-4b34-994b-987f3b73601f

📥 Commits

Reviewing files that changed from the base of the PR and between 4cabde2 and da135cf.

📒 Files selected for processing: 6

• changelog.d/preserve-damaged-shared-state.md
• server/preferences.test.ts
• server/preferences.ts
• server/seen.test.ts
• server/seen.ts
• server/state-document.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 2 remain after this review.

📝 Summary

Summary by CodeRabbit

• Bug Fixes

  • Damaged or malformed preference and read-history files are now preserved before recovery, preventing accidental data loss.
  • Valid data is retained when files contain a mix of valid and invalid entries.
  • Concurrent changes made during manual repairs are preserved.
  • Unreadable files are no longer overwritten, and failed recovery attempts can be retried safely.
  • Recovered files use more secure file permissions, with only one damaged backup retained.

• Documentation

  • Added documentation describing damaged-file preservation and recovery behavior.

Shared state stores now use common helpers to read and replace JSON documents. The stores preserve damaged files during recovery, reread disk state before their first write, and have expanded tests for repair and write-failure scenarios.

Changes: Shared State Recovery

Layer / File(s)	Summary
Read and replace state documents server/state-document.ts, changelog.d/preserve-damaged-shared-state.md	Added helpers to read JSON state and atomically replace files. When preservation is requested, the helper moves the existing file to a .bad path before replacement. The changelog describes this behavior.
Recover preference documents server/preferences.ts, server/preferences.test.ts	PreferenceStore now distinguishes missing, malformed, and invalid documents. It rereads disk state before the first write and preserves damaged files during repair. Tests cover recovery, manual repairs, unreadable files, and write failures.
Recover seen-state documents server/seen.ts, server/seen.test.ts	SeenStore now validates and merges disk state before its first write, then persists through the shared helpers. Tests cover damaged rows, manual repairs, unreadable files, and write failures.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to da135

This change preserves damaged preferences and seen-state files as .bad copies before replacing them, and it refuses to overwrite files it cannot read. No actionable merge-blocking issue was identified in the supplied context.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 5 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: preserving damaged shared documents before replacement.
Description check		The description includes the required Change and Validation sections. It explains the problem, resulting behavior, scope, failure handling, and test results in sufficient detail.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 5 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• 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

_{Comment @coderabbitai help to get the list of available commands.}