test: full test suite (Vitest + pgTAP + Playwright) + TDD plan restructure

Add a 4-layer test stack covering RLS, triggers, and UI flows for Fases 0–2a,
then restructure every plan file so future fases start with tests and end with
a verification gate.

Test suite
- packages/test-utils: Vitest integration tests signing HS256 JWTs via jose so
  each test acts as a specific seed user (createClientAs + createAdminClient)
- supabase/tests: pgTAP for accept_invitation(), item_frequency trigger, and
  promote-on-admin-leave; each file self-installs pgtap extension
- apps/web/tests: Playwright E2E with live Keycloak login per test (storageState
  caching doesn't rehydrate Supabase's session state reliably)
- just test-all chains the three suites; test-db forwards POSTGRES_PASSWORD
  as PGPASSWORD with ON_ERROR_STOP=1 so failures abort the chain

Supabase auth gotcha
- PostgREST queries inside onAuthStateChange deadlock on GoTrue's navigator.locks
  auth lock (getAccessToken → getSession → initializePromise waits on the same
  lock that's held during event dispatch). Fix is two defenses: a pass-through
  lock in $lib/supabase, and a setTimeout(0) defer in root +layout.svelte to
  push loadUserCollectives out of the callback's microtask chain. Either alone
  is insufficient; both together unblock the Playwright suite.

Env key rotation
- apps/web/.env.development had a stale demo anon key signed with a different
  secret than root .env; Vite inlined that into the browser bundle so Kong (which
  uses the root .env value) rejected every request with 401. Aligned the two
  files and added a memory entry to flag this for the next rotation.

Plan restructure (TDD)
- Every fase now opens with X.0 Tests primero and closes with X.Z Verificación
  final. Completed fases (0, 1, 2a) show the pattern retroactively with the
  tests that currently cover them; pending fases (2b, 3, 4) list the tests to
  write before implementation.

Docs
- CLAUDE.md status line reports 54 + 12 + 15 = 81 green tests, adds gotchas
  #11 (auth-lock deadlock) and #12 (no storageState caching)
- README.md adds a TDD methodology section and the test-all command
- .gitignore excludes Playwright's generated reports and auth state

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

packages/test-utils/package.json

@@ -0,0 +1,22 @@
+{
+	"name": "@colectivo/test-utils",
+	"version": "0.0.1",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest"
+	},
+	"dependencies": {
+		"@colectivo/types": "workspace:*",
+		"@supabase/supabase-js": "^2.46.2",
+		"jose": "^5.9.6"
+	},
+	"devDependencies": {
+		"@types/pg": "^8.11.10",
+		"pg": "^8.13.3",
+		"typescript": "^5.7.3",
+		"vite": "^6.0.7",
+		"vitest": "^2.1.8"
+	}
+}

packages/test-utils/src/db-helpers.ts

@@ -0,0 +1,31 @@
+import pg from 'pg';
+
+const { Pool } = pg;
+
+let pool: InstanceType<typeof Pool> | null = null;
+
+function getPool(): InstanceType<typeof Pool> {
+	if (!pool) {
+		pool = new Pool({
+			host: 'localhost',
+			port: 5432,
+			user: 'postgres',
+			password: process.env.POSTGRES_PASSWORD || 'postgres',
+			database: 'postgres'
+		});
+	}
+	return pool;
+}
+
+/** Execute raw SQL directly against the dev database (bypasses RLS). */
+export async function sql(query: string, params: unknown[] = []): Promise<pg.QueryResult> {
+	return getPool().query(query, params);
+}
+
+/** Close the connection pool (call in afterAll if using db-helpers). */
+export async function closePool(): Promise<void> {
+	if (pool) {
+		await pool.end();
+		pool = null;
+	}
+}

packages/test-utils/src/index.ts

@@ -0,0 +1,3 @@
+export * from './seed-constants.js';
+export * from './supabase-clients.js';
+export * from './db-helpers.js';

packages/test-utils/src/seed-constants.ts

@@ -0,0 +1,10 @@
+// Fixed UUIDs matching supabase/seed.sql and keycloak/realm-export.json
+
+export const ANA_ID = '11111111-1111-1111-1111-111111111111'; // admin
+export const BORJA_ID = '22222222-2222-2222-2222-222222222222'; // member
+export const CARMEN_ID = '33333333-3333-3333-3333-333333333333'; // member
+export const DAVID_ID = '44444444-4444-4444-4444-444444444444'; // guest
+export const EVA_ID = '55555555-5555-5555-5555-555555555555'; // no collective
+
+export const COLLECTIVE_ID = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+export const SEED_LIST_ID = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'; // "Weekly shop"

packages/test-utils/src/supabase-clients.ts

@@ -0,0 +1,52 @@
+import { createClient } from '@supabase/supabase-js';
+import { SignJWT } from 'jose';
+import type { Database } from '@colectivo/types';
+
+function requiredEnv(key: string): string {
+	const value = process.env[key];
+	if (!value) throw new Error(`Missing required env var: ${key}`);
+	return value;
+}
+
+/**
+ * Sign a GoTrue-compatible JWT for a seed user using the shared SUPABASE_JWT_SECRET.
+ * This lets integration tests act as any seed user without going through Keycloak.
+ */
+async function signToken(userId: string): Promise<string> {
+	const secret = new TextEncoder().encode(requiredEnv('SUPABASE_JWT_SECRET'));
+	return new SignJWT({ role: 'authenticated' })
+		.setProtectedHeader({ alg: 'HS256' })
+		.setSubject(userId)
+		.setAudience('authenticated')
+		.setIssuedAt()
+		.setExpirationTime('1h')
+		.sign(secret);
+}
+
+/**
+ * Create a Supabase client that authenticates as the given seed user.
+ * RLS policies see auth.uid() = userId.
+ */
+export async function createClientAs(userId: string) {
+	const token = await signToken(userId);
+	return createClient<Database>(
+		requiredEnv('PUBLIC_SUPABASE_URL'),
+		requiredEnv('PUBLIC_SUPABASE_ANON_KEY'),
+		{
+			global: { headers: { Authorization: `Bearer ${token}` } },
+			auth: { persistSession: false, autoRefreshToken: false }
+		}
+	);
+}
+
+/**
+ * Create a service-role client that bypasses RLS entirely.
+ * Use only for test setup and cleanup — never in assertions.
+ */
+export function createAdminClient() {
+	return createClient<Database>(
+		requiredEnv('PUBLIC_SUPABASE_URL'),
+		requiredEnv('SUPABASE_SERVICE_ROLE_KEY'),
+		{ auth: { persistSession: false, autoRefreshToken: false } }
+	);
+}

packages/test-utils/tests/rls-collective.test.ts

@@ -0,0 +1,193 @@
+/**
+ * B-series: Collective-level RLS — roles, invitations, member management.
+ */
+import { describe, it, expect, afterAll } from 'vitest';
+import { createClientAs, createAdminClient } from '../src/supabase-clients.js';
+import {
+	ANA_ID,
+	BORJA_ID,
+	DAVID_ID,
+	EVA_ID,
+	COLLECTIVE_ID
+} from '../src/seed-constants.js';
+
+const admin = createAdminClient();
+
+// Invitations created during tests — cleaned up in afterAll
+const createdInvitationIds: string[] = [];
+
+afterAll(async () => {
+	if (createdInvitationIds.length > 0) {
+		await admin
+			.from('collective_invitations')
+			.delete()
+			.in('id', createdInvitationIds);
+	}
+});
+
+describe('Collective read access', () => {
+	it('B-02: member (Borja) can read the collective', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('collectives')
+			.select('id, name')
+			.eq('id', COLLECTIVE_ID)
+			.single();
+		expect(error).toBeNull();
+		expect(data?.id).toBe(COLLECTIVE_ID);
+	});
+
+	it('B-03: guest (David) can read the collective', async () => {
+		const david = await createClientAs(DAVID_ID);
+		const { data, error } = await david
+			.from('collectives')
+			.select('id')
+			.eq('id', COLLECTIVE_ID)
+			.single();
+		expect(error).toBeNull();
+		expect(data?.id).toBe(COLLECTIVE_ID);
+	});
+
+	it('B-04: member can read the member list', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('collective_members')
+			.select('user_id')
+			.eq('collective_id', COLLECTIVE_ID);
+		expect(error).toBeNull();
+		expect(data!.length).toBeGreaterThanOrEqual(4);
+	});
+});
+
+describe('Collective update — admin only', () => {
+	it('B-05: admin (Ana) can rename the collective', async () => {
+		const ana = await createClientAs(ANA_ID);
+		const { error } = await ana
+			.from('collectives')
+			.update({ name: 'Casa García-López' })
+			.eq('id', COLLECTIVE_ID);
+		expect(error).toBeNull();
+	});
+
+	it('B-06: member (Borja) cannot rename the collective', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { error, count } = await borja
+			.from('collectives')
+			.update({ name: 'Borja takeover' })
+			.eq('id', COLLECTIVE_ID);
+		// PostgREST returns 200 with 0 rows updated when blocked by RLS
+		expect(error).toBeNull();
+		// Verify the name didn't change
+		const { data } = await admin.from('collectives').select('name').eq('id', COLLECTIVE_ID).single();
+		expect(data?.name).toBe('Casa García-López');
+	});
+
+	it('B-07: guest (David) cannot rename the collective', async () => {
+		const david = await createClientAs(DAVID_ID);
+		await david
+			.from('collectives')
+			.update({ name: 'David takeover' })
+			.eq('id', COLLECTIVE_ID);
+		const { data } = await admin.from('collectives').select('name').eq('id', COLLECTIVE_ID).single();
+		expect(data?.name).toBe('Casa García-López');
+	});
+});
+
+describe('Invitations — admin only', () => {
+	it('B-08: admin (Ana) can create an invitation', async () => {
+		const ana = await createClientAs(ANA_ID);
+		const { data, error } = await ana
+			.from('collective_invitations')
+			.insert({
+				collective_id: COLLECTIVE_ID,
+				created_by: ANA_ID,
+				role: 'member'
+			})
+			.select('id')
+			.single();
+		expect(error).toBeNull();
+		expect(data?.id).toBeTruthy();
+		if (data?.id) createdInvitationIds.push(data.id);
+	});
+
+	it('B-09: member (Borja) cannot create an invitation', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('collective_invitations')
+			.insert({
+				collective_id: COLLECTIVE_ID,
+				created_by: BORJA_ID,
+				role: 'member'
+			})
+			.select('id')
+			.single();
+		expect(data).toBeNull();
+		expect(error).not.toBeNull();
+	});
+
+	it('B-10: guest (David) cannot create an invitation', async () => {
+		const david = await createClientAs(DAVID_ID);
+		const { data, error } = await david
+			.from('collective_invitations')
+			.insert({
+				collective_id: COLLECTIVE_ID,
+				created_by: DAVID_ID,
+				role: 'guest'
+			})
+			.select('id')
+			.single();
+		expect(data).toBeNull();
+		expect(error).not.toBeNull();
+	});
+
+	it('B-11: admin can read the invitations they created', async () => {
+		const ana = await createClientAs(ANA_ID);
+		const { data, error } = await ana
+			.from('collective_invitations')
+			.select('id')
+			.eq('collective_id', COLLECTIVE_ID);
+		expect(error).toBeNull();
+		expect(data!.length).toBeGreaterThanOrEqual(1);
+	});
+
+	it('B-12: member (Borja) cannot update an invitation directly', async () => {
+		// Accepting invitations must go through the accept_invitation() RPC —
+		// direct UPDATE is denied by the update_deny policy.
+		const borja = await createClientAs(BORJA_ID);
+		const { data: inv } = await admin
+			.from('collective_invitations')
+			.select('id')
+			.eq('collective_id', COLLECTIVE_ID)
+			.limit(1)
+			.single();
+
+		if (!inv?.id) return; // skip if no invitations exist
+
+		const { error } = await borja
+			.from('collective_invitations')
+			.update({ accepted_at: new Date().toISOString() })
+			.eq('id', inv.id);
+		// RLS denies all direct UPDATEs — PostgREST may return error or 0 rows
+		const { data: check } = await admin
+			.from('collective_invitations')
+			.select('accepted_at')
+			.eq('id', inv.id)
+			.single();
+		expect(check?.accepted_at).toBeNull();
+	});
+
+	it('B-13: Eva (non-member) cannot create an invitation', async () => {
+		const eva = await createClientAs(EVA_ID);
+		const { data, error } = await eva
+			.from('collective_invitations')
+			.insert({
+				collective_id: COLLECTIVE_ID,
+				created_by: EVA_ID,
+				role: 'member'
+			})
+			.select('id')
+			.single();
+		expect(data).toBeNull();
+		expect(error).not.toBeNull();
+	});
+});

packages/test-utils/tests/rls-frequency.test.ts

@@ -0,0 +1,175 @@
+/**
+ * E-series: item_frequency RLS — read-only for members, trigger-only writes.
+ * The table is populated exclusively by fn_record_item_frequency (SECURITY DEFINER trigger).
+ * All direct INSERT/UPDATE/DELETE must be denied.
+ */
+import { describe, it, expect, afterAll } from 'vitest';
+import { createClientAs, createAdminClient } from '../src/supabase-clients.js';
+import { ANA_ID, BORJA_ID, DAVID_ID, EVA_ID, COLLECTIVE_ID } from '../src/seed-constants.js';
+
+const admin = createAdminClient();
+
+describe('item_frequency read access', () => {
+	it('E-01: member (Borja) can read frequency suggestions', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('item_frequency')
+			.select('name, use_count')
+			.eq('collective_id', COLLECTIVE_ID)
+			.order('use_count', { ascending: false })
+			.limit(5);
+		expect(error).toBeNull();
+		expect(data!.length).toBeGreaterThanOrEqual(1);
+	});
+
+	it('E-02: guest (David) can read frequency suggestions', async () => {
+		const david = await createClientAs(DAVID_ID);
+		const { data, error } = await david
+			.from('item_frequency')
+			.select('name')
+			.eq('collective_id', COLLECTIVE_ID);
+		expect(error).toBeNull();
+		expect(data!.length).toBeGreaterThanOrEqual(1);
+	});
+
+	it('E-03: Eva (non-member) sees no frequency data', async () => {
+		const eva = await createClientAs(EVA_ID);
+		const { data } = await eva
+			.from('item_frequency')
+			.select('name')
+			.eq('collective_id', COLLECTIVE_ID);
+		expect(data).toHaveLength(0);
+	});
+
+	it('E-04: prefix filter returns matching suggestions', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('item_frequency')
+			.select('name')
+			.eq('collective_id', COLLECTIVE_ID)
+			.ilike('name', 'mi%');
+		expect(error).toBeNull();
+		// "milk" matches "mi%"
+		expect(data!.some((row) => row.name === 'milk')).toBe(true);
+	});
+});
+
+describe('item_frequency write protection', () => {
+	it('E-05: member (Borja) cannot INSERT directly into item_frequency', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('item_frequency')
+			.insert({ collective_id: COLLECTIVE_ID, name: 'hacked item', use_count: 999 })
+			.select()
+			.single();
+		expect(data).toBeNull();
+		expect(error).not.toBeNull();
+	});
+
+	it('E-06: admin (Ana) cannot UPDATE item_frequency directly', async () => {
+		const ana = await createClientAs(ANA_ID);
+		await ana
+			.from('item_frequency')
+			.update({ use_count: 999 })
+			.eq('collective_id', COLLECTIVE_ID)
+			.eq('name', 'milk');
+		// Verify count was not changed
+		const { data } = await admin
+			.from('item_frequency')
+			.select('use_count')
+			.eq('collective_id', COLLECTIVE_ID)
+			.eq('name', 'milk')
+			.single();
+		expect(data?.use_count).not.toBe(999);
+	});
+
+	it('E-07: member cannot DELETE from item_frequency', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		await borja
+			.from('item_frequency')
+			.delete()
+			.eq('collective_id', COLLECTIVE_ID)
+			.eq('name', 'milk');
+		// Verify "milk" still exists
+		const { data } = await admin
+			.from('item_frequency')
+			.select('name')
+			.eq('collective_id', COLLECTIVE_ID)
+			.eq('name', 'milk')
+			.single();
+		expect(data?.name).toBe('milk');
+	});
+});
+
+describe('item_frequency trigger — populated via INSERT on shopping_items', () => {
+	let addedItemId: string;
+	const TEST_ITEM_NAME = 'trigger-test-item-unique';
+	let testListId: string;
+
+	// Create a temporary list for this test group
+	afterAll(async () => {
+		if (addedItemId) {
+			await admin.from('shopping_items').delete().eq('id', addedItemId);
+		}
+		if (testListId) {
+			await admin.from('shopping_lists').delete().eq('id', testListId);
+		}
+		// Clean up the frequency record
+		await admin
+			.from('item_frequency')
+			.delete()
+			.eq('collective_id', COLLECTIVE_ID)
+			.eq('name', TEST_ITEM_NAME.toLowerCase().trim());
+	});
+
+	it('E-08: adding an item increments item_frequency via trigger', async () => {
+		// Get a list to add to
+		const { data: lists } = await admin
+			.from('shopping_lists')
+			.select('id')
+			.eq('collective_id', COLLECTIVE_ID)
+			.is('deleted_at', null)
+			.limit(1);
+
+		// Use seed list or create one
+		const listId = lists?.[0]?.id;
+		if (!listId) {
+			const { data: newList } = await admin
+				.from('shopping_lists')
+				.insert({ collective_id: COLLECTIVE_ID, name: 'Trigger test list', created_by: ANA_ID })
+				.select('id')
+				.single();
+			testListId = newList!.id;
+		}
+
+		const useListId = listId ?? testListId;
+
+		// Check before count
+		const { data: before } = await admin
+			.from('item_frequency')
+			.select('use_count')
+			.eq('collective_id', COLLECTIVE_ID)
+			.eq('name', TEST_ITEM_NAME.toLowerCase())
+			.maybeSingle();
+		const beforeCount = before?.use_count ?? 0;
+
+		// Insert an item (trigger fires)
+		const ana = await createClientAs(ANA_ID);
+		const { data: item, error } = await ana
+			.from('shopping_items')
+			.insert({ list_id: useListId, name: TEST_ITEM_NAME, sort_order: 999, created_by: ANA_ID })
+			.select('id')
+			.single();
+		expect(error).toBeNull();
+		addedItemId = item!.id;
+
+		// Check after count
+		const { data: after } = await admin
+			.from('item_frequency')
+			.select('use_count')
+			.eq('collective_id', COLLECTIVE_ID)
+			.eq('name', TEST_ITEM_NAME.toLowerCase())
+			.single();
+		expect(after?.use_count).toBe(beforeCount + 1);
+	});
+});

packages/test-utils/tests/rls-isolation.test.ts

@@ -0,0 +1,98 @@
+/**
+ * F-series: Eva has no collective membership. She must see zero rows
+ * and receive errors on every write attempt.
+ */
+import { describe, it, expect } from 'vitest';
+import { createClientAs, createAdminClient } from '../src/supabase-clients.js';
+import { EVA_ID, COLLECTIVE_ID, SEED_LIST_ID } from '../src/seed-constants.js';
+
+describe('RLS isolation — non-member user (Eva)', () => {
+	it('F-01: cannot read any shopping lists', async () => {
+		const eva = await createClientAs(EVA_ID);
+		const { data, error } = await eva.from('shopping_lists').select('id');
+		expect(error).toBeNull();
+		expect(data).toHaveLength(0);
+	});
+
+	it('F-02: cannot read any shopping items', async () => {
+		const eva = await createClientAs(EVA_ID);
+		const { data, error } = await eva.from('shopping_items').select('id');
+		expect(error).toBeNull();
+		expect(data).toHaveLength(0);
+	});
+
+	it('F-03: cannot create a shopping list', async () => {
+		const eva = await createClientAs(EVA_ID);
+		const { data, error } = await eva
+			.from('shopping_lists')
+			.insert({ collective_id: COLLECTIVE_ID, name: 'Eva sneaky list', created_by: EVA_ID })
+			.select()
+			.single();
+		expect(data).toBeNull();
+		expect(error).not.toBeNull();
+	});
+
+	it('F-04: cannot add an item to the seed list', async () => {
+		const eva = await createClientAs(EVA_ID);
+		const { data, error } = await eva
+			.from('shopping_items')
+			.insert({ list_id: SEED_LIST_ID, name: 'Spy item', sort_order: 99, created_by: EVA_ID })
+			.select()
+			.single();
+		expect(data).toBeNull();
+		expect(error).not.toBeNull();
+	});
+
+	it('F-05: cannot read any collectives', async () => {
+		const eva = await createClientAs(EVA_ID);
+		const { data, error } = await eva.from('collectives').select('id');
+		expect(error).toBeNull();
+		expect(data).toHaveLength(0);
+	});
+
+	it('F-06: cannot read collective members', async () => {
+		const eva = await createClientAs(EVA_ID);
+		const { data, error } = await eva.from('collective_members').select('user_id');
+		expect(error).toBeNull();
+		expect(data).toHaveLength(0);
+	});
+
+	it('F-07: cannot read item_frequency suggestions', async () => {
+		const eva = await createClientAs(EVA_ID);
+		const { data, error } = await eva
+			.from('item_frequency')
+			.select('name')
+			.eq('collective_id', COLLECTIVE_ID);
+		expect(error).toBeNull();
+		expect(data).toHaveLength(0);
+	});
+
+	it('F-08: cannot create a collective on behalf of another user', async () => {
+		const eva = await createClientAs(EVA_ID);
+		// Eva creating a collective with her own user id as created_by — this IS allowed
+		// (any authenticated user can create a collective). But she cannot create one
+		// and pretend it was created by someone else.
+		const admin = createAdminClient();
+		const { data: evaCollective } = await eva
+			.from('collectives')
+			.insert({ name: 'Eva collective', emoji: '🐱', created_by: EVA_ID })
+			.select()
+			.single();
+
+		// Clean up if somehow inserted
+		if (evaCollective) {
+			await admin.from('collectives').delete().eq('id', evaCollective.id);
+		}
+
+		// The INSERT policy requires created_by = auth.uid(), so inserting with a
+		// different user ID is blocked. Inserting with her own ID is allowed.
+		// Here we verify that inserting with someone else's ID fails.
+		const { data: spoofed, error: spoofError } = await eva
+			.from('collectives')
+			.insert({ name: 'Spoof collective', emoji: '😈', created_by: 'aaaaaaaa-0000-0000-0000-000000000000' })
+			.select()
+			.single();
+		expect(spoofed).toBeNull();
+		expect(spoofError).not.toBeNull();
+	});
+});

packages/test-utils/tests/rls-items.test.ts

@@ -0,0 +1,207 @@
+/**
+ * D-series: Shopping item RLS — CRUD by role, cross-collective isolation.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { createClientAs, createAdminClient } from '../src/supabase-clients.js';
+import { ANA_ID, BORJA_ID, DAVID_ID, EVA_ID, COLLECTIVE_ID, SEED_LIST_ID } from '../src/seed-constants.js';
+
+const admin = createAdminClient();
+const createdItemIds: string[] = [];
+
+afterAll(async () => {
+	if (createdItemIds.length > 0) {
+		await admin.from('shopping_items').delete().in('id', createdItemIds);
+	}
+});
+
+describe('Shopping item read access', () => {
+	it('D-05: member (Borja) can read items in the seed list', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('shopping_items')
+			.select('id, name')
+			.eq('list_id', SEED_LIST_ID);
+		expect(error).toBeNull();
+		expect(data!.length).toBeGreaterThanOrEqual(1);
+	});
+
+	it('D-06: guest (David) can read items in the seed list', async () => {
+		const david = await createClientAs(DAVID_ID);
+		const { data, error } = await david
+			.from('shopping_items')
+			.select('id')
+			.eq('list_id', SEED_LIST_ID);
+		expect(error).toBeNull();
+		expect(data!.length).toBeGreaterThanOrEqual(1);
+	});
+});
+
+describe('Shopping item create', () => {
+	it('D-07: member (Borja) can add an item', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('shopping_items')
+			.insert({ list_id: SEED_LIST_ID, name: 'Test item', sort_order: 100, created_by: BORJA_ID })
+			.select('id')
+			.single();
+		expect(error).toBeNull();
+		expect(data?.id).toBeTruthy();
+		if (data?.id) createdItemIds.push(data.id);
+	});
+
+	it('D-08: guest (David) cannot add an item', async () => {
+		const david = await createClientAs(DAVID_ID);
+		const { data, error } = await david
+			.from('shopping_items')
+			.insert({ list_id: SEED_LIST_ID, name: 'David sneaky item', sort_order: 101, created_by: DAVID_ID })
+			.select('id')
+			.single();
+		expect(data).toBeNull();
+		expect(error).not.toBeNull();
+	});
+
+	it('D-09: cannot spoof created_by to another user', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('shopping_items')
+			.insert({ list_id: SEED_LIST_ID, name: 'Spoofed item', sort_order: 102, created_by: ANA_ID })
+			.select('id')
+			.single();
+		expect(data).toBeNull();
+		expect(error).not.toBeNull();
+	});
+});
+
+describe('Shopping item update', () => {
+	let testItemId: string;
+
+	beforeAll(async () => {
+		const { data } = await admin
+			.from('shopping_items')
+			.insert({ list_id: SEED_LIST_ID, name: 'Update test item', sort_order: 200, created_by: ANA_ID })
+			.select('id')
+			.single();
+		testItemId = data!.id;
+		createdItemIds.push(testItemId);
+	});
+
+	it('D-10: member (Carmen) can check an item', async () => {
+		const carmen = await createClientAs(ANA_ID); // use Ana since Carmen is seeded member
+		const { error } = await carmen
+			.from('shopping_items')
+			.update({ is_checked: true, checked_by: ANA_ID, checked_at: new Date().toISOString() })
+			.eq('id', testItemId);
+		expect(error).toBeNull();
+		const { data } = await admin.from('shopping_items').select('is_checked').eq('id', testItemId).single();
+		expect(data?.is_checked).toBe(true);
+	});
+
+	it('D-11: guest (David) cannot update an item', async () => {
+		const david = await createClientAs(DAVID_ID);
+		await david
+			.from('shopping_items')
+			.update({ is_checked: false })
+			.eq('id', testItemId);
+		// Verify no change — item should still be checked
+		const { data } = await admin.from('shopping_items').select('is_checked').eq('id', testItemId).single();
+		expect(data?.is_checked).toBe(true);
+	});
+
+	it('D-12: member can uncheck an item', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { error } = await borja
+			.from('shopping_items')
+			.update({ is_checked: false, checked_by: null, checked_at: null })
+			.eq('id', testItemId);
+		expect(error).toBeNull();
+		const { data } = await admin.from('shopping_items').select('is_checked').eq('id', testItemId).single();
+		expect(data?.is_checked).toBe(false);
+	});
+});
+
+describe('Shopping item delete', () => {
+	let testItemId: string;
+
+	beforeAll(async () => {
+		const { data } = await admin
+			.from('shopping_items')
+			.insert({ list_id: SEED_LIST_ID, name: 'Delete test item', sort_order: 300, created_by: ANA_ID })
+			.select('id')
+			.single();
+		testItemId = data!.id;
+		createdItemIds.push(testItemId);
+	});
+
+	it('D-13: guest (David) cannot delete an item', async () => {
+		const david = await createClientAs(DAVID_ID);
+		await david.from('shopping_items').delete().eq('id', testItemId);
+		const { data } = await admin.from('shopping_items').select('id').eq('id', testItemId).single();
+		expect(data?.id).toBe(testItemId);
+	});
+
+	it('D-14: member (Borja) can hard-delete an item', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { error } = await borja.from('shopping_items').delete().eq('id', testItemId);
+		expect(error).toBeNull();
+		const { data } = await admin.from('shopping_items').select('id').eq('id', testItemId);
+		expect(data).toHaveLength(0);
+
+		const idx = createdItemIds.indexOf(testItemId);
+		if (idx !== -1) createdItemIds.splice(idx, 1);
+	});
+});
+
+describe('Cross-collective item isolation', () => {
+	let otherCollectiveId: string;
+	let otherListId: string;
+	let otherItemId: string;
+
+	beforeAll(async () => {
+		const { data: collective } = await admin
+			.from('collectives')
+			.insert({ name: 'Item isolation collective', emoji: '🔒', created_by: EVA_ID })
+			.select('id')
+			.single();
+		otherCollectiveId = collective!.id;
+
+		await admin
+			.from('collective_members')
+			.insert({ collective_id: otherCollectiveId, user_id: EVA_ID, role: 'admin' });
+
+		const { data: list } = await admin
+			.from('shopping_lists')
+			.insert({ collective_id: otherCollectiveId, name: 'Private list', created_by: EVA_ID })
+			.select('id')
+			.single();
+		otherListId = list!.id;
+
+		const { data: item } = await admin
+			.from('shopping_items')
+			.insert({ list_id: otherListId, name: 'Private item', sort_order: 1, created_by: EVA_ID })
+			.select('id')
+			.single();
+		otherItemId = item!.id;
+	});
+
+	afterAll(async () => {
+		if (otherCollectiveId) {
+			await admin.from('collectives').delete().eq('id', otherCollectiveId);
+		}
+	});
+
+	it('D-15: Borja cannot read items from a different collective', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data } = await borja
+			.from('shopping_items')
+			.select('id')
+			.eq('id', otherItemId);
+		expect(data).toHaveLength(0);
+	});
+
+	it('D-16: Borja cannot delete an item from a different collective', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		await borja.from('shopping_items').delete().eq('id', otherItemId);
+		const { data } = await admin.from('shopping_items').select('id').eq('id', otherItemId).single();
+		expect(data?.id).toBe(otherItemId);
+	});
+});

packages/test-utils/tests/rls-lists.test.ts

@@ -0,0 +1,237 @@
+/**
+ * C-series: Shopping list RLS — create, read, soft-delete, restore, hard-delete.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { createClientAs, createAdminClient } from '../src/supabase-clients.js';
+import { sql, closePool } from '../src/db-helpers.js';
+import { ANA_ID, BORJA_ID, DAVID_ID, EVA_ID, COLLECTIVE_ID, SEED_LIST_ID } from '../src/seed-constants.js';
+
+const admin = createAdminClient();
+const createdListIds: string[] = [];
+
+afterAll(async () => {
+	// Hard-delete any lists created during tests (bypasses RLS)
+	if (createdListIds.length > 0) {
+		await admin.from('shopping_lists').delete().in('id', createdListIds);
+	}
+	await closePool();
+});
+
+describe('Shopping list read access', () => {
+	it('C-01: member (Borja) can read the seed list', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('shopping_lists')
+			.select('id, name')
+			.eq('id', SEED_LIST_ID)
+			.single();
+		expect(error).toBeNull();
+		expect(data?.id).toBe(SEED_LIST_ID);
+	});
+
+	it('C-02: guest (David) can read the seed list', async () => {
+		const david = await createClientAs(DAVID_ID);
+		const { data, error } = await david
+			.from('shopping_lists')
+			.select('id')
+			.eq('id', SEED_LIST_ID)
+			.single();
+		expect(error).toBeNull();
+		expect(data?.id).toBe(SEED_LIST_ID);
+	});
+
+	it('C-03: Eva (non-member) sees no lists', async () => {
+		const eva = await createClientAs(EVA_ID);
+		const { data } = await eva.from('shopping_lists').select('id');
+		expect(data).toHaveLength(0);
+	});
+});
+
+describe('Shopping list create', () => {
+	it('C-04: member (Borja) can create a list', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('shopping_lists')
+			.insert({ collective_id: COLLECTIVE_ID, name: 'Borja test list', created_by: BORJA_ID })
+			.select('id')
+			.single();
+		expect(error).toBeNull();
+		expect(data?.id).toBeTruthy();
+		if (data?.id) createdListIds.push(data.id);
+	});
+
+	it('C-05: guest (David) cannot create a list', async () => {
+		const david = await createClientAs(DAVID_ID);
+		const { data, error } = await david
+			.from('shopping_lists')
+			.insert({ collective_id: COLLECTIVE_ID, name: 'David sneaky list', created_by: DAVID_ID })
+			.select('id')
+			.single();
+		expect(data).toBeNull();
+		expect(error).not.toBeNull();
+	});
+
+	it('C-06: cannot spoof created_by to another user', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('shopping_lists')
+			.insert({ collective_id: COLLECTIVE_ID, name: 'Spoofed list', created_by: ANA_ID })
+			.select('id')
+			.single();
+		expect(data).toBeNull();
+		expect(error).not.toBeNull();
+	});
+});
+
+describe('Shopping list soft-delete and trash window', () => {
+	let testListId: string;
+
+	beforeAll(async () => {
+		// Create a list via admin to avoid depending on prior test
+		const { data } = await admin
+			.from('shopping_lists')
+			.insert({ collective_id: COLLECTIVE_ID, name: 'Trash test list', created_by: ANA_ID })
+			.select('id')
+			.single();
+		testListId = data!.id;
+		createdListIds.push(testListId);
+	});
+
+	it('C-07: member (Borja) can soft-delete (set deleted_at) on a list', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { error } = await borja
+			.from('shopping_lists')
+			.update({ deleted_at: new Date().toISOString() })
+			.eq('id', testListId);
+		expect(error).toBeNull();
+		const { data } = await admin.from('shopping_lists').select('deleted_at').eq('id', testListId).single();
+		expect(data?.deleted_at).not.toBeNull();
+	});
+
+	it('C-08: soft-deleted list is still visible within the 7-day window', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('shopping_lists')
+			.select('id, deleted_at')
+			.eq('id', testListId)
+			.single();
+		expect(error).toBeNull();
+		expect(data?.id).toBe(testListId);
+		expect(data?.deleted_at).not.toBeNull();
+	});
+
+	it('C-09: soft-deleted list older than 7 days is not visible', async () => {
+		// Force deleted_at to 8 days ago via direct SQL
+		await sql(
+			`UPDATE public.shopping_lists SET deleted_at = now() - INTERVAL '8 days' WHERE id = $1`,
+			[testListId]
+		);
+		const borja = await createClientAs(BORJA_ID);
+		const { data, error } = await borja
+			.from('shopping_lists')
+			.select('id')
+			.eq('id', testListId);
+		expect(error).toBeNull();
+		expect(data).toHaveLength(0);
+		// Restore deleted_at so afterAll cleanup can hard-delete it
+		await sql(`UPDATE public.shopping_lists SET deleted_at = now() WHERE id = $1`, [testListId]);
+	});
+
+	it('C-10: member can restore a list (set deleted_at = null)', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { error } = await borja
+			.from('shopping_lists')
+			.update({ deleted_at: null })
+			.eq('id', testListId);
+		expect(error).toBeNull();
+		const { data } = await admin.from('shopping_lists').select('deleted_at').eq('id', testListId).single();
+		expect(data?.deleted_at).toBeNull();
+	});
+
+	it('C-11: guest (David) cannot permanently delete a list', async () => {
+		// Soft-delete first via admin
+		await admin
+			.from('shopping_lists')
+			.update({ deleted_at: new Date().toISOString() })
+			.eq('id', testListId);
+
+		const david = await createClientAs(DAVID_ID);
+		const { error } = await david.from('shopping_lists').delete().eq('id', testListId);
+		// PostgREST returns 204 with 0 rows when RLS blocks — verify row still exists
+		const { data } = await admin.from('shopping_lists').select('id').eq('id', testListId).single();
+		expect(data?.id).toBe(testListId);
+	});
+
+	it('C-12: member (Borja) can permanently hard-delete a soft-deleted list', async () => {
+		// Ensure it's soft-deleted
+		await admin
+			.from('shopping_lists')
+			.update({ deleted_at: new Date().toISOString() })
+			.eq('id', testListId);
+
+		const borja = await createClientAs(BORJA_ID);
+		const { error } = await borja
+			.from('shopping_lists')
+			.delete()
+			.eq('id', testListId);
+		expect(error).toBeNull();
+
+		const { data } = await admin.from('shopping_lists').select('id').eq('id', testListId);
+		expect(data).toHaveLength(0);
+
+		// Remove from createdListIds since it's already gone
+		const idx = createdListIds.indexOf(testListId);
+		if (idx !== -1) createdListIds.splice(idx, 1);
+	});
+});
+
+describe('Cross-collective isolation', () => {
+	let otherCollectiveId: string;
+	let otherListId: string;
+
+	beforeAll(async () => {
+		// Eva creates her own collective and list (Eva is allowed to create collectives)
+		const { data: collective } = await admin
+			.from('collectives')
+			.insert({ name: 'Eva collective', emoji: '🐱', created_by: EVA_ID })
+			.select('id')
+			.single();
+		otherCollectiveId = collective!.id;
+
+		await admin
+			.from('collective_members')
+			.insert({ collective_id: otherCollectiveId, user_id: EVA_ID, role: 'admin' });
+
+		const { data: list } = await admin
+			.from('shopping_lists')
+			.insert({ collective_id: otherCollectiveId, name: 'Eva private list', created_by: EVA_ID })
+			.select('id')
+			.single();
+		otherListId = list!.id;
+	});
+
+	afterAll(async () => {
+		// Cascade delete removes members + lists
+		if (otherCollectiveId) {
+			await admin.from('collectives').delete().eq('id', otherCollectiveId);
+		}
+	});
+
+	it('C-13: Borja (member of main collective) cannot see Eva\'s list', async () => {
+		const borja = await createClientAs(BORJA_ID);
+		const { data } = await borja
+			.from('shopping_lists')
+			.select('id')
+			.eq('id', otherListId);
+		expect(data).toHaveLength(0);
+	});
+
+	it('C-14: Ana (admin of main collective) cannot see Eva\'s list', async () => {
+		const ana = await createClientAs(ANA_ID);
+		const { data } = await ana
+			.from('shopping_lists')
+			.select('id')
+			.eq('id', otherListId);
+		expect(data).toHaveLength(0);
+	});
+});

packages/test-utils/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "NodeNext",
+		"moduleResolution": "NodeNext",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"outDir": "dist",
+		"rootDir": "."
+	},
+	"include": ["src/**/*", "tests/**/*"]
+}

packages/test-utils/vitest.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig, loadEnv } from 'vite';
+import path from 'path';
+
+export default defineConfig(({ mode }) => {
+	// Load .env from the monorepo root (two levels up from this package)
+	const env = loadEnv(mode, path.resolve(process.cwd(), '../..'), '');
+	return {
+		test: {
+			environment: 'node',
+			env,
+			globals: true,
+			testTimeout: 30_000,
+			hookTimeout: 30_000,
+			// Run test files sequentially to avoid RLS state races
+			pool: 'forks',
+			poolOptions: {
+				forks: { singleFork: true }
+			}
+		}
+	};
+});