@react-spa-scaffold/mcp 2.1.1 → 2.3.0

package/templates/src/lib/createSelectors.test.ts

@@ -0,0 +1,136 @@
+import { act, renderHook } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { create } from 'zustand';
+
+import { createSelectors } from './createSelectors';
+
+interface TestState {
+  count: number;
+  name: string;
+  increment: () => void;
+  setName: (name: string) => void;
+}
+
+describe('createSelectors', () => {
+  it('creates auto-generated selectors for all state properties', () => {
+    const useStoreBase = create<TestState>()((set) => ({
+      count: 0,
+      name: 'test',
+      increment: () => set((state) => ({ count: state.count + 1 })),
+      setName: (name) => set({ name }),
+    }));
+
+    const useStore = createSelectors(useStoreBase);
+
+    // Verify .use namespace exists
+    expect(useStore.use).toBeDefined();
+    expect(typeof useStore.use.count).toBe('function');
+    expect(typeof useStore.use.name).toBe('function');
+    expect(typeof useStore.use.increment).toBe('function');
+    expect(typeof useStore.use.setName).toBe('function');
+  });
+
+  it('selectors return correct state values', () => {
+    const useStoreBase = create<TestState>()((set) => ({
+      count: 42,
+      name: 'hello',
+      increment: () => set((state) => ({ count: state.count + 1 })),
+      setName: (name) => set({ name }),
+    }));
+
+    const useStore = createSelectors(useStoreBase);
+
+    const { result: countResult } = renderHook(() => useStore.use.count());
+    const { result: nameResult } = renderHook(() => useStore.use.name());
+
+    expect(countResult.current).toBe(42);
+    expect(nameResult.current).toBe('hello');
+  });
+
+  it('selectors return action functions', () => {
+    const useStoreBase = create<TestState>()((set) => ({
+      count: 0,
+      name: 'test',
+      increment: () => set((state) => ({ count: state.count + 1 })),
+      setName: (name) => set({ name }),
+    }));
+
+    const useStore = createSelectors(useStoreBase);
+
+    const { result: incrementResult } = renderHook(() => useStore.use.increment());
+    const { result: setNameResult } = renderHook(() => useStore.use.setName());
+
+    expect(typeof incrementResult.current).toBe('function');
+    expect(typeof setNameResult.current).toBe('function');
+  });
+
+  it('actions from selectors update state correctly', () => {
+    const useStoreBase = create<TestState>()((set) => ({
+      count: 0,
+      name: 'initial',
+      increment: () => set((state) => ({ count: state.count + 1 })),
+      setName: (name) => set({ name }),
+    }));
+
+    const useStore = createSelectors(useStoreBase);
+
+    // Get initial state
+    expect(useStore.getState().count).toBe(0);
+    expect(useStore.getState().name).toBe('initial');
+
+    // Use action from selector
+    const { result: incrementResult } = renderHook(() => useStore.use.increment());
+
+    act(() => {
+      incrementResult.current();
+    });
+
+    expect(useStore.getState().count).toBe(1);
+
+    // Use another action
+    const { result: setNameResult } = renderHook(() => useStore.use.setName());
+
+    act(() => {
+      setNameResult.current('updated');
+    });
+
+    expect(useStore.getState().name).toBe('updated');
+  });
+
+  it('preserves original store functionality', () => {
+    const useStoreBase = create<TestState>()((set) => ({
+      count: 0,
+      name: 'test',
+      increment: () => set((state) => ({ count: state.count + 1 })),
+      setName: (name) => set({ name }),
+    }));
+
+    const useStore = createSelectors(useStoreBase);
+
+    // Original hook still works
+    const { result } = renderHook(() => useStore((state) => state.count));
+    expect(result.current).toBe(0);
+
+    // getState still works
+    expect(useStore.getState().count).toBe(0);
+
+    // setState still works
+    act(() => {
+      useStore.setState({ count: 100 });
+    });
+    expect(useStore.getState().count).toBe(100);
+
+    // subscribe still works
+    let subscribedValue = 0;
+    const unsub = useStore.subscribe((state) => {
+      subscribedValue = state.count;
+    });
+
+    act(() => {
+      useStore.setState({ count: 200 });
+    });
+    expect(subscribedValue).toBe(200);
+
+    unsub();
+  });
+});

package/templates/src/lib/createSelectors.ts

@@ -0,0 +1,31 @@
+import type { StoreApi, UseBoundStore } from 'zustand';
+
+/**
+ * Type that extends a Zustand store with auto-generated selectors.
+ * Adds a `use` namespace with selector functions for each store property.
+ */
+type WithSelectors<S> = S extends { getState: () => infer T } ? S & { use: { [K in keyof T]: () => T[K] } } : never;
+
+/**
+ * Wraps a Zustand store and automatically generates selector hooks for all properties.
+ *
+ * @example
+ * ```tsx
+ * const useStoreBase = create<State>()((set) => ({ count: 0 }));
+ * export const useStore = createSelectors(useStoreBase);
+ *
+ * // Usage in components:
+ * const count = useStore.use.count();
+ * const increment = useStore.use.increment();
+ * ```
+ */
+export function createSelectors<S extends UseBoundStore<StoreApi<object>>>(_store: S): WithSelectors<S> {
+  const store = _store as WithSelectors<typeof _store>;
+  store.use = {} as WithSelectors<S>['use'];
+
+  for (const key of Object.keys(store.getState())) {
+    (store.use as Record<string, () => unknown>)[key] = () => store((state) => state[key as keyof typeof state]);
+  }
+
+  return store;
+}

package/templates/src/lib/env.ts

@@ -1,25 +1,40 @@
 /**
  * Environment variable validation using Zod.
  * Validates at runtime to catch missing/invalid env vars early.
+ *
+ * All env vars are REQUIRED. The MCP scaffold tool strips unused vars
+ * when scaffolding builds without certain features.
  */
 
 import { z } from 'zod';
 
+/**
+ * Transforms string env var to boolean.
+ * - 'true', '1' → true
+ * - 'false', '0' → false
+ */
+const booleanEnv = z.enum(['true', 'false', '1', '0']).transform((val) => val === 'true' || val === '1');
+
 const envSchema = z.object({
-  VITE_APP_NAME: z.string().min(1).optional(),
-  VITE_APP_URL: z.string().url().optional(),
-  VITE_API_URL: z.string().url().optional(),
-  VITE_SENTRY_DSN: z.string().url().optional(),
-  MODE: z.enum(['development', 'production', 'test']).default('development'),
-  DEV: z.boolean().default(false),
-  PROD: z.boolean().default(false),
+  VITE_APP_NAME: z.string().min(1),
+  VITE_APP_URL: z.string().url(),
+  VITE_API_URL: z.string().url(),
+  VITE_SENTRY_DSN: z.string().url(),
+  VITE_SENTRY_ENABLED: booleanEnv,
+  VITE_CLERK_PUBLISHABLE_KEY: z.string().min(1),
+  VITE_SUPABASE_DATABASE_URL: z.string().url(),
+  VITE_SUPABASE_ANON_KEY: z.string().min(1),
+  VITE_PERF_TEST: booleanEnv,
+  MODE: z.enum(['development', 'production', 'test']),
+  DEV: z.boolean(),
+  PROD: z.boolean(),
 });
 
 export type Env = z.infer<typeof envSchema>;
 
 /**
  * Validate environment variables and return typed env object.
- * Throws if validation fails in production.
+ * Throws if any required env var is missing or invalid.
  */
 export function validateEnv(): Env {
   const env = {
@@ -27,6 +42,11 @@ export function validateEnv(): Env {
     VITE_APP_URL: import.meta.env.VITE_APP_URL,
     VITE_API_URL: import.meta.env.VITE_API_URL,
     VITE_SENTRY_DSN: import.meta.env.VITE_SENTRY_DSN,
+    VITE_SENTRY_ENABLED: import.meta.env.VITE_SENTRY_ENABLED,
+    VITE_CLERK_PUBLISHABLE_KEY: import.meta.env.VITE_CLERK_PUBLISHABLE_KEY,
+    VITE_SUPABASE_DATABASE_URL: import.meta.env.VITE_SUPABASE_DATABASE_URL,
+    VITE_SUPABASE_ANON_KEY: import.meta.env.VITE_SUPABASE_ANON_KEY,
+    VITE_PERF_TEST: import.meta.env.VITE_PERF_TEST,
     MODE: import.meta.env.MODE,
     DEV: import.meta.env.DEV,
     PROD: import.meta.env.PROD,
@@ -35,15 +55,17 @@ export function validateEnv(): Env {
   const result = envSchema.safeParse(env);
 
   if (!result.success) {
-    const errors = result.error.format();
-    console.error('Environment validation failed:', errors);
+    const errors = result.error.flatten();
+    const fieldErrors = Object.entries(errors.fieldErrors)
+      .map(([key, msgs]) => `${key}: ${(msgs as string[]).join(', ')}`)
+      .join('; ');
+    const formErrors = errors.formErrors.join('; ');
+    const allErrors = [fieldErrors, formErrors].filter(Boolean).join('; ');
 
-    if (import.meta.env.PROD) {
-      throw new Error('Invalid environment configuration');
-    }
+    throw new Error(`Environment validation failed: ${allErrors}`);
   }
 
-  return result.success ? result.data : (env as Env);
+  return result.data;
 }
 
 /**

package/templates/src/lib/index.ts

@@ -5,10 +5,13 @@
 
 export { cn } from './utils';
 export { STORAGE_KEYS, isAppKey } from './storageKeys';
-export { APP_CONFIG, SENTRY_CONFIG } from './config';
-export { API_CONFIG } from './api';
+export { APP_CONFIG, API_CONFIG, SENTRY_CONFIG, CLERK_CONFIG, SUPABASE_CONFIG, PERFORMANCE_CONFIG } from './config';
 export { ROUTES, type AppRoute } from './routes';
 export { env, validateEnv, type Env } from './env';
 export { api, ApiClientError } from './api';
 export { getStorageItem, setStorageItem, removeStorageItem, clearAppStorage } from './storage';
 export { registerFormSchema, type RegisterFormData } from './validations';
+export { createSelectors } from './createSelectors';
+
+// Supabase
+export { createSupabaseClient, type TypedSupabaseClient, type GetTokenFn } from './supabase';

package/templates/src/lib/routes.ts

@@ -5,6 +5,7 @@
 
 export const ROUTES = {
   HOME: '/',
+  PROFILE: '/profile',
   NOT_FOUND: '*',
 } as const;
 

package/templates/src/lib/sentry.ts

@@ -0,0 +1,58 @@
+import type * as SentryType from '@sentry/react';
+
+import { SENTRY_CONFIG } from './config';
+import { env } from './env';
+
+let sentryInstance: typeof SentryType | null = null;
+
+/**
+ * Initialize Sentry error tracking.
+ * Only runs in production when enabled and VITE_SENTRY_DSN is configured.
+ */
+export async function initSentry(): Promise<typeof SentryType | null> {
+  // Skip if disabled, in development, already initialized, or no DSN
+  if (!SENTRY_CONFIG.enabled || env.DEV || sentryInstance || !SENTRY_CONFIG.dsn) {
+    return sentryInstance;
+  }
+
+  const sentry = await import('@sentry/react');
+
+  sentry.init({
+    dsn: SENTRY_CONFIG.dsn,
+    environment: SENTRY_CONFIG.environment,
+    sendDefaultPii: true,
+    integrations: [sentry.browserTracingIntegration()],
+    tracesSampleRate: SENTRY_CONFIG.tracesSampleRate,
+  });
+
+  sentryInstance = sentry;
+  return sentryInstance;
+}
+
+/**
+ * Lazily initialize Sentry after the app is interactive.
+ * Uses requestIdleCallback with fallback for older browsers.
+ */
+export function lazySentryInit(): void {
+  const init = () => void initSentry();
+
+  if ('requestIdleCallback' in window) {
+    window.requestIdleCallback(init, { timeout: 2000 });
+  } else {
+    setTimeout(init, 1000);
+  }
+}
+
+interface CaptureContext {
+  componentStack?: string;
+}
+
+/**
+ * Capture an exception to Sentry.
+ * No-op if Sentry is not initialized.
+ */
+export function captureException(error: unknown, context?: CaptureContext): void {
+  sentryInstance?.captureException(error, {
+    extra: context?.componentStack ? { componentStack: context.componentStack } : undefined,
+  });
+}

package/templates/src/lib/storage.ts

@@ -4,7 +4,8 @@
 
 import { STORAGE_KEYS } from './storageKeys';
 
-type StorageKey = (typeof STORAGE_KEYS)[keyof typeof STORAGE_KEYS];
+// Extract only string keys (exclude functions if any are added later)
+type StorageKey = Extract<(typeof STORAGE_KEYS)[keyof typeof STORAGE_KEYS], string>;
 
 /**
  * Check if we're in a browser environment
@@ -81,7 +82,10 @@ export function clearAppStorage(): boolean {
 
   try {
     Object.values(STORAGE_KEYS).forEach((key) => {
-      localStorage.removeItem(key);
+      // Skip function keys (like prompt()) if any exist
+      if (typeof key === 'string') {
+        localStorage.removeItem(key);
+      }
     });
     return true;
   } catch (error) {

package/templates/src/lib/supabase/client.ts

@@ -0,0 +1,58 @@
+/**
+ * Supabase client factory with Clerk authentication integration.
+ *
+ * Uses the modern `accessToken` pattern for third-party auth providers.
+ * The Clerk session token is automatically injected into Supabase requests.
+ *
+ * @see https://supabase.com/docs/guides/auth/third-party/clerk
+ */
+
+import { createClient, type SupabaseClient } from '@supabase/supabase-js';
+
+import type { Database } from '@/types/database';
+
+import { SUPABASE_CONFIG } from '../config';
+
+/**
+ * Typed Supabase client with database schema.
+ */
+export type TypedSupabaseClient = SupabaseClient<Database>;
+
+/**
+ * Token getter function type.
+ * Returns the Clerk session token or null if not authenticated.
+ */
+export type GetTokenFn = () => Promise<string | null>;
+
+/**
+ * Creates a Supabase client configured with Clerk authentication.
+ *
+ * Uses the `accessToken` configuration option which is the recommended
+ * approach for third-party auth providers like Clerk.
+ *
+ * @param getToken - Async function that returns the Clerk session token
+ * @returns Typed Supabase client
+ * @throws Error if Supabase environment variables are not configured
+ *
+ * @example
+ * ```tsx
+ * const { session } = useSession();
+ * const supabase = createSupabaseClient(() => session?.getToken() ?? null);
+ *
+ * // Now use supabase with Clerk auth
+ * const { data } = await supabase.from('profiles').select();
+ * ```
+ */
+export function createSupabaseClient(getToken: GetTokenFn): TypedSupabaseClient {
+  if (!SUPABASE_CONFIG.isConfigured) {
+    throw new Error(
+      'Missing Supabase environment variables. ' +
+        'Set VITE_SUPABASE_DATABASE_URL and VITE_SUPABASE_ANON_KEY in your .env file.',
+    );
+  }
+
+  // Type assertion safe here - isConfigured guarantees both are defined
+  return createClient<Database>(SUPABASE_CONFIG.url!, SUPABASE_CONFIG.anonKey!, {
+    accessToken: getToken,
+  });
+}

package/templates/src/lib/supabase/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Supabase client exports.
+ */
+
+export { createSupabaseClient, type TypedSupabaseClient, type GetTokenFn } from './client';

package/templates/src/main.tsx

@@ -6,42 +6,26 @@ import { BrowserRouter } from 'react-router';
 import './index.css';
 import { ErrorBoundary } from '@/components/shared';
 import { Toaster } from '@/components/ui/sonner';
+import { ClerkThemeProvider } from '@/contexts/clerkContext';
 import { MobileProvider } from '@/contexts/mobileContext';
 import { PerformanceProviderWrapper } from '@/contexts/performanceContext';
 import { QueryProvider } from '@/contexts/queryContext';
+import { SupabaseProvider } from '@/contexts/supabaseContext';
 import { i18n, initI18n } from '@/i18n';
-import { SENTRY_CONFIG } from '@/lib/config';
+import { CLERK_CONFIG } from '@/lib/config';
+import { initSentry } from '@/lib/sentry';
 import { initPreferencesSync } from '@/stores/preferencesStore';
 
 import App from './App';
 
-/**
- * Lazy load Sentry after initial render to avoid blocking web vitals.
- * Returns the Sentry module for use in global error handlers.
- */
-async function initSentry() {
-  if (import.meta.env.PROD && SENTRY_CONFIG.enabled && SENTRY_CONFIG.dsn) {
-    try {
-      const Sentry = await import('@sentry/react');
-      Sentry.init({
-        dsn: SENTRY_CONFIG.dsn,
-        sendDefaultPii: true,
-        integrations: [Sentry.browserTracingIntegration()],
-        tracesSampleRate: SENTRY_CONFIG.tracesSampleRate,
-      });
-      return Sentry;
-    } catch (error) {
-      console.error('Failed to initialize Sentry:', error);
-    }
-  }
-  return null;
-}
+/** Sentry module type for error handlers */
+type SentryModule = Awaited<ReturnType<typeof initSentry>>;
 
 /**
  * Setup global error handlers for uncaught errors and promise rejections.
  * @param Sentry - The Sentry module or null if not available
  */
-function setupGlobalErrorHandlers(Sentry: Awaited<ReturnType<typeof initSentry>>) {
+function setupGlobalErrorHandlers(Sentry: SentryModule) {
   // Handle uncaught errors
   window.onerror = (message, source, lineno, colno, error) => {
     console.error('Uncaught error:', { message, source, lineno, colno, error });
@@ -74,14 +58,18 @@ initI18n().then(() => {
       <QueryProvider>
         <I18nProvider i18n={i18n}>
           <BrowserRouter>
-            <MobileProvider>
-              <ErrorBoundary>
-                <PerformanceProviderWrapper>
-                  <App />
-                  <Toaster />
-                </PerformanceProviderWrapper>
-              </ErrorBoundary>
-            </MobileProvider>
+            <ClerkThemeProvider publishableKey={CLERK_CONFIG.publishableKey!}>
+              <SupabaseProvider>
+                <MobileProvider>
+                  <ErrorBoundary>
+                    <PerformanceProviderWrapper>
+                      <App />
+                      <Toaster />
+                    </PerformanceProviderWrapper>
+                  </ErrorBoundary>
+                </MobileProvider>
+              </SupabaseProvider>
+            </ClerkThemeProvider>
           </BrowserRouter>
         </I18nProvider>
       </QueryProvider>

package/templates/src/mocks/constants.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared test constants for mocks and fixtures.
+ *
+ * Use these values across all mocks to ensure consistency
+ * between Clerk, Supabase, and other test utilities.
+ */
+
+/** Mock user data - consistent across all auth/database mocks */
+export const MOCK_USER = {
+  id: 'user_123',
+  email: 'test@example.com',
+  firstName: 'Test',
+  lastName: 'User',
+  fullName: 'Test User',
+  avatarUrl: 'https://example.com/avatar.jpg',
+} as const;
+
+/** Mock session ID for auth mocks */
+export const MOCK_SESSION_ID = 'sess_123';
+
+/** Mock auth token for API requests */
+export const MOCK_AUTH_TOKEN = 'mock-auth-token';
+
+/** Mock Supabase URL for MSW handlers */
+export const MOCK_SUPABASE_URL = 'https://mock.supabase.co';
+
+/** Default timestamps for fixtures */
+export const MOCK_TIMESTAMPS = {
+  created: '2024-01-01T00:00:00.000Z',
+  updated: '2024-01-01T00:00:00.000Z',
+} as const;

package/templates/src/mocks/fixtures/index.ts

@@ -1 +1,3 @@
-export { mockTodos, createTodo, createTodos, type Todo } from './todos';
+export { createTodo, createTodos, mockTodos, type Todo } from './todos';
+export { createProfile, createProfiles, mockProfiles } from './profiles';
+export { createUser, createUsers, defaultUser, mockUsers, type MockUser } from './users';

package/templates/src/mocks/fixtures/profiles.ts

@@ -0,0 +1,55 @@
+/**
+ * Mock profile fixtures for testing.
+ * Used by MSW handlers to simulate Supabase responses.
+ */
+
+import type { Profile } from '@/types/database';
+
+import { MOCK_TIMESTAMPS, MOCK_USER } from '../constants';
+
+/** Counter for unique ID generation */
+let idCounter = 0;
+
+/**
+ * Sample profiles for MSW handlers.
+ */
+export const mockProfiles: Profile[] = [
+  {
+    id: MOCK_USER.id,
+    email: MOCK_USER.email,
+    full_name: MOCK_USER.fullName,
+    avatar_url: null,
+    created_at: MOCK_TIMESTAMPS.created,
+    updated_at: MOCK_TIMESTAMPS.updated,
+  },
+];
+
+/**
+ * Create a profile with optional overrides.
+ */
+export function createProfile(overrides: Partial<Profile> = {}): Profile {
+  const now = new Date().toISOString();
+  return {
+    id: `user_${Date.now()}_${idCounter++}`,
+    email: MOCK_USER.email,
+    full_name: MOCK_USER.fullName,
+    avatar_url: null,
+    created_at: now,
+    updated_at: now,
+    ...overrides,
+  };
+}
+
+/**
+ * Create multiple profiles.
+ */
+export function createProfiles(count: number, overrides: Partial<Profile> = {}): Profile[] {
+  return Array.from({ length: count }, (_, i) =>
+    createProfile({
+      id: `user_${i + 1}`,
+      email: `user${i + 1}@example.com`,
+      full_name: `User ${i + 1}`,
+      ...overrides,
+    }),
+  );
+}

package/templates/src/mocks/fixtures/users.ts

@@ -0,0 +1,91 @@
+/**
+ * Mock user fixtures for Clerk authentication testing.
+ * Used by clerkMock.tsx to simulate authenticated users.
+ */
+
+import { MOCK_USER } from '../constants';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface MockUser {
+  id: string;
+  firstName: string;
+  lastName: string;
+  fullName?: string;
+  primaryEmailAddress?: { emailAddress: string };
+  imageUrl?: string;
+}
+
+// =============================================================================
+// Default User
+// =============================================================================
+
+/** Default mock user based on MOCK_USER constants */
+export const defaultUser: MockUser = {
+  id: MOCK_USER.id,
+  firstName: MOCK_USER.firstName,
+  lastName: MOCK_USER.lastName,
+  fullName: MOCK_USER.fullName,
+  primaryEmailAddress: { emailAddress: MOCK_USER.email },
+  imageUrl: MOCK_USER.avatarUrl,
+};
+
+// =============================================================================
+// Static Fixtures
+// =============================================================================
+
+/** Sample users for MSW handlers */
+export const mockUsers: MockUser[] = [{ ...defaultUser }];
+
+// =============================================================================
+// Factory Functions
+// =============================================================================
+
+/** Counter for unique ID generation */
+let idCounter = 0;
+
+/**
+ * Create a mock user with optional overrides.
+ *
+ * @example
+ * ```ts
+ * const user = createUser({ firstName: 'Jane' });
+ * ```
+ */
+export function createUser(overrides: Partial<MockUser> = {}): MockUser {
+  const id = overrides.id ?? `user_${Date.now()}_${idCounter++}`;
+  const firstName = overrides.firstName ?? MOCK_USER.firstName;
+  const lastName = overrides.lastName ?? MOCK_USER.lastName;
+
+  return {
+    id,
+    firstName,
+    lastName,
+    fullName: `${firstName} ${lastName}`,
+    primaryEmailAddress: { emailAddress: MOCK_USER.email },
+    imageUrl: MOCK_USER.avatarUrl,
+    ...overrides,
+  };
+}
+
+/**
+ * Create multiple mock users.
+ *
+ * @example
+ * ```ts
+ * const users = createUsers(3);
+ * ```
+ */
+export function createUsers(count: number, overrides: Partial<MockUser> = {}): MockUser[] {
+  return Array.from({ length: count }, (_, i) =>
+    createUser({
+      id: `user_${i + 1}`,
+      firstName: `User${i + 1}`,
+      lastName: 'Test',
+      primaryEmailAddress: { emailAddress: `user${i + 1}@example.com` },
+      ...overrides,
+    }),
+  );
+}