@react-spa-scaffold/mcp 2.2.0 → 2.3.0

package/templates/docs/SUPABASE_INTEGRATION.md

@@ -0,0 +1,310 @@
+# Supabase Integration
+
+Clerk-Supabase integration architecture, RLS patterns, and database operations.
+For quick-start usage and hooks, see [CLAUDE.md](../CLAUDE.md#database-supabase).
+
+---
+
+## Architecture
+
+```
+ClerkProvider
+    │
+    ▼
+useSession().getToken() ──► Clerk JWT (role: authenticated)
+    │
+    ▼
+SupabaseProvider
+    │
+    ▼
+createClient({ accessToken: getToken }) ──► Supabase API
+    │
+    ▼
+PostgreSQL + Row Level Security (RLS)
+    └── auth.uid() = Clerk user_id (JWT sub claim)
+```
+
+**Key Design Decisions:**
+
+- **No Supabase Auth** - Clerk handles authentication; Supabase validates JWTs via third-party provider
+- **Modern `accessToken` pattern** - No JWT templates needed (post April 2025)
+- **Automatic `role` claim** - Clerk integration adds `"role": "authenticated"` to JWTs, enabling RLS `TO authenticated` policies
+- **Session-based client** - Client recreates only on `session?.id` change, not every render
+- **TanStack Query integration** - All data fetching uses React Query for caching/invalidation
+- **RLS enforcement** - Security at database level via `auth.uid()` = Clerk `user_id`
+
+---
+
+## Setup
+
+### 1. Enable Clerk as Third-Party Auth Provider
+
+1. **Clerk Dashboard** → Integrations → Supabase → Activate
+2. Copy your **Clerk domain** (e.g., `your-app.clerk.accounts.dev`)
+3. **Supabase Dashboard** → Authentication → Sign In/Up → Add provider → Clerk
+4. Paste your Clerk domain
+
+### 2. Environment Variables
+
+| Variable                     | Description                                 |
+| ---------------------------- | ------------------------------------------- |
+| `VITE_SUPABASE_DATABASE_URL` | `https://your-project.supabase.co`          |
+| `VITE_SUPABASE_ANON_KEY`     | Client-side API key (respects RLS)          |
+| `SUPABASE_PROJECT_ID`        | For `npm run db:types` (subdomain from URL) |
+
+Both URL and key must be set together. Find them in Supabase Dashboard → Project Settings → Data API.
+
+### 3. Provider Hierarchy
+
+```tsx
+// main.tsx - SupabaseProvider MUST be inside ClerkProvider
+<ClerkProvider>
+  <SupabaseProvider>
+    <App />
+  </SupabaseProvider>
+</ClerkProvider>
+```
+
+---
+
+## File Structure
+
+```
+src/
+├── lib/supabase/
+│   └── client.ts           # createSupabaseClient(getToken)
+├── contexts/
+│   └── supabaseContext.tsx # SupabaseProvider + useSupabase hook
+├── hooks/supabase/
+│   ├── useSupabaseQuery.ts # Generic SELECT with TanStack Query
+│   └── useProfiles.ts      # Profile CRUD hooks
+├── types/
+│   ├── supabase.ts         # Auto-generated (npm run db:types)
+│   └── database.ts         # Convenience aliases (Profile, etc.)
+└── components/shared/
+    └── ProfileSync/        # Auto-sync Clerk user to Supabase
+```
+
+---
+
+## Database & RLS
+
+### Complete Table Example
+
+```sql
+-- Create table with user_id linked to Clerk
+CREATE TABLE profiles (
+  id TEXT PRIMARY KEY,              -- Clerk user_id (auth.uid())
+  email TEXT NOT NULL,
+  full_name TEXT,
+  avatar_url TEXT,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Enable Row Level Security
+ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
+
+-- RLS Policies (all four CRUD operations)
+CREATE POLICY "Users can view own profile"
+  ON profiles FOR SELECT TO authenticated
+  USING (id = (auth.uid())::text);
+
+CREATE POLICY "Users can insert own profile"
+  ON profiles FOR INSERT TO authenticated
+  WITH CHECK (id = (auth.uid())::text);
+
+CREATE POLICY "Users can update own profile"
+  ON profiles FOR UPDATE TO authenticated
+  USING (id = (auth.uid())::text)
+  WITH CHECK (id = (auth.uid())::text);
+
+CREATE POLICY "Users can delete own profile"
+  ON profiles FOR DELETE TO authenticated
+  USING (id = (auth.uid())::text);
+
+-- Auto-update timestamp trigger
+CREATE OR REPLACE FUNCTION update_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER profiles_updated_at
+  BEFORE UPDATE ON profiles
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at();
+```
+
+### RLS Policy Template
+
+For tables where `user_id` is NOT the primary key:
+
+```sql
+CREATE TABLE tasks (
+  id SERIAL PRIMARY KEY,
+  name TEXT NOT NULL,
+  user_id TEXT NOT NULL DEFAULT auth.jwt()->>'sub',  -- Auto-set from Clerk
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+ALTER TABLE tasks ENABLE ROW LEVEL SECURITY;
+
+-- Apply this pattern for each operation (SELECT, INSERT, UPDATE, DELETE)
+CREATE POLICY "Users can select own tasks"
+  ON tasks FOR SELECT TO authenticated
+  USING (user_id = (auth.uid())::text);
+
+CREATE POLICY "Users can insert own tasks"
+  ON tasks FOR INSERT TO authenticated
+  WITH CHECK (user_id = (auth.uid())::text);
+
+-- UPDATE needs both USING (existing rows) and WITH CHECK (new values)
+-- DELETE only needs USING
+```
+
+### SQL Functions Reference
+
+| Function              | Returns | Use Case                                       |
+| --------------------- | ------- | ---------------------------------------------- |
+| `auth.uid()`          | UUID    | Primary comparison (`::text` for TEXT columns) |
+| `auth.jwt()`          | JSON    | Access full JWT claims                         |
+| `auth.jwt()->>'sub'`  | TEXT    | User ID directly as text                       |
+| `(select auth.uid())` | UUID    | Performance optimization in RLS                |
+
+### MCP Tools for Database Operations
+
+| Tool                                       | Purpose                              |
+| ------------------------------------------ | ------------------------------------ |
+| `mcp__supabase__apply_migration`           | Apply DDL (CREATE, ALTER, DROP)      |
+| `mcp__supabase__execute_sql`               | Run queries (SELECT, INSERT, UPDATE) |
+| `mcp__supabase__list_tables`               | List all tables in schemas           |
+| `mcp__supabase__list_migrations`           | View applied migrations              |
+| `mcp__supabase__get_advisors`              | Check security/performance issues    |
+| `mcp__supabase__generate_typescript_types` | Generate types from schema           |
+
+### Type Generation
+
+After schema changes:
+
+```bash
+npm run db:types   # Regenerates src/types/supabase.ts
+```
+
+Add convenience aliases in `src/types/database.ts`:
+
+```typescript
+export type Profile = Tables<'profiles'>;
+export type ProfileInsert = TablesInsert<'profiles'>;
+export type ProfileUpdate = TablesUpdate<'profiles'>;
+```
+
+---
+
+## React Integration
+
+### Hooks Reference
+
+| Hook                        | Purpose                     | Returns                          |
+| --------------------------- | --------------------------- | -------------------------------- |
+| `useSupabase()`             | Direct client access        | `TypedSupabaseClient`            |
+| `useSupabaseQuery(options)` | Generic SELECT with caching | `UseQueryResult<T[]>`            |
+| `useProfile()`              | Current user's profile      | `{ profile, exists, isLoading }` |
+| `useCurrentProfile()`       | Raw profile query           | `UseQueryResult<Profile[]>`      |
+| `useUpsertProfile()`        | Create/update profile       | `UseMutationResult`              |
+| `useUpdateProfile()`        | Update current profile      | `UseMutationResult`              |
+| `useDeleteProfile()`        | Delete current profile      | `UseMutationResult`              |
+
+**`useSupabaseQuery` options:** `{ table, queryKey, select?, filter?, queryOptions? }`
+
+**Query key pattern:** All queries use `['supabase', table, ...queryKey]` for cache invalidation.
+
+For usage examples, see [CLAUDE.md](../CLAUDE.md#database-supabase).
+
+### ProfileSync Component
+
+Automatically syncs Clerk user data to Supabase on sign-in:
+
+```tsx
+import { ProfileSync } from '@/components/shared';
+
+function App() {
+  return (
+    <>
+      <ProfileSync /> {/* Optional: onSyncComplete, onSyncError callbacks */}
+      <Routes>...</Routes>
+    </>
+  );
+}
+```
+
+**Behavior:** Creates profile on first login, updates if email changed, runs once per mount.
+
+---
+
+## Testing
+
+### Mock Utilities
+
+Import from `@/test`:
+
+| Utility                                   | Purpose                                  |
+| ----------------------------------------- | ---------------------------------------- |
+| `setMockSupabaseData(data[])`             | Set data to return                       |
+| `setMockSupabaseError({ message, code })` | Simulate error                           |
+| `resetSupabaseMocks()`                    | Reset to defaults (call in `beforeEach`) |
+| `createProfile(overrides?)`               | Create mock profile                      |
+| `mockProfiles`                            | Pre-built profile array                  |
+
+For test examples, see [CLAUDE.md](../CLAUDE.md#database-supabase).
+
+---
+
+## Security
+
+- **Always enable RLS** on every table
+- **Use `anon` key** in client code (respects RLS)
+- **Never expose `service_role` key** (bypasses RLS)
+- **Cast `auth.uid()` to text** when comparing with TEXT columns: `(auth.uid())::text`
+- **Use `(select auth.uid())`** in policies for performance (prevents re-evaluation per row)
+- **Test with multiple accounts** to verify users can't access each other's data
+
+---
+
+## Deployment
+
+For Netlify deployment with Supabase integration, see [DEPLOYMENT.md](./DEPLOYMENT.md).
+
+---
+
+## Troubleshooting
+
+| Issue                                              | Cause                             | Fix                                                  |
+| -------------------------------------------------- | --------------------------------- | ---------------------------------------------------- |
+| "useSupabase must be used within SupabaseProvider" | Component outside provider        | Check `main.tsx` provider order                      |
+| 403 RLS Policy Violation                           | JWT missing `role: authenticated` | Verify Clerk-Supabase integration enabled            |
+| Empty arrays returned                              | RLS blocking access               | Check policies use `auth.uid()` correctly            |
+| Stale data after mutations                         | Missing invalidation              | Ensure `invalidateQueries(['supabase', 'profiles'])` |
+| Missing env vars error                             | Incomplete config                 | Both URL and key must be set                         |
+
+### Debug Token Claims
+
+```typescript
+const { session } = useSession();
+const token = await session?.getToken();
+if (token) {
+  const payload = JSON.parse(atob(token.split('.')[1]));
+  console.log(payload); // { sub: "user_xxx", role: "authenticated", ... }
+}
+```
+
+---
+
+## Resources
+
+- [AUTHENTICATION.md](./AUTHENTICATION.md) - Clerk authentication setup and configuration
+- [Supabase + Clerk Integration Guide](https://supabase.com/docs/guides/auth/third-party/clerk)
+- [Row Level Security Docs](https://supabase.com/docs/guides/auth/row-level-security)
+- [Clerk Supabase Docs](https://clerk.com/docs/integrations/databases/supabase)
+- [Supabase MCP Server](https://supabase.com/docs/guides/getting-started/mcp)

package/templates/docs/TESTING.md

@@ -30,7 +30,180 @@ import { screen, renderHook, act, waitFor, fireEvent } from '@testing-library/re
 import userEvent from '@testing-library/user-event';
 
 // Custom utilities from @/test
-import { render, mockMatchMedia, createTestQueryClient, server } from '@/test';
+import { render, server, mockMatchMedia, silenceConsoleError } from '@/test';
+```
+
+## Mock Infrastructure
+
+The codebase uses a unified mocking approach with shared constants and reusable utilities.
+
+### Directory Structure
+
+```
+src/test/                    # Test utilities
+├── index.ts                 # Public API - import from '@/test'
+├── clerkMock.tsx            # Clerk auth mocks
+├── supabaseMock.ts          # Supabase mocks
+├── mocks.ts                 # Browser API mocks
+└── providers.tsx            # Test render wrapper
+
+src/mocks/                   # MSW infrastructure
+├── constants.ts             # Shared test values (MOCK_USER, etc.)
+├── fixtures/                # Test data factories
+│   ├── profiles.ts          # createProfile(), mockProfiles
+│   └── todos.ts             # createTodo(), mockTodos
+├── handlers/                # MSW request handlers
+│   ├── supabase.ts          # Supabase API mocks
+│   └── todos.ts             # JSONPlaceholder mocks
+└── node.ts                  # MSW server setup
+```
+
+### Shared Constants
+
+All mocks use shared constants from `@/mocks/constants.ts` to ensure consistency:
+
+```typescript
+import { MOCK_USER, MOCK_SESSION_ID } from '@/test';
+
+// MOCK_USER.id = 'user_123'
+// MOCK_USER.email = 'test@example.com'
+// MOCK_USER.fullName = 'Test User'
+```
+
+### Clerk Mocks
+
+Control authentication state in tests:
+
+```typescript
+import { setMockClerkSignedIn, setMockClerkLoaded, resetClerkMocks } from '@/test';
+
+beforeEach(() => resetClerkMocks());
+
+it('shows sign-in when not authenticated', () => {
+  setMockClerkSignedIn(false);
+  render(<ProtectedRoute />);
+  expect(screen.getByTestId('sign-in-button')).toBeInTheDocument();
+});
+```
+
+### Supabase Mocks
+
+Control Supabase query responses:
+
+```typescript
+import { setMockSupabaseData, setMockSupabaseError, createProfile, resetSupabaseMocks } from '@/test';
+
+beforeEach(() => resetSupabaseMocks());
+
+it('displays profile data', async () => {
+  setMockSupabaseData([createProfile({ full_name: 'John Doe' })]);
+  render(<ProfileCard />);
+  await waitFor(() => expect(screen.getByText('John Doe')).toBeInTheDocument());
+});
+
+it('handles database error', async () => {
+  setMockSupabaseError({ message: 'Connection failed', code: 'NETWORK_ERROR' });
+  render(<ProfileCard />);
+  await waitFor(() => expect(screen.getByText(/error/i)).toBeInTheDocument());
+});
+```
+
+### Browser API Mocks
+
+Reusable mocks for common browser APIs:
+
+```typescript
+import { mockMatchMedia, mockScrollTo, mockAnimationFrame, silenceConsoleError, silenceConsoleWarn } from '@/test';
+
+// Media queries
+beforeEach(() => {
+  window.matchMedia = mockMatchMedia(true); // matches
+});
+
+// Scroll behavior
+it('scrolls to top', () => {
+  const scrollSpy = mockScrollTo();
+  triggerScroll();
+  expect(scrollSpy).toHaveBeenCalledWith(0, 0);
+});
+
+// Animation frames
+let getCallback: () => FrameRequestCallback | null;
+beforeEach(() => {
+  getCallback = mockAnimationFrame();
+});
+
+it('updates on animation frame', () => {
+  const callback = getCallback();
+  act(() => callback?.(0));
+  // assert state change
+});
+
+// Silence console during error tests
+it('handles error gracefully', () => {
+  const spy = silenceConsoleError();
+  triggerError();
+  expect(handleError).toHaveBeenCalled();
+  spy.mockRestore();
+});
+```
+
+### Fetch Mocking
+
+Use `vi.spyOn` for type-safe fetch mocking:
+
+```typescript
+beforeEach(() => {
+  vi.spyOn(global, 'fetch');
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+it('handles API response', async () => {
+  vi.mocked(global.fetch).mockResolvedValueOnce({
+    ok: true,
+    status: 200,
+    json: () => Promise.resolve({ data: 'test' }),
+  } as Response);
+
+  const result = await fetchData();
+  expect(result.data).toBe('test');
+});
+```
+
+### MSW (Mock Service Worker)
+
+MSW handlers intercept HTTP requests. Override per-test:
+
+```typescript
+import { http, HttpResponse } from 'msw';
+import { server } from '@/test';
+
+it('handles API error', async () => {
+  server.use(http.get('/api/todos', () => new HttpResponse(null, { status: 500 })));
+  // Test error handling...
+});
+```
+
+MSW handlers auto-reset after each test via `src/test-setup.ts`.
+
+### Test Data Factories
+
+Use factories to create test data with sensible defaults:
+
+```typescript
+import { createProfile, createTodo } from '@/test';
+
+// Override specific fields
+const profile = createProfile({ full_name: 'Custom Name' });
+const todo = createTodo({ completed: true });
+
+// Create multiple
+import { createProfiles, createTodos } from '@/mocks/fixtures';
+const profiles = createProfiles(5);
+const todos = createTodos(10, { userId: 1 });
 ```
 
 ## Core Patterns
@@ -50,25 +223,6 @@ it.each([
 // ❌ Avoid - repetitive individual tests
 it('formats 0 bytes', () => expect(formatBytes(0)).toBe('0 Bytes'));
 it('formats 1024 bytes', () => expect(formatBytes(1024)).toBe('1 KB'));
-it('formats 1MB', () => expect(formatBytes(1024 * 1024)).toBe('1 MB'));
-```
-
-### Use Shared Mocks
-
-```typescript
-import { mockMatchMedia } from '@/test';
-
-describe('useMediaQuery', () => {
-  beforeEach(() => {
-    window.matchMedia = mockMatchMedia(false);
-  });
-
-  it('detects desktop viewport', () => {
-    window.matchMedia = mockMatchMedia(true); // matches min-width query
-    const { result } = renderHook(() => useIsDesktop());
-    expect(result.current).toBe(true);
-  });
-});
 ```
 
 ### Component Testing
@@ -120,61 +274,6 @@ it('updates after async action', async () => {
 });
 ```
 
-### Mocking
-
-```typescript
-import { mockMatchMedia } from '@/test';
-
-// Mock modules at top of file
-vi.mock('@/lib/storage', () => ({
-  setStorageItem: vi.fn(() => true),
-}));
-
-// Mock browser APIs using shared utilities
-beforeEach(() => {
-  window.matchMedia = mockMatchMedia(false);
-});
-
-afterEach(() => {
-  vi.restoreAllMocks();
-});
-
-// Mock fetch for API tests
-const mockFetch = vi.fn();
-beforeEach(() => {
-  global.fetch = mockFetch;
-});
-mockFetch.mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({}) });
-```
-
-### MSW (Mock Service Worker)
-
-MSW handlers are organized in `src/mocks/`:
-
-```
-src/mocks/
-├── handlers/
-│   ├── index.ts     # Combines all handlers
-│   └── todos.ts     # Example domain handlers
-├── fixtures/
-│   └── todos.ts     # Response data
-├── browser.ts       # Browser worker setup
-└── node.ts          # Node server for tests
-```
-
-Override handlers per-test:
-
-```typescript
-import { http, HttpResponse, server } from '@/test';
-
-it('handles API error', async () => {
-  server.use(http.get('/api/todos', () => new HttpResponse(null, { status: 500 })));
-  // Test error handling...
-});
-```
-
-MSW handlers auto-reset after each test via `src/test-setup.ts`.
-
 ### Store Testing (Zustand)
 
 ```typescript
@@ -192,6 +291,24 @@ describe('preferencesStore', () => {
 });
 ```
 
+## Mock Best Practices
+
+### DO
+
+- ✅ Use shared constants (`MOCK_USER`, etc.) for consistency
+- ✅ Use `vi.spyOn()` for type-safe mocking
+- ✅ Use `vi.mocked()` wrapper for TypeScript support
+- ✅ Reset mocks in `beforeEach`/`afterEach`
+- ✅ Restore mocks after silencing console
+- ✅ Use factory functions for test data
+
+### DON'T
+
+- ❌ Hardcode user IDs or emails across files
+- ❌ Use `global.fetch = mockFn` (use `vi.spyOn` instead)
+- ❌ Create duplicate mock utilities in test files
+- ❌ Forget to reset stateful mocks between tests
+
 ## Test Organization
 
 ### Structure Within Test Files
@@ -239,9 +356,10 @@ npm run test:ui       # Visual UI
 ## Checklist for New Tests
 
 - [ ] File follows `[name].test.ts(x)` naming
+- [ ] Uses shared mocks from `@/test`
+- [ ] Uses shared constants (`MOCK_USER`, etc.)
 - [ ] Uses `it.each` for parameterized cases
-- [ ] Mocks are cleared in `beforeEach`/`afterEach`
-- [ ] No duplicate helper functions
+- [ ] Mocks are reset in `beforeEach`/`afterEach`
 - [ ] Tests behavior, not implementation
 - [ ] Async tests use `await`/`waitFor` properly
 - [ ] Coverage threshold maintained (80%)

package/templates/e2e/auth/auth.setup.ts

@@ -0,0 +1,60 @@
+import { clerk, clerkSetup } from '@clerk/testing/playwright';
+import { expect, test as setup } from '@playwright/test';
+
+import { ASYNC_CONTENT_TIMEOUT, AUTH_STATE_FILE } from '../fixtures';
+
+// Setup must be run serially for Clerk initialization
+setup.describe.configure({ mode: 'serial' });
+
+/**
+ * Configure Playwright with Clerk testing token.
+ * This obtains a Testing Token when the test suite starts.
+ *
+ * Required: CLERK_SECRET_KEY environment variable
+ */
+setup('global setup', async () => {
+  // Skip if CLERK_SECRET_KEY is not set
+  if (!process.env.CLERK_SECRET_KEY) {
+    setup.skip(true, 'CLERK_SECRET_KEY required for authenticated tests');
+    return;
+  }
+  await clerkSetup();
+});
+
+/**
+ * Authenticate and save state to storage.
+ * This creates a reusable auth state for authenticated tests.
+ *
+ * Required environment variables:
+ * - E2E_CLERK_USER_USERNAME: Test user email
+ * - E2E_CLERK_USER_PASSWORD: Test user password
+ */
+setup('authenticate and save state', async ({ page }) => {
+  const username = process.env.E2E_CLERK_USER_USERNAME;
+  const password = process.env.E2E_CLERK_USER_PASSWORD;
+
+  // Skip auth setup if credentials are not provided
+  if (!username || !password) {
+    setup.skip(true, 'E2E_CLERK_USER_USERNAME and E2E_CLERK_USER_PASSWORD required for authenticated tests');
+    return;
+  }
+
+  // Navigate to app and sign in
+  await page.goto('/');
+
+  await clerk.signIn({
+    page,
+    signInParams: {
+      strategy: 'password',
+      identifier: username,
+      password: password,
+    },
+  });
+
+  // Verify authentication succeeded by checking for authenticated UI
+  await page.goto('/profile');
+  await expect(page.getByText('Your Profile')).toBeVisible({ timeout: ASYNC_CONTENT_TIMEOUT });
+
+  // Save authentication state for reuse in other tests
+  await page.context().storageState({ path: AUTH_STATE_FILE });
+});

package/templates/e2e/fixtures/index.ts

@@ -1,4 +1,15 @@
 import type { Page } from '@playwright/test';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+// ESM-compatible path resolution
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Path to Clerk auth state file for authenticated tests */
+export const AUTH_STATE_FILE = join(__dirname, '../.clerk/user.json');
+
+/** Default timeout for waiting on profile/async content to load */
+export const ASYNC_CONTENT_TIMEOUT = 10000;
 
 /**
  * Navigate to page with clean state (clears localStorage).