Windsurf AI Native IDE Patterns

// Windsurf Cascade Pattern: Multi-File Refactoring
// 1. Select files in sidebar (Cmd/Ctrl+Click multiple files)
// 2. Open Cascade panel (Cmd/Ctrl+K)
// 3. Describe refactoring intent

// Example Cascade prompt:
// "Refactor user authentication across these files to use better-auth v1.3.9
// instead of NextAuth. Maintain all existing functionality and update types."

// Before: auth.ts (NextAuth)
import NextAuth from 'next-auth';
import { authOptions } from '@/lib/auth/options';

export const { handlers, signIn, signOut, auth } = NextAuth(authOptions);

// After: auth.ts (better-auth) - Cascade generates
import { betterAuth } from 'better-auth';
import { prismaAdapter } from 'better-auth/adapters/prisma';
import { prisma } from '@/lib/db';

export const auth = betterAuth({
  database: prismaAdapter(prisma, {
    provider: 'postgresql',
  }),
  emailAndPassword: {
    enabled: true,
  },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
  },
});

export const { signIn, signOut } = auth;

// Pattern: Cross-File Type Safety
// Windsurf automatically detects type dependencies

// types/user.ts
export interface User {
  id: string;
  email: string;
  profile: UserProfile;
}

export interface UserProfile {
  name: string;
  avatar: string | null;
  bio: string | null;
}

// lib/api/users.ts - Windsurf suggests imports automatically
// Ask Cascade: "Create a user API client with full type safety"
import type { User, UserProfile } from '@/types/user';

class UserAPI {
  async getUser(id: string): Promise<User> {
    const response = await fetch(`/api/users/${id}`);
    return response.json();
  }

  async updateProfile(
    userId: string,
    profile: Partial<UserProfile>
  ): Promise<User> {
    const response = await fetch(`/api/users/${userId}/profile`, {
      method: 'PATCH',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(profile),
    });
    return response.json();
  }
}

export const userAPI = new UserAPI();

// components/user-profile.tsx - Cascade maintains type consistency
// Ask: "Create a user profile component with optimistic updates"
import { useState, useTransition } from 'react';
import { userAPI } from '@/lib/api/users';
import type { User, UserProfile } from '@/types/user';

interface UserProfileEditorProps {
  user: User;
}

export function UserProfileEditor({ user }: UserProfileEditorProps) {
  const [profile, setProfile] = useState<UserProfile>(user.profile);
  const [isPending, startTransition] = useTransition();

  const handleSave = async () => {
    startTransition(async () => {
      await userAPI.updateProfile(user.id, profile);
    });
  };

  return (
    <form onSubmit={(e) => { e.preventDefault(); handleSave(); }}>
      <input
        value={profile.name}
        onChange={(e) => setProfile({ ...profile, name: e.target.value })}
      />
      <button type="submit" disabled={isPending}>
        {isPending ? 'Saving...' : 'Save Profile'}
      </button>
    </form>
  );
}

// Flow Pattern: Feature Development Workflow
// 1. Create Flow session (Cmd/Ctrl+Shift+F)
// 2. Add collaborators or AI assistants
// 3. Define feature scope with Cascade

// Example Flow prompt:
// "Implement a real-time notification system using Supabase Realtime.
// Include: database schema, API routes, React hooks, and UI components.
// Follow our existing patterns in /lib/supabase and /components/ui."

// Cascade generates coordinated changes:

// 1. Database migration
// supabase/migrations/20250116_notifications.sql
CREATE TABLE notifications (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  type TEXT NOT NULL CHECK (type IN ('mention', 'like', 'comment', 'follow')),
  content JSONB NOT NULL,
  read BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_notifications_user_id ON notifications(user_id);
CREATE INDEX idx_notifications_created_at ON notifications(created_at DESC);

ALTER TABLE notifications ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can view own notifications"
  ON notifications FOR SELECT
  USING (auth.uid() = user_id);

// 2. TypeScript types
// types/notification.ts
export type NotificationType = 'mention' | 'like' | 'comment' | 'follow';

export interface Notification {
  id: string;
  user_id: string;
  type: NotificationType;
  content: Record<string, unknown>;
  read: boolean;
  created_at: string;
}

// 3. Realtime hook
// hooks/use-notifications.ts
import { useEffect, useState } from 'react';
import { supabase } from '@/lib/supabase';
import type { Notification } from '@/types/notification';

export function useNotifications(userId: string) {
  const [notifications, setNotifications] = useState<Notification[]>([]);

  useEffect(() => {
    const fetchNotifications = async () => {
      const { data } = await supabase
        .from('notifications')
        .select('*')
        .eq('user_id', userId)
        .order('created_at', { ascending: false })
        .limit(50);

      if (data) setNotifications(data);
    };

    fetchNotifications();

    // Subscribe to realtime changes
    const channel = supabase
      .channel(`notifications:${userId}`)
      .on(
        'postgres_changes',
        {
          event: 'INSERT',
          schema: 'public',
          table: 'notifications',
          filter: `user_id=eq.${userId}`,
        },
        (payload) => {
          setNotifications((prev) => [payload.new as Notification, ...prev]);
        }
      )
      .subscribe();

    return () => {
      supabase.removeChannel(channel);
    };
  }, [userId]);

  return { notifications };
}

// 4. UI Component
// components/notification-bell.tsx
import { Bell } from 'lucide-react';
import { useNotifications } from '@/hooks/use-notifications';
import { Badge } from '@/components/ui/badge';

export function NotificationBell({ userId }: { userId: string }) {
  const { notifications } = useNotifications(userId);
  const unreadCount = notifications.filter((n) => !n.read).length;

  return (
    <button className="relative">
      <Bell className="h-5 w-5" />
      {unreadCount > 0 && (
        <Badge className="absolute -top-1 -right-1">
          {unreadCount}
        </Badge>
      )}
    </button>
  );
}

// ❌ Bad: Vague, single-file focus
// "Add error handling"

// ✅ Good: Specific, context-aware, multi-file
// "Add comprehensive error handling across the authentication flow:
// 1. In lib/auth.ts: Add try/catch with specific error types
// 2. In app/api/auth/[...auth]/route.ts: Return proper HTTP status codes
// 3. In components/login-form.tsx: Display user-friendly error messages
// 4. Follow our error handling patterns in lib/errors.ts"

// Example: Cascade generates coordinated error handling

// lib/errors.ts - Error taxonomy
export class AuthError extends Error {
  constructor(
    message: string,
    public code: AuthErrorCode,
    public statusCode: number = 400
  ) {
    super(message);
    this.name = 'AuthError';
  }
}

export enum AuthErrorCode {
  INVALID_CREDENTIALS = 'INVALID_CREDENTIALS',
  EMAIL_NOT_VERIFIED = 'EMAIL_NOT_VERIFIED',
  ACCOUNT_LOCKED = 'ACCOUNT_LOCKED',
  SESSION_EXPIRED = 'SESSION_EXPIRED',
}

// lib/auth.ts - Service layer errors
import { AuthError, AuthErrorCode } from './errors';

export async function signInWithEmail(email: string, password: string) {
  try {
    const user = await db.user.findUnique({ where: { email } });

    if (!user) {
      throw new AuthError(
        'Invalid email or password',
        AuthErrorCode.INVALID_CREDENTIALS,
        401
      );
    }

    const isValid = await verifyPassword(password, user.passwordHash);

    if (!isValid) {
      throw new AuthError(
        'Invalid email or password',
        AuthErrorCode.INVALID_CREDENTIALS,
        401
      );
    }

    if (!user.emailVerified) {
      throw new AuthError(
        'Please verify your email before signing in',
        AuthErrorCode.EMAIL_NOT_VERIFIED,
        403
      );
    }

    return createSession(user);
  } catch (error) {
    if (error instanceof AuthError) throw error;
    
    // Unexpected errors
    console.error('Signin error:', error);
    throw new AuthError(
      'An unexpected error occurred',
      AuthErrorCode.INVALID_CREDENTIALS,
      500
    );
  }
}

// app/api/auth/signin/route.ts - API layer
import { NextResponse } from 'next/server';
import { signInWithEmail } from '@/lib/auth';
import { AuthError } from '@/lib/errors';

export async function POST(request: Request) {
  try {
    const { email, password } = await request.json();
    const session = await signInWithEmail(email, password);

    return NextResponse.json({ session });
  } catch (error) {
    if (error instanceof AuthError) {
      return NextResponse.json(
        { error: error.message, code: error.code },
        { status: error.statusCode }
      );
    }

    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

// components/login-form.tsx - UI layer
import { useState } from 'react';
import { AuthErrorCode } from '@/lib/errors';

const ERROR_MESSAGES = {
  [AuthErrorCode.INVALID_CREDENTIALS]: 'Invalid email or password. Please try again.',
  [AuthErrorCode.EMAIL_NOT_VERIFIED]: 'Please verify your email before signing in.',
  [AuthErrorCode.ACCOUNT_LOCKED]: 'Your account has been locked. Contact support.',
  [AuthErrorCode.SESSION_EXPIRED]: 'Your session has expired. Please sign in again.',
};

export function LoginForm() {
  const [error, setError] = useState<string | null>(null);

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    setError(null);

    const formData = new FormData(e.currentTarget);
    const email = formData.get('email') as string;
    const password = formData.get('password') as string;

    try {
      const response = await fetch('/api/auth/signin', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, password }),
      });

      const data = await response.json();

      if (!response.ok) {
        const errorMessage = ERROR_MESSAGES[data.code as AuthErrorCode] || data.error;
        setError(errorMessage);
        return;
      }

      // Redirect on success
      window.location.href = '/dashboard';
    } catch (err) {
      setError('Unable to connect. Please check your internet connection.');
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      {error && (
        <div className="bg-red-50 text-red-600 p-3 rounded">
          {error}
        </div>
      )}
      <input name="email" type="email" required />
      <input name="password" type="password" required />
      <button type="submit">Sign In</button>
    </form>
  );
}

// Cascade Command Pattern: "Explain this pattern"
// Select complex code → Right-click → Ask Cascade

// Example: Understanding a custom hook
// Ask Cascade: "Explain how this hook works and show me where it's used"

import { useEffect, useState, useRef } from 'react';

export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value);
  const timerRef = useRef<NodeJS.Timeout>();

  useEffect(() => {
    timerRef.current = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => {
      if (timerRef.current) {
        clearTimeout(timerRef.current);
      }
    };
  }, [value, delay]);

  return debouncedValue;
}

// Cascade Response:
// "This hook debounces a value by delaying state updates.
// Used in 3 locations:
// 1. components/search-bar.tsx (line 12) - search input
// 2. components/filter-panel.tsx (line 28) - filter changes
// 3. hooks/use-search-params.tsx (line 45) - URL param updates"

// Cascade Refactor Pattern: Component Extraction
// Prompt: "Extract the user profile section into a reusable component
// with proper TypeScript types and move to components/user/profile.tsx"

// Before: app/dashboard/page.tsx (monolithic)
export default function DashboardPage() {
  const { user } = useAuth();

  return (
    <div>
      {/* Other dashboard content */}
      
      <div className="user-section">
        <img src={user.avatar} alt={user.name} />
        <h2>{user.name}</h2>
        <p>{user.email}</p>
        <p>{user.bio}</p>
      </div>
    </div>
  );
}

// After: components/user/profile.tsx (extracted)
import type { User } from '@/types/user';

interface UserProfileProps {
  user: User;
  variant?: 'compact' | 'full';
}

export function UserProfile({ user, variant = 'full' }: UserProfileProps) {
  return (
    <div className="user-profile">
      <img src={user.avatar} alt={user.name} />
      <h2>{user.name}</h2>
      {variant === 'full' && (
        <>
          <p>{user.email}</p>
          <p>{user.bio}</p>
        </>
      )}
    </div>
  );
}

// After: app/dashboard/page.tsx (refactored)
import { UserProfile } from '@/components/user/profile';

export default function DashboardPage() {
  const { user } = useAuth();

  return (
    <div>
      {/* Other dashboard content */}
      <UserProfile user={user} />
    </div>
  );
}