@react-spa-scaffold/mcp 2.2.0 → 2.4.0

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

@@ -1,18 +1,21 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { api, ApiClientError } from '@/lib/api';
+import {
+  mockFetchError,
+  mockFetchNetworkError,
+  mockFetchNoContent,
+  mockFetchSuccess,
+  mockFetchUnknownError,
+} from '@/test';
 
 describe('api client', () => {
-  const mockFetch = vi.fn();
-  const originalFetch = global.fetch;
-
   beforeEach(() => {
-    global.fetch = mockFetch;
-    vi.clearAllMocks();
+    vi.spyOn(global, 'fetch');
   });
 
   afterEach(() => {
-    global.fetch = originalFetch;
+    vi.restoreAllMocks();
   });
 
   describe('HTTP methods', () => {
@@ -23,15 +26,11 @@ describe('api client', () => {
       { method: 'patch', httpMethod: 'PATCH' },
       { method: 'delete', httpMethod: 'DELETE' },
     ] as const)('$method makes $httpMethod request', async ({ method, httpMethod }) => {
-      mockFetch.mockResolvedValueOnce({
-        ok: true,
-        status: 200,
-        json: () => Promise.resolve({ id: 1 }),
-      });
+      mockFetchSuccess({ id: 1 });
 
       await api[method]('/test');
 
-      expect(mockFetch).toHaveBeenCalledWith(
+      expect(global.fetch).toHaveBeenCalledWith(
         expect.stringContaining('/test'),
         expect.objectContaining({ method: httpMethod }),
       );
@@ -39,30 +38,22 @@ describe('api client', () => {
 
     it('sends request body for POST/PUT/PATCH', async () => {
       const body = { name: 'Test' };
-      mockFetch.mockResolvedValueOnce({
-        ok: true,
-        status: 200,
-        json: () => Promise.resolve({ id: 1 }),
-      });
+      mockFetchSuccess({ id: 1 });
 
       await api.post('/test', body);
 
-      expect(mockFetch).toHaveBeenCalledWith(
+      expect(global.fetch).toHaveBeenCalledWith(
         expect.anything(),
         expect.objectContaining({ body: JSON.stringify(body) }),
       );
     });
 
     it('handles full URL without prepending base URL', async () => {
-      mockFetch.mockResolvedValueOnce({
-        ok: true,
-        status: 200,
-        json: () => Promise.resolve({}),
-      });
+      mockFetchSuccess({});
 
       await api.get('https://external.api/data');
 
-      expect(mockFetch).toHaveBeenCalledWith('https://external.api/data', expect.anything());
+      expect(global.fetch).toHaveBeenCalledWith('https://external.api/data', expect.anything());
     });
   });
 
@@ -71,12 +62,7 @@ describe('api client', () => {
       { status: 404, message: 'Resource not found', hasJson: true },
       { status: 500, message: 'Internal Server Error', hasJson: false },
     ])('handles $status error response', async ({ status, message, hasJson }) => {
-      mockFetch.mockResolvedValueOnce({
-        ok: false,
-        status,
-        statusText: message,
-        json: hasJson ? () => Promise.resolve({ message }) : () => Promise.reject(new Error('No JSON')),
-      });
+      mockFetchError(status, message, hasJson);
 
       const error = (await api.get('/error').catch((e) => e)) as ApiClientError;
 
@@ -87,7 +73,7 @@ describe('api client', () => {
 
     it('handles timeout with TIMEOUT code', async () => {
       vi.useFakeTimers();
-      mockFetch.mockImplementationOnce(
+      vi.mocked(global.fetch).mockImplementationOnce(
         () =>
           new Promise((_, reject) => {
             const error = new Error('Aborted');
@@ -106,20 +92,26 @@ describe('api client', () => {
       vi.useRealTimers();
     });
 
-    it.each([
-      { rejection: new Error('Network failure'), code: 'NETWORK_ERROR' },
-      { rejection: 'string error', code: 'UNKNOWN' },
-    ])('handles $code errors', async ({ rejection, code }) => {
-      mockFetch.mockRejectedValueOnce(rejection);
+    it('handles NETWORK_ERROR', async () => {
+      mockFetchNetworkError();
+
+      const error = (await api.get('/error').catch((e) => e)) as ApiClientError;
+
+      expect(error).toBeInstanceOf(ApiClientError);
+      expect(error.code).toBe('NETWORK_ERROR');
+    });
+
+    it('handles UNKNOWN errors', async () => {
+      mockFetchUnknownError('string error');
 
       const error = (await api.get('/error').catch((e) => e)) as ApiClientError;
 
       expect(error).toBeInstanceOf(ApiClientError);
-      expect(error.code).toBe(code);
+      expect(error.code).toBe('UNKNOWN');
     });
 
     it('returns undefined for 204 No Content', async () => {
-      mockFetch.mockResolvedValueOnce({ ok: true, status: 204 });
+      mockFetchNoContent();
 
       const result = await api.delete('/test/1');
 

package/templates/src/lib/api.ts

@@ -5,13 +5,7 @@
 
 import type { ApiError } from '@/types/api';
 
-/**
- * API configuration.
- */
-export const API_CONFIG = {
-  baseUrl: import.meta.env.VITE_API_URL || 'https://jsonplaceholder.typicode.com',
-  timeout: 30000,
-} as const;
+import { API_CONFIG } from './config';
 
 /**
  * Custom API error class

package/templates/src/lib/config.ts

@@ -1,15 +1,65 @@
 /**
  * Application configuration.
  * Centralized config for feature flags, etc.
+ *
+ * All environment variables flow through the validated `env` object from env.ts.
  */
 
+import { env } from './env';
+
+// =============================================================================
+// App Configuration
+// =============================================================================
+
 export const APP_CONFIG = {
-  name: import.meta.env.VITE_APP_NAME || 'My App',
-  url: import.meta.env.VITE_APP_URL || 'http://localhost:5173',
+  name: env.VITE_APP_NAME,
+  url: env.VITE_APP_URL,
+} as const;
+
+// =============================================================================
+// API Configuration
+// =============================================================================
+
+export const API_CONFIG = {
+  baseUrl: env.VITE_API_URL,
+  timeout: 30000,
 } as const;
 
+// =============================================================================
+// Sentry Configuration
+// =============================================================================
+
 export const SENTRY_CONFIG = {
-  enabled: import.meta.env.VITE_SENTRY_ENABLED !== 'false',
-  dsn: import.meta.env.VITE_SENTRY_DSN,
+  enabled: env.VITE_SENTRY_ENABLED,
+  dsn: env.VITE_SENTRY_DSN,
+  environment: env.MODE,
   tracesSampleRate: 0.1,
 } as const;
+
+// =============================================================================
+// Clerk Configuration
+// =============================================================================
+
+export const CLERK_CONFIG = {
+  publishableKey: env.VITE_CLERK_PUBLISHABLE_KEY,
+} as const;
+
+// =============================================================================
+// Supabase Configuration
+// =============================================================================
+
+export const SUPABASE_CONFIG = {
+  url: env.VITE_SUPABASE_DATABASE_URL,
+  anonKey: env.VITE_SUPABASE_ANON_KEY,
+  /** Whether both URL and anon key are configured */
+  isConfigured: Boolean(env.VITE_SUPABASE_DATABASE_URL && env.VITE_SUPABASE_ANON_KEY),
+} as const;
+
+// =============================================================================
+// Performance Configuration
+// =============================================================================
+
+export const PERFORMANCE_CONFIG = {
+  /** Enable performance tracking in dev or when VITE_PERF_TEST is set */
+  enabled: env.DEV || env.VITE_PERF_TEST,
+} as const;

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,11 +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

@@ -1,29 +1,32 @@
 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 VITE_SENTRY_DSN is configured.
+ * Only runs in production when enabled and VITE_SENTRY_DSN is configured.
  */
-export async function initSentry(): Promise<void> {
-  // Skip in development or if already initialized
-  if (import.meta.env.DEV || sentryInstance) return;
-
-  const dsn = import.meta.env.VITE_SENTRY_DSN;
-  if (!dsn) return;
+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,
-    environment: import.meta.env.MODE,
+    dsn: SENTRY_CONFIG.dsn,
+    environment: SENTRY_CONFIG.environment,
     sendDefaultPii: true,
     integrations: [sentry.browserTracingIntegration()],
-    tracesSampleRate: 0.1,
+    tracesSampleRate: SENTRY_CONFIG.tracesSampleRate,
   });
 
   sentryInstance = sentry;
+  return sentryInstance;
 }
 
 /**

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.ts

@@ -0,0 +1,227 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { app, BrowserWindow, ipcMain, Menu, type MenuItemConstructorOptions } from 'electron';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Track window state
+interface WindowState {
+  alwaysOnTop: boolean;
+  contentProtection: boolean;
+}
+
+let mainWindow: BrowserWindow | null = null;
+const windowState: WindowState = {
+  alwaysOnTop: false,
+  contentProtection: false,
+};
+
+function createMenu(): void {
+  const isMac = process.platform === 'darwin';
+
+  const template: MenuItemConstructorOptions[] = [
+    // App menu (macOS only)
+    ...(isMac
+      ? [
+          {
+            label: app.name,
+            submenu: [
+              { role: 'about' as const },
+              { type: 'separator' as const },
+              { role: 'services' as const },
+              { type: 'separator' as const },
+              { role: 'hide' as const },
+              { role: 'hideOthers' as const },
+              { role: 'unhide' as const },
+              { type: 'separator' as const },
+              { role: 'quit' as const },
+            ],
+          },
+        ]
+      : []),
+    // File menu
+    {
+      label: 'File',
+      submenu: [isMac ? { role: 'close' as const } : { role: 'quit' as const }],
+    },
+    // Edit menu
+    {
+      label: 'Edit',
+      submenu: [
+        { role: 'undo' as const },
+        { role: 'redo' as const },
+        { type: 'separator' as const },
+        { role: 'cut' as const },
+        { role: 'copy' as const },
+        { role: 'paste' as const },
+        ...(isMac
+          ? [{ role: 'pasteAndMatchStyle' as const }, { role: 'delete' as const }, { role: 'selectAll' as const }]
+          : [{ role: 'delete' as const }, { type: 'separator' as const }, { role: 'selectAll' as const }]),
+      ],
+    },
+    // View menu
+    {
+      label: 'View',
+      submenu: [
+        { role: 'reload' as const },
+        { role: 'forceReload' as const },
+        { role: 'toggleDevTools' as const },
+        { type: 'separator' as const },
+        { role: 'resetZoom' as const },
+        { role: 'zoomIn' as const },
+        { role: 'zoomOut' as const },
+        { type: 'separator' as const },
+        { role: 'togglefullscreen' as const },
+        { type: 'separator' as const },
+        {
+          label: 'Always on Top',
+          type: 'checkbox' as const,
+          checked: windowState.alwaysOnTop,
+          click: () => {
+            windowState.alwaysOnTop = !windowState.alwaysOnTop;
+            mainWindow?.setAlwaysOnTop(windowState.alwaysOnTop, 'floating');
+            createMenu(); // Refresh menu to update checkbox state
+          },
+        },
+        {
+          label: 'Hide from Screen Sharing',
+          type: 'checkbox' as const,
+          checked: windowState.contentProtection,
+          click: () => {
+            windowState.contentProtection = !windowState.contentProtection;
+            mainWindow?.setContentProtection(windowState.contentProtection);
+            createMenu(); // Refresh menu to update checkbox state
+          },
+        },
+      ],
+    },
+    // Window menu
+    {
+      label: 'Window',
+      submenu: [
+        { role: 'minimize' as const },
+        { role: 'zoom' as const },
+        ...(isMac
+          ? [
+              { type: 'separator' as const },
+              { role: 'front' as const },
+              { type: 'separator' as const },
+              { role: 'window' as const },
+            ]
+          : [{ role: 'close' as const }]),
+      ],
+    },
+  ];
+
+  const menu = Menu.buildFromTemplate(template);
+  Menu.setApplicationMenu(menu);
+}
+
+function createWindow(): void {
+  // Determine preload path based on environment
+  const preloadPath = path.join(__dirname, 'preload.js');
+
+  mainWindow = new BrowserWindow({
+    width: 1280,
+    height: 800,
+    minWidth: 800,
+    minHeight: 600,
+    webPreferences: {
+      preload: preloadPath,
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true,
+    },
+    // macOS specific styling
+    titleBarStyle: process.platform === 'darwin' ? 'hiddenInset' : 'default',
+    trafficLightPosition: { x: 16, y: 16 },
+  });
+
+  // Load the app with retry logic for dev server
+  // Increased retries and delay to handle Vite restart during dep-scan
+  const loadApp = async (retries = 10, delay = 2000): Promise<void> => {
+    if (!mainWindow) return;
+
+    if (MAIN_WINDOW_VITE_DEV_SERVER_URL) {
+      try {
+        await mainWindow.loadURL(MAIN_WINDOW_VITE_DEV_SERVER_URL);
+      } catch (error) {
+        if (retries > 0) {
+          console.log(`Failed to load dev server, retrying in ${delay}ms... (${retries} retries left)`);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          return loadApp(retries - 1, delay);
+        }
+        console.error('Failed to load dev server after all retries:', error);
+      }
+    } else {
+      mainWindow.loadFile(path.join(__dirname, `../renderer/${MAIN_WINDOW_VITE_NAME}/index.html`));
+    }
+  };
+
+  loadApp();
+
+  // Open DevTools in development
+  if (process.env.NODE_ENV === 'development' || MAIN_WINDOW_VITE_DEV_SERVER_URL) {
+    mainWindow.webContents.openDevTools();
+  }
+
+  mainWindow.on('closed', () => {
+    mainWindow = null;
+  });
+}
+
+// Setup IPC handlers
+function setupIpcHandlers(): void {
+  // Toggle always on top
+  ipcMain.handle('window:setAlwaysOnTop', (_event, enable: boolean) => {
+    if (mainWindow) {
+      windowState.alwaysOnTop = enable;
+      mainWindow.setAlwaysOnTop(enable, 'floating');
+      createMenu(); // Update menu checkbox state
+      return true;
+    }
+    return false;
+  });
+
+  // Toggle content protection (hide from screen sharing)
+  ipcMain.handle('window:setContentProtection', (_event, enable: boolean) => {
+    if (mainWindow) {
+      windowState.contentProtection = enable;
+      mainWindow.setContentProtection(enable);
+      createMenu(); // Update menu checkbox state
+      return true;
+    }
+    return false;
+  });
+
+  // Get current window state
+  ipcMain.handle('window:getState', () => {
+    return { ...windowState };
+  });
+}
+
+// App lifecycle
+app.whenReady().then(() => {
+  setupIpcHandlers();
+  createMenu();
+  createWindow();
+
+  app.on('activate', () => {
+    // On macOS, re-create window when dock icon is clicked
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createWindow();
+    }
+  });
+});
+
+app.on('window-all-closed', () => {
+  // On macOS, keep app running until explicitly quit
+  if (process.platform !== 'darwin') {
+    app.quit();
+  }
+});
+
+// Declare globals injected by Electron Forge Vite plugin
+declare const MAIN_WINDOW_VITE_DEV_SERVER_URL: string | undefined;
+declare const MAIN_WINDOW_VITE_NAME: string;