From 99096f9f4a25abbfe8781ddf70a96770c4be181c Mon Sep 17 00:00:00 2001 From: Oier Bravo Urtasun Date: Mon, 18 May 2026 04:45:36 +0200 Subject: [PATCH] docs(fase-12): history doc + CLAUDE.md status + new-section convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds docs/history/fase-12-section-visibility.md describing the COALESCE-precedence design that keeps Fase 13's server-settings layer to a one-line diff, the realtime publication addition that SV-02 forced, and the hermetic test-reset deviation from the plan. Updates CLAUDE.md project status (2/6 → 4/6 since Fase 11 and 12 both shipped on the mvp2 branch) and adds the "new top-level section requires" rule under Domain Model. Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 12 +- docs/history/fase-12-section-visibility.md | 202 +++++++++++++++++++++ 2 files changed, 213 insertions(+), 1 deletion(-) create mode 100644 docs/history/fase-12-section-visibility.md diff --git a/CLAUDE.md b/CLAUDE.md index e2e0362..5659429 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co **Fase 0–5 complete. Fase 6 complete (deploy readiness: PWA injectManifest SW + manifest + iOS meta tags + placeholder icons + Kong rate-limit on invitations + dev JWT rotation + prod env template + rls-audit.sh + Justfile lighthouse/rls-audit/test-rate-limit). Production stack deployed to ambrosio (OVH VPS) at https://erosi.limonia.net (app + Supabase, external Keycloak); edge proxy now off-stack — internal Caddy fans kong/app on host port 3000, whatever external proxy fronts the host terminates TLS and forwards plain HTTP to ambrosio:3000 (originally NetBird's self-hosted Traefik, now proxy-agnostic); PWA strategy switched to generateSW to unblock the prod build (see the "injectManifest hardcoded filename" gotcha below). Fase 7 complete: 12 new Playwright tests fill the collective-flow UI gap (O-01..O-03 onboarding, I-01..I-05 invitation acceptance, MC-02..MC-05 admin-manage) — writing them surfaced + fixed three latent bugs in the product code (atomic `create_collective()` RPC, pendingInvitationToken restore after login, manage page not reloading on late $currentCollective hydration). Plus migration 013 (auth.users role/aud default trigger) — found after the first real self-registration on prod via Keycloak→GoTrue left the user with empty `role`/`aud` columns, breaking every REST call with `role "" does not exist`. Post-fase-7 prod auth hardening (2026-04-20..21, see `docs/history/fase-8-auth-logout.md`): migration 014 extends the role/aud guard to UPDATE (GoTrue's pop-ORM resends role='' right after the INSERT and clobbered the INSERT trigger's backfill); `logout()` now does RP-initiated Keycloak end-session + lands on a new public `/logged-out` route, which both actually ends the Keycloak SSO cookie (so the next login re-prompts) and closes a PKCE-verifier race that produced "PKCE code verifier not found in storage" on prod. 259 tests green: 45 pgTAP + 140 Vitest integration + 15 Vitest unit + 59 Playwright + 1 Vitest rate-limit (gated, run via `just test-rate-limit`). 3 skipped in `just test-all` (2 Realtime presence — upstream `handle_out/3` bug; 1 rate-limit — gated). Push notifications + CI Docker + final production icons deliberately out of scope. ✅** -**MVP2 — in progress (2/6 ✅).** Branch `mvp2`. **Fase 9 complete: dark mode + polish** (migration 015 + 016 + pgTAP 009 + 010 + dark-mode plumbing + max-w-2xl reading column on detail routes + sync_conflicts table/queue logging/debug panel + WebKit Playwright project for the swipe-toggle gestures; see `docs/history/fase-9-polish-dark-mode.md`). **Fase 10 complete: spec completion (H06/H07/H08 + trash restore + account deletion + sidebar-create + reset-from-detail + Accept-Language)** — 5 new migrations (017 leave_collective, 018 dissolve_collective, 019 user-deletion FKs, 020 restore/hard-delete RPCs, 021 delete_account) + 4 new pgTAP suites + 6 new Playwright specs + Accept-Language parser; see `docs/history/fase-10-spec-completion.md`. Test totals: 96 pgTAP + 151 Vitest integration + 38 Vitest unit + 74 Playwright + 1 Vitest rate-limit (gated) = **360 tests green**; 3 skipped in `just test-all` (2 Realtime presence — upstream `handle_out/3` bug `supabase/realtime#1617` still open as of 2026-05-18 / latest v2.86.3; 1 rate-limit — gated). WebKit specs (2 in Fase 9.4) are gated on `RUN_WEBKIT=1` so they stay out of `just test-all` (the binary needs `libicu74` / `libwoff1` / `libmanette-0.2-0` system deps via `sudo pnpm exec playwright install-deps`). Remaining fases (📋): Fase 11 item tags + drag-reorder (`plan/fase-11-item-tags-importance.md`, migration 022) | Fase 12 section visibility — JSONB `feature_flags` on `users`+`collectives`, `section_enabled()` SQL helper (`plan/fase-12-section-visibility.md`, migration 023) | Fase 13 server administration — `/admin` area, `server_admins` table, audit log, server-level visibility defaults, depends on Fase 12 (`plan/fase-13-server-admin.md`, migrations 024+025) | Fase 14 PWA hardening — update toast, offline polish, version chip, depends on Fase 9.3 (`plan/fase-14-pwa-hardening.md`, no migration). Fase 7+8 already shipped as MVP cleanup, not MVP2. +**MVP2 — in progress (4/6 ✅).** Branch `mvp2`. **Fase 9 complete: dark mode + polish** (migration 015 + 016 + pgTAP 009 + 010 + dark-mode plumbing + max-w-2xl reading column on detail routes + sync_conflicts table/queue logging/debug panel + WebKit Playwright project for the swipe-toggle gestures; see `docs/history/fase-9-polish-dark-mode.md`). **Fase 10 complete: spec completion (H06/H07/H08 + trash restore + account deletion + sidebar-create + reset-from-detail + Accept-Language)** — 5 new migrations (017–021) + 4 new pgTAP suites + 6 new Playwright specs; see `docs/history/fase-10-spec-completion.md`. **Fase 11 complete: item tags + drag-reorder** — migration 022 + pgTAP 014 + tags store + chips/picker + filter bar + realtime re-sort; see `docs/history/fase-11-item-tags-importance.md`. **Fase 12 complete: section visibility (feature flags)** — migration 023 + pgTAP 015 (20 assertions) + Vitest SV-01..SV-06 + Playwright SV-01..SV-03; JSONB `feature_flags` on `users`+`collectives`, `public.section_enabled()` SQL helper with COALESCE precedence chain (Fase 13 server layer is a one-line diff); see `docs/history/fase-12-section-visibility.md`. Test totals: 124 pgTAP + 163 Vitest integration + 45 Vitest unit + 82 Playwright + 1 Vitest rate-limit (gated) = **414 tests green**; 3 skipped in `just test-all` (2 Realtime presence — upstream `handle_out/3` bug `supabase/realtime#1617` still open; 1 rate-limit — gated). WebKit specs (2 in Fase 9.4) are gated on `RUN_WEBKIT=1` so they stay out of `just test-all` (the binary needs `libicu74` / `libwoff1` / `libmanette-0.2-0` system deps via `sudo pnpm exec playwright install-deps`). Remaining fases (📋): Fase 13 server administration — `/admin` area, `server_admins` table, audit log, server-level visibility defaults, depends on Fase 12 (`plan/fase-13-server-admin.md`, migrations 024+025) | Fase 14 PWA hardening — update toast, offline polish, version chip, depends on Fase 9.3 (`plan/fase-14-pwa-hardening.md`, no migration). Fase 7+8 already shipped as MVP cleanup, not MVP2. ## Documentation Map @@ -17,6 +17,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co - `docs/history/fase-8-auth-logout.md` — post-fase-7 prod auth hardening (migration 014 + RP-initiated logout) - `docs/history/fase-9-polish-dark-mode.md` — MVP2 dark mode + reading width + sync-conflicts debug panel - `docs/history/fase-10-spec-completion.md` — MVP2 CU-H06/H07/H08 + trash RPCs + account delete + sidebar create + reset from detail + auto language +- `docs/history/fase-11-item-tags-importance.md` — MVP2 item tags + drag-reorder +- `docs/history/fase-12-section-visibility.md` — MVP2 section visibility / feature flags (this fase) - `analysis/analisis-funcional.md` — complete functional specification (domain model, use cases, data models, business rules) - `plan/fase-*.md` — phase-by-phase implementation plans (Fase 0 through Fase 7) - `design/slate_collective/DESIGN.md` + `design/*/screen.png` — "Monolith Editorial" direction + per-screen Stitch mockups. Consult before changing UI. @@ -73,6 +75,14 @@ The central organizing unit is the **Collective** (household group), not the ind - Trash retains deleted items/notes for 7 days before permanent deletion. - If the sole admin deletes their account, the system auto-promotes the oldest member before allowing deletion. +**Section visibility (feature flags) — required steps for any new top-level section.** A "section" here is one of the four current navigable areas (lists, tasks, notes, search) — adding a fifth means EVERY one of: +1. SQL migration that updates `public.known_sections()` to include the new key + (if it adds a new RPC) maps onto the planned Fase 13 server-layer extension of `public.section_enabled()`. +2. `SectionKey` union + `SECTION_KEYS` array entry in `packages/types/src/domain.ts`. +3. Default-checked toggle row in `/settings` (per-user) and `/collective/manage` (admin) — both already iterate `SECTION_KEYS`, so this is automatic as long as you add the `section_label_` Paraglide message + the route prefix in `(app)/+layout.svelte`'s `SECTION_BY_PREFIX` array (drives the redirect guard). +4. pgTAP assertion in `supabase/tests/015_section_visibility.sql` that `section_enabled('', user, collective)` defaults to true. + +Without all four, the section either shows up but can't be hidden, or can be hidden but isn't toggled from the UI — both are confusing failure modes. + ## Internationalisation Library: **Paraglide JS** (`@inlang/paraglide-sveltekit`). Compile-time, zero runtime overhead, tree-shaken per language. diff --git a/docs/history/fase-12-section-visibility.md b/docs/history/fase-12-section-visibility.md new file mode 100644 index 0000000..6422247 --- /dev/null +++ b/docs/history/fase-12-section-visibility.md @@ -0,0 +1,202 @@ +# Fase 12 — Section visibility / feature toggles (MVP2 4/6) + +**Status: complete · 2026-05-18.** + +Fourth slice of MVP2. Lets each user hide top-level sections they don't use, and lets a collective admin hide them for every member. No plugin system — JSONB `feature_flags` on `users` + `collectives` resolved through a single STABLE SQL function, mirrored client-side for nav rendering. + +Pre-requisite for Fase 13 (server administration). The SQL helper is designed so the Fase-13 server layer is a one-line diff. + +Final test counts: **124 pgTAP + 163 Vitest integration + 45 Vitest unit + 82 Playwright = 414 green; 3 skipped (2 upstream Realtime presence + 1 gated rate-limit).** Delta vs Fase 11: + +| Suite | Before | After | Δ | +|---|---|---|---| +| pgTAP | 104 | 124 | +20 | +| Vitest integration | 157 | 163 | +6 | +| Vitest unit | 45 | 45 | 0 | +| Playwright E2E | 79 | 82 | +3 | +| **Total** | **385** | **414** | **+29** | + +--- + +## 12.1 — Model + SQL helpers + +**Migration `023_section_visibility.sql`** adds: + +- `public.users.feature_flags jsonb NOT NULL DEFAULT '{}'::jsonb` +- `public.collectives.feature_flags jsonb NOT NULL DEFAULT '{}'::jsonb` +- `public.known_sections() returns text[] IMMUTABLE` — canonical 4 keys (`lists`, `tasks`, `notes`, `search`). Adding a section is a fresh migration; nothing else queries the function at runtime, but it documents the contract. +- `public.section_enabled(p_section text, p_user uuid, p_collective uuid) returns boolean STABLE SECURITY DEFINER` — the precedence resolver. + +The function body is structured as a single `COALESCE` so the **Fase-13 server layer is a literal one-line prepend** — no callers change shape, no extra branching. The expected end state once Fase 13 lands: + +```sql +SELECT COALESCE( + (SELECT (value ->> p_section)::boolean -- Fase 13 server layer (FUTURE) + FROM public.server_settings + WHERE key = 'default_sections'), + (SELECT (feature_flags ->> p_section)::boolean + FROM public.collectives WHERE id = p_collective), + (SELECT (feature_flags ->> p_section)::boolean + FROM public.users WHERE id = p_user), + true +); +``` + +A comment in the migration spells out the chain (server → collective → user → default true) so the next contributor can see the slot before having read this doc. + +RLS: writes to `feature_flags` piggyback on the existing `users_update_own` (migration 003) + `collectives_update` (admin-only) policies. **No new policy was needed** — the JSONB column is a normal column from RLS's perspective. This was the rule-7 stop condition; it did not trigger. + +**Realtime**: also added in this migration. `public.users` and `public.collectives` are now in the `supabase_realtime` publication with `REPLICA IDENTITY FULL`. Without them, the client-side subscriptions in `features.ts` see zero events — caught by SV-02 (the dual-context realtime test) before it ever passed locally. + +**pgTAP `015_section_visibility.sql`** — 20 assertions: + +- SV-T01..SV-T06: column shape (existence, type `jsonb`, NOT NULL) for both tables. +- SV-T07..SV-T09: `known_sections()` exists, is IMMUTABLE, returns the canonical 4 keys in order. +- SV-T10..SV-T12: `section_enabled()` exists with the right `(text, uuid, uuid) → boolean` signature, is STABLE. +- SV-T13: empty flags on both layers → default ON. +- SV-T14: user OFF + collective absent → OFF. +- SV-T15: collective OFF wins over user ON. +- SV-T16: unknown section key → default true (forward-compat — a newly-deployed front-end can call `section_enabled('newkey', …)` before the migration that adds the key lands and the call doesn't error). +- SV-T17..SV-T20: realtime publication membership + REPLICA IDENTITY FULL for both new tables. + +`packages/types/src/database.ts` hand-extended with `feature_flags: Json` on the `users` + `collectives` Row/Insert/Update shapes plus the two new Functions (`known_sections`, `section_enabled`). `just db-types` remains gated (Supabase CLI not installed on this host) — same convention as Fase 11. + +--- + +## 12.2 — Stores + types + +`packages/types/src/domain.ts`: + +```ts +export type SectionKey = 'lists' | 'tasks' | 'notes' | 'search'; +export const SECTION_KEYS: readonly SectionKey[] = ['lists', 'tasks', 'notes', 'search']; +export type FeatureFlags = Partial>; +``` + +`apps/web/src/lib/stores/features.ts` (new) — the client mirror of `section_enabled()`: + +- `currentUserFeatures` writable, loaded by root `+layout.svelte` after sign-in. +- `enabledSections` derived `Record` applying the same precedence (collective > user > default true). Used as `$enabledSections.tasks` in components. +- `enabledSectionList` derived `SectionKey[]` — the ordered list of visible keys with one client-side hard override: if every layer says OFF for everything, force `['lists']` so the user always has a landing page (§12.3.4). +- `setUserFeature(key, value)` — optimistic local patch, rolls back on RLS denial. +- `setCollectiveFeature(key, value)` — optimistic patch, throws `forbidden` when the UPDATE returns zero rows (RLS denied), which the UI surfaces by snapping the toggle back. +- `loadCurrentUserFeatures(userId)` + `subscribeCollectiveFeatures(collectiveId)` — set up one Realtime channel each per target. The user channel is keyed by user id; the collective channel is rebuilt whenever `$currentCollective.id` changes (subscribed via `currentCollective.subscribe(...)` in the root layout). + +Per CLAUDE.md "Supabase JS + onAuthStateChange deadlock" gotcha, `loadCurrentUserFeatures` is called from inside the already-deferred `setTimeout(..., 0)` block in the auth callback — same shape as the existing `loadUserCollectives` path. The collective channel is set up outside that callback so collective switches don't need an auth event. + +`Collective` interface (`apps/web/src/lib/stores/collective.ts`) grows a `feature_flags: FeatureFlags` field. `loadUserCollectives` extends its SELECT to fetch it. Every other place that fabricated a Collective by hand (`CreateCollectiveModal`, `onboarding/+page.svelte`, `collective/manage/+page.svelte`) now includes `feature_flags: {}` for fresh rows or selects it on rename/recolor. + +**Vitest integration `tests/section-visibility.test.ts`** — 6 assertions: + +- SV-01 default ON for every known section. +- SV-02 user OFF affects only that user, not peers. +- SV-03 collective OFF beats user ON. +- SV-04 user can update own `feature_flags` (RLS write piggyback). +- SV-05 admin can update collective `feature_flags`; non-admin member's UPDATE returns 0 rows (RLS denied). +- SV-06 a user in two collectives sees the per-collective override resolution independently. + +--- + +## 12.3 — UI gating + redirect guard + +**Nav components** (`DesktopSidebar`, `BottomTabBar`): + +- Each nav entry declared with its `SectionKey` so the runtime filter is one line: `allItems.filter((it) => it.section === 'lists' || $enabledSections[it.section])`. +- "lists" is force-shown unconditionally (the §12.3.4 always-one-landing rule). +- Both components add `data-section="…"` on each entry; `BottomTabBar` adds `data-section-count="N"` on the nav so tests can assert grid changes. + +`MobileDrawer` doesn't carry nav entries today (only the collective switcher + Manage + Settings + Logout) so it didn't need a change. If a future iteration adds nav links there, the same filter pattern applies. + +**Route guard** in `(app)/+layout.svelte`: a `$effect` watches `$page.url.pathname`. If it matches a disabled section's prefix (`/tasks`, `/notes`, `/search` — `/lists` is always allowed), it calls `goto('/lists')` and surfaces a transient `section_disabled_for_collective` toast (top-centered, 3.5 s auto-dismiss). Adding a new section requires extending the `SECTION_BY_PREFIX` array — flagged in CLAUDE.md. + +The toast is intentionally separate from the existing `UndoToast` so the two can stack without colliding. + +Dev-only hook: `+layout.svelte`'s `onMount` exposes the Supabase client singleton on `window.__sb` when `import.meta.env.DEV` is true so the Playwright spec can patch rows directly via the same client (and the same JWT) the app uses. Vite dead-code-eliminates this in production builds. + +--- + +## 12.4 — Settings + manage UI + +`/settings`: + +- New "Visible sections" block with one checkbox per `SectionKey`, bound to `setUserFeature`. +- When the active collective has explicitly turned a section OFF, that user toggle is disabled and a one-line "Hidden by the collective" hint replaces the visible state — explaining why the per-user toggle is moot. + +`/collective/manage` (admin-only, inside the existing `isAdmin` block): + +- New "Collective sections" block with one checkbox per `SectionKey`, bound to `setCollectiveFeature`. +- Flipping any of them propagates to every member in realtime — that's exactly what SV-02 verifies. + +Both helpers fall back to default-ON semantics when the JSONB key is missing, mirroring `section_enabled()`. So untouched rows render exactly as before fase 12 — nothing is forced on or off. + +11 new Paraglide messages in `en` + `es`: `section_disabled_for_collective`, `settings_section_visibility_{title,blurb,overridden}`, `collective_section_visibility_{title,blurb}`, `section_label_{lists,tasks,notes,search}`. + +--- + +## 12.5 — Convention rule + +Added to `CLAUDE.md` under "Domain Model" — adding a new top-level section requires all four of: + +1. Migration that updates `public.known_sections()`. +2. `SectionKey` + `SECTION_KEYS` entry in `packages/types/src/domain.ts`. +3. Paraglide `section_label_` message + route prefix in `(app)/+layout.svelte`'s `SECTION_BY_PREFIX`. +4. pgTAP assertion that `section_enabled('', …)` defaults to true. + +The settings + manage toggles iterate `SECTION_KEYS`, so they're automatic once steps 2 + 3 are done. + +--- + +## 12.6 — Tests + +**E2E `tests/e2e/section-visibility.test.ts`** (SV-01..SV-03): + +- SV-01 Ana flips the user toggle for Tasks in /settings → sidebar + bottom tab bar lose the entry → visiting /tasks bounces to /lists + the toast surfaces. +- SV-02 Dual-context. Ana (admin) hides Notes for the collective in /collective/manage; Borja's BottomTabBar loses the Notes entry within the 15 s realtime window, no reload. +- SV-03 Borja sets `tasks: false` for himself; Ana then sets `tasks: true` at the collective level. Tasks reappears for Borja in that collective (collective ON beats user OFF — the integration suite's SV-06 covers the inverse where the collective has no opinion). + +Each test resets both `users.feature_flags` (Ana + Borja) AND `collectives.feature_flags` (seed collective) in **beforeEach AND afterEach** so the suite is hermetic regardless of what ran before in `just test-all`. Without the beforeEach we observed bleed from the prior tasks tests into SV-02 + SV-03 on the first full-suite run; the early "passes in isolation, fails in the full run" failure mode is captured in CLAUDE.md's existing "Realtime waitFor timeout" gotcha shape — same root cause family. + +--- + +## Deviation note: e2e cleanup hardening (vs plan) + +The plan didn't call out the beforeEach reset, but the `just test-all` first run surfaced state leakage from the broader suite into SV-02 (collective row had stale `feature_flags`). Adding a symmetric beforeEach reset (Ana resets her row + the seed collective via a fresh context; Borja resets his row via his own context) made the suite deterministic across 5 sequential full runs. Cost: ~6 s per spec in setup overhead; acceptable. + +--- + +## Forward-compat for Fase 13 + +The single design decision that makes Fase 13's server-settings layer a clean diff: + +- `section_enabled()` is a single COALESCE chain. Fase 13 only prepends a new SELECT branch from `server_settings.default_sections` at the top of the COALESCE. No call-site shape changes anywhere in the codebase. The migration body comment spells this out so the next contributor sees it. +- The client-side `enabledSections` derived store reads from two sources today (`currentUserFeatures` + `currentCollective`). Fase 13 will add a third (`serverSettings`), and the derived shape stays `Record`. No consumer changes. +- `setCollectiveFeature` throws a typed `'forbidden'` error already, which Fase 13 can reuse for the server-layer admin endpoint. + +Nothing about the current design makes Fase 13 harder. The one place a server-layer pgTAP test will need extra wiring is `SV-T15` — once the server layer exists, an "admin server override OFF wins over collective ON" case becomes the new top of the precedence ladder. + +--- + +## File map (new) + +- `supabase/migrations/023_section_visibility.sql` +- `supabase/tests/015_section_visibility.sql` +- `packages/test-utils/tests/section-visibility.test.ts` +- `apps/web/src/lib/stores/features.ts` +- `apps/web/tests/e2e/section-visibility.test.ts` +- `docs/history/fase-12-section-visibility.md` + +Modified: + +- `packages/types/src/domain.ts` — `SectionKey`, `SECTION_KEYS`, `FeatureFlags` +- `packages/types/src/database.ts` — `feature_flags` on `users` + `collectives` Rows, `known_sections` + `section_enabled` Functions +- `apps/web/src/lib/stores/collective.ts` — `feature_flags` on `Collective` +- `apps/web/src/lib/components/CreateCollectiveModal.svelte` — fabricate `feature_flags: {}` on create +- `apps/web/src/routes/onboarding/+page.svelte` — same +- `apps/web/src/routes/(app)/collective/manage/+page.svelte` — collective toggle UI + extended SELECT for `feature_flags` +- `apps/web/src/routes/(app)/settings/+page.svelte` — user toggle UI +- `apps/web/src/routes/(app)/+layout.svelte` — route guard + toast +- `apps/web/src/routes/+layout.svelte` — `loadCurrentUserFeatures` wiring, `subscribeCollectiveFeatures`, `window.__sb` dev hook +- `apps/web/src/lib/components/layout/DesktopSidebar.svelte` — nav filter + `data-section` +- `apps/web/src/lib/components/layout/BottomTabBar.svelte` — nav filter + `data-section` + `data-section-count` +- `apps/web/messages/{en,es}.json` — 11 keys +- `CLAUDE.md` — Domain Model "new section requires" rule