feat(PBI-76): user-settings DB-store infrastructure (Phase 0) (#185)

* docs(PBI-76): plan for user-settings DB-store

Persists view/filter prefs in User.settings (Json) instead of
localStorage. SSR-correct hydration, cross-tab sync via
LISTEN/NOTIFY + SSE, cross-device persistence.

Phased: 0=infra, 1=migrate flicker sources, 2=cookie consolidation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-76): User.settings json column + migration

Adds JSONB column to users table for persistent user prefs.
Idempotent SQL — safe on databases where column already exists.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-76): user-settings types and merge helpers

Zod schema for User.settings shape (views/devTools), deep-merge
helper that replaces arrays and merges nested objects, and a
safe parser that returns defaults on invalid input.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-76): updateUserSettingsAction with notify

Validates patch via Zod, deep-merges with current settings in
a transaction, persists to DB, and emits pg_notify on
scrum4me_changes for cross-tab/cross-device sync. Demo accounts
get 403, unauthenticated 401, invalid input 422.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-76): user-settings zustand store with optimistic flow

Hydrate from prop (SSR-correct), setPref via path with optimistic
update + rollback on server error, applyServerPatch for SSE-driven
cross-tab updates. Demo accounts skip server-write entirely.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-76): SSE route for user-settings

User-scoped /api/realtime/user-settings stream that filters
scrum4me_changes notifications on kind=user_settings and matching
userId. Forwards the patch as a data: event so other tabs can
applyServerPatch without re-fetching settings.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(PBI-76): user-settings bridge mounted in app layout

Hydrates the zustand store with the user's persisted settings via
prop (SSR-correct, no flicker). Opens an EventSource to
/api/realtime/user-settings so changes from other tabs/devices
flow into the same store. Demo accounts skip the SSE subscription.

Layout now selects user.settings alongside the other user fields,
no extra DB roundtrip.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(PBI-76): user-settings lib/action/store coverage

22 vitest cases covering merge semantics (no mutation, array
replace, nested merge), Zod schema strictness, server action
auth/demo/validation paths, and the optimistic store flow
including rollback and demo-mode skip.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(PBI-76): sync package-lock to v1.3.3

Lockfile drifted after @prisma/client reinstall during the
schema regenerate. No dependency changes — just the version
field tracking package.json bumped in #184.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

__tests__/lib/user-settings.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  DEFAULT_USER_SETTINGS,
+  UserSettingsSchema,
+  mergeSettings,
+  parseUserSettings,
+  type UserSettings,
+} from '@/lib/user-settings'
+
+describe('mergeSettings', () => {
+  it('returns the patch when previous is empty', () => {
+    const result = mergeSettings({}, { views: { sprintBacklog: { sort: 'code' } } })
+    expect(result).toEqual({ views: { sprintBacklog: { sort: 'code' } } })
+  })
+
+  it('preserves existing keys when patch only sets new ones', () => {
+    const prev: UserSettings = { views: { sprintBacklog: { sort: 'code' } } }
+    const result = mergeSettings(prev, {
+      views: { pbiList: { sort: 'date' } },
+    })
+    expect(result).toEqual({
+      views: {
+        sprintBacklog: { sort: 'code' },
+        pbiList: { sort: 'date' },
+      },
+    })
+  })
+
+  it('merges nested objects without overwriting siblings', () => {
+    const prev: UserSettings = {
+      views: { sprintBacklog: { sort: 'code', sortDir: 'asc' } },
+    }
+    const result = mergeSettings(prev, {
+      views: { sprintBacklog: { sort: 'priority' } },
+    })
+    expect(result).toEqual({
+      views: { sprintBacklog: { sort: 'priority', sortDir: 'asc' } },
+    })
+  })
+
+  it('replaces arrays instead of appending', () => {
+    const prev: UserSettings = {
+      views: { sprintBacklog: { collapsedPbis: ['a', 'b'] } },
+    }
+    const result = mergeSettings(prev, {
+      views: { sprintBacklog: { collapsedPbis: ['c'] } },
+    })
+    expect(result.views?.sprintBacklog?.collapsedPbis).toEqual(['c'])
+  })
+
+  it('does not mutate the previous object', () => {
+    const prev: UserSettings = { views: { sprintBacklog: { sort: 'code' } } }
+    const snapshot = JSON.parse(JSON.stringify(prev))
+    mergeSettings(prev, { views: { sprintBacklog: { sortDir: 'desc' } } })
+    expect(prev).toEqual(snapshot)
+  })
+
+  it('skips undefined values in the patch', () => {
+    const prev: UserSettings = { views: { sprintBacklog: { sort: 'code' } } }
+    const result = mergeSettings(prev, { views: undefined })
+    expect(result).toEqual(prev)
+  })
+})
+
+describe('parseUserSettings', () => {
+  it('returns defaults for null', () => {
+    expect(parseUserSettings(null)).toEqual(DEFAULT_USER_SETTINGS)
+  })
+
+  it('returns defaults for undefined', () => {
+    expect(parseUserSettings(undefined)).toEqual(DEFAULT_USER_SETTINGS)
+  })
+
+  it('returns defaults for invalid input', () => {
+    expect(parseUserSettings({ views: { sprintBacklog: { filterStatus: 'BOGUS' } } }))
+      .toEqual(DEFAULT_USER_SETTINGS)
+  })
+
+  it('passes valid settings through', () => {
+    const valid = { views: { sprintBacklog: { sort: 'code' as const } } }
+    expect(parseUserSettings(valid)).toEqual(valid)
+  })
+})
+
+describe('UserSettingsSchema', () => {
+  it('rejects unknown top-level keys', () => {
+    const result = UserSettingsSchema.safeParse({ unknown: 1 })
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts an empty object', () => {
+    expect(UserSettingsSchema.safeParse({}).success).toBe(true)
+  })
+
+  it('accepts the full shape', () => {
+    const result = UserSettingsSchema.safeParse({
+      views: {
+        sprintBacklog: {
+          filterPriority: 1,
+          filterStatus: 'OPEN',
+          sort: 'code',
+          sortDir: 'asc',
+          collapsedPbis: ['x'],
+          filterPopoverOpen: true,
+        },
+        pbiList: { sort: 'priority', filterPriority: 'all', filterStatus: 'ready', sortDir: 'desc' },
+        storyPanel: { sort: 'date' },
+        jobsColumns: { 'queue:active': { kinds: ['TASK_IMPLEMENTATION'], statuses: [] } },
+      },
+      devTools: { debugMode: true },
+    })
+    expect(result.success).toBe(true)
+  })
+})