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>

lib/user-settings.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod'
+
+const PriorityFilter = z.union([
+  z.number().int().min(1).max(4),
+  z.literal('all'),
+])
+
+const SortDir = z.enum(['asc', 'desc'])
+
+const SprintBacklogPrefs = z.object({
+  filterPriority: PriorityFilter.optional(),
+  filterStatus: z.enum(['OPEN', 'IN_SPRINT', 'DONE', 'all']).optional(),
+  sort: z.enum(['priority', 'status', 'code']).optional(),
+  sortDir: SortDir.optional(),
+  collapsedPbis: z.array(z.string()).optional(),
+  filterPopoverOpen: z.boolean().optional(),
+}).strict()
+
+const PbiListPrefs = z.object({
+  sort: z.enum(['priority', 'code', 'date']).optional(),
+  filterPriority: PriorityFilter.optional(),
+  filterStatus: z.enum(['ready', 'blocked', 'done', 'all']).optional(),
+  sortDir: SortDir.optional(),
+}).strict()
+
+const StoryPanelPrefs = z.object({
+  sort: z.enum(['priority', 'code', 'date']).optional(),
+}).strict()
+
+const JobsColumnPrefs = z.object({
+  kinds: z.array(z.string()),
+  statuses: z.array(z.string()),
+}).strict()
+
+const ViewsPrefs = z.object({
+  sprintBacklog: SprintBacklogPrefs.optional(),
+  pbiList: PbiListPrefs.optional(),
+  storyPanel: StoryPanelPrefs.optional(),
+  jobsColumns: z.record(z.string(), JobsColumnPrefs).optional(),
+}).strict()
+
+const DevToolsPrefs = z.object({
+  debugMode: z.boolean().optional(),
+}).strict()
+
+export const UserSettingsSchema = z.object({
+  views: ViewsPrefs.optional(),
+  devTools: DevToolsPrefs.optional(),
+}).strict()
+
+export type UserSettings = z.infer<typeof UserSettingsSchema>
+
+export const DEFAULT_USER_SETTINGS: UserSettings = {}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function mergeSettings(
+  prev: UserSettings,
+  patch: Partial<UserSettings>,
+): UserSettings {
+  const out: Record<string, unknown> = { ...prev }
+  for (const [key, patchValue] of Object.entries(patch)) {
+    if (patchValue === undefined) continue
+    const prevValue = (prev as Record<string, unknown>)[key]
+    if (isPlainObject(patchValue) && isPlainObject(prevValue)) {
+      out[key] = mergeSettings(
+        prevValue as UserSettings,
+        patchValue as Partial<UserSettings>,
+      )
+    } else {
+      out[key] = patchValue
+    }
+  }
+  return out as UserSettings
+}
+
+export function parseUserSettings(raw: unknown): UserSettings {
+  if (raw === null || raw === undefined) return DEFAULT_USER_SETTINGS
+  const result = UserSettingsSchema.safeParse(raw)
+  return result.success ? result.data : DEFAULT_USER_SETTINGS
+}