@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/nextjs/.claude/rules/authentication.md

@@ -0,0 +1,355 @@
+---
+paths:
+  - "**/auth/**"
+  - "**/login/**"
+  - "**/api/auth/**"
+  - "middleware.ts"
+---
+
+# Next.js Authentication
+
+## NextAuth.js v5 Setup
+
+### Configuration
+
+```typescript
+// auth.ts
+import NextAuth from 'next-auth';
+import Credentials from 'next-auth/providers/credentials';
+import Google from 'next-auth/providers/google';
+import { authConfig } from './auth.config';
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  ...authConfig,
+  providers: [
+    Google({
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    }),
+    Credentials({
+      async authorize(credentials) {
+        const { email, password } = credentials;
+        const user = await verifyCredentials(email, password);
+        if (!user) return null;
+        return user;
+      },
+    }),
+  ],
+});
+```
+
+### Auth Config (for Edge)
+
+```typescript
+// auth.config.ts
+import type { NextAuthConfig } from 'next-auth';
+
+export const authConfig = {
+  pages: {
+    signIn: '/login',
+    error: '/auth/error',
+  },
+  callbacks: {
+    authorized({ auth, request: { nextUrl } }) {
+      const isLoggedIn = !!auth?.user;
+      const isProtected = nextUrl.pathname.startsWith('/dashboard');
+
+      if (isProtected && !isLoggedIn) {
+        return Response.redirect(new URL('/login', nextUrl));
+      }
+      return true;
+    },
+    jwt({ token, user }) {
+      if (user) {
+        token.id = user.id;
+        token.role = user.role;
+      }
+      return token;
+    },
+    session({ session, token }) {
+      session.user.id = token.id as string;
+      session.user.role = token.role as string;
+      return session;
+    },
+  },
+  providers: [], // Configured in auth.ts
+} satisfies NextAuthConfig;
+```
+
+### Route Handlers
+
+```typescript
+// app/api/auth/[...nextauth]/route.ts
+import { handlers } from '@/auth';
+export const { GET, POST } = handlers;
+```
+
+## Middleware Protection
+
+```typescript
+// middleware.ts
+import { auth } from './auth';
+
+export default auth((req) => {
+  const { nextUrl } = req;
+  const isLoggedIn = !!req.auth;
+
+  const publicPaths = ['/login', '/register', '/'];
+  const isPublic = publicPaths.includes(nextUrl.pathname);
+
+  if (!isLoggedIn && !isPublic) {
+    return Response.redirect(new URL('/login', nextUrl));
+  }
+
+  // Role-based protection
+  if (nextUrl.pathname.startsWith('/admin')) {
+    if (req.auth?.user?.role !== 'admin') {
+      return Response.redirect(new URL('/forbidden', nextUrl));
+    }
+  }
+});
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+## Server Components
+
+### Get Session
+
+```typescript
+// app/dashboard/page.tsx
+import { auth } from '@/auth';
+import { redirect } from 'next/navigation';
+
+export default async function DashboardPage() {
+  const session = await auth();
+
+  if (!session) {
+    redirect('/login');
+  }
+
+  return (
+    <div>
+      <h1>Welcome, {session.user.name}</h1>
+    </div>
+  );
+}
+```
+
+### Protected Layout
+
+```typescript
+// app/(protected)/layout.tsx
+import { auth } from '@/auth';
+import { redirect } from 'next/navigation';
+
+export default async function ProtectedLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const session = await auth();
+
+  if (!session) {
+    redirect('/login');
+  }
+
+  return <>{children}</>;
+}
+```
+
+## Client Components
+
+### Sign In/Out
+
+```typescript
+'use client';
+
+import { signIn, signOut } from 'next-auth/react';
+
+export function LoginButton() {
+  return (
+    <button onClick={() => signIn('google', { callbackUrl: '/dashboard' })}>
+      Sign in with Google
+    </button>
+  );
+}
+
+export function LogoutButton() {
+  return (
+    <button onClick={() => signOut({ callbackUrl: '/' })}>
+      Sign out
+    </button>
+  );
+}
+```
+
+### Use Session Hook
+
+```typescript
+'use client';
+
+import { useSession } from 'next-auth/react';
+
+export function UserProfile() {
+  const { data: session, status } = useSession();
+
+  if (status === 'loading') {
+    return <Skeleton />;
+  }
+
+  if (!session) {
+    return <LoginButton />;
+  }
+
+  return (
+    <div>
+      <img src={session.user.image} alt={session.user.name} />
+      <span>{session.user.name}</span>
+    </div>
+  );
+}
+```
+
+## Server Actions
+
+### Login Action
+
+```typescript
+// app/login/actions.ts
+'use server';
+
+import { signIn } from '@/auth';
+import { AuthError } from 'next-auth';
+
+export async function loginAction(
+  prevState: { error?: string } | undefined,
+  formData: FormData
+) {
+  try {
+    await signIn('credentials', {
+      email: formData.get('email'),
+      password: formData.get('password'),
+      redirectTo: '/dashboard',
+    });
+  } catch (error) {
+    if (error instanceof AuthError) {
+      switch (error.type) {
+        case 'CredentialsSignin':
+          return { error: 'Invalid credentials' };
+        default:
+          return { error: 'Something went wrong' };
+      }
+    }
+    throw error;
+  }
+}
+```
+
+### Login Form
+
+```typescript
+'use client';
+
+import { useActionState } from 'react';
+import { loginAction } from './actions';
+
+export function LoginForm() {
+  const [state, action, isPending] = useActionState(loginAction, undefined);
+
+  return (
+    <form action={action}>
+      <input name="email" type="email" required />
+      <input name="password" type="password" required />
+
+      {state?.error && <p className="error">{state.error}</p>}
+
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Signing in...' : 'Sign in'}
+      </button>
+    </form>
+  );
+}
+```
+
+## Type Extensions
+
+```typescript
+// types/next-auth.d.ts
+import 'next-auth';
+
+declare module 'next-auth' {
+  interface User {
+    role: string;
+  }
+
+  interface Session {
+    user: User & {
+      id: string;
+      role: string;
+    };
+  }
+}
+
+declare module 'next-auth/jwt' {
+  interface JWT {
+    id: string;
+    role: string;
+  }
+}
+```
+
+## Session Provider
+
+```typescript
+// app/providers.tsx
+'use client';
+
+import { SessionProvider } from 'next-auth/react';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <SessionProvider>{children}</SessionProvider>;
+}
+
+// app/layout.tsx
+import { Providers } from './providers';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+## Anti-patterns
+
+```typescript
+// BAD: Checking auth in client component for protection
+'use client';
+export function ProtectedPage() {
+  const { data: session } = useSession();
+  if (!session) return <Redirect />;  // Too late, page already loaded
+}
+
+// GOOD: Check in middleware or server component
+export default async function ProtectedPage() {
+  const session = await auth();
+  if (!session) redirect('/login');
+}
+
+// BAD: Exposing secrets
+const user = await db.user.findUnique({ where: { id } });
+return { ...user, password: user.password }; // Leaking password!
+
+// GOOD: Select only needed fields
+const user = await db.user.findUnique({
+  where: { id },
+  select: { id: true, name: true, email: true },
+});
+```

package/configs/nextjs/.claude/rules/components.md

@@ -209,3 +209,55 @@ export default function Page() {}
 - Inline styles (use CSS modules or Tailwind)
 - Anonymous components
 - Props spreading without type safety
+
+## Error and Loading UI
+
+### Error Boundary (error.tsx)
+
+```tsx
+'use client';
+
+interface ErrorProps {
+  error: Error & { digest?: string };
+  reset: () => void;
+}
+
+export default function Error({ error, reset }: ErrorProps) {
+  return (
+    <div className="error-container">
+      <h2>Something went wrong!</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+### Loading State (loading.tsx)
+
+```tsx
+export default function Loading() {
+  return (
+    <div className="loading-container">
+      <Spinner />
+      <p>Loading...</p>
+    </div>
+  );
+}
+```
+
+### Not Found (not-found.tsx)
+
+```tsx
+import Link from 'next/link';
+
+export default function NotFound() {
+  return (
+    <div>
+      <h2>Not Found</h2>
+      <p>Could not find the requested resource.</p>
+      <Link href="/">Return Home</Link>
+    </div>
+  );
+}
+```

package/configs/nextjs/.claude/rules/data-fetching.md

@@ -0,0 +1,249 @@
+---
+paths:
+  - "app/**/*.tsx"
+  - "app/**/*.ts"
+  - "**/actions.ts"
+  - "**/actions/*.ts"
+---
+
+# Data Fetching & Server Actions
+
+## Server Components - Data Fetching
+
+```tsx
+// app/users/page.tsx
+async function getUsers(): Promise<User[]> {
+  const response = await fetch('https://api.example.com/users', {
+    cache: 'no-store',           // Dynamic - always fresh
+    // cache: 'force-cache',     // Static (default)
+    // next: { revalidate: 60 }, // ISR - revalidate every 60s
+  });
+
+  if (!response.ok) {
+    throw new Error('Failed to fetch users');
+  }
+
+  return response.json();
+}
+
+export default async function UsersPage() {
+  const users = await getUsers();
+
+  return (
+    <ul>
+      {users.map((user) => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Cache Options
+
+| Option | Behavior |
+|--------|----------|
+| `cache: 'force-cache'` | Static, cached indefinitely (default) |
+| `cache: 'no-store'` | Dynamic, never cached |
+| `next: { revalidate: N }` | ISR, revalidate every N seconds |
+| `next: { tags: ['users'] }` | Tagged for on-demand revalidation |
+
+## Server Actions
+
+```tsx
+// app/users/actions.ts
+'use server';
+
+import { revalidatePath, revalidateTag } from 'next/cache';
+import { redirect } from 'next/navigation';
+import { z } from 'zod';
+
+const CreateUserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+});
+
+export async function createUser(formData: FormData) {
+  // Validate
+  const parsed = CreateUserSchema.safeParse({
+    name: formData.get('name'),
+    email: formData.get('email'),
+  });
+
+  if (!parsed.success) {
+    return { error: 'Invalid data' };
+  }
+
+  // Create
+  await db.user.create({ data: parsed.data });
+
+  // Revalidate and redirect
+  revalidatePath('/users');
+  redirect('/users');
+}
+```
+
+## Form with Server Action
+
+```tsx
+// app/users/_components/user-form.tsx
+'use client';
+
+import { useActionState } from 'react';
+import { createUser } from '../actions';
+
+const initialState = { error: null };
+
+export function UserForm() {
+  const [state, formAction, isPending] = useActionState(
+    createUser,
+    initialState
+  );
+
+  return (
+    <form action={formAction}>
+      <input name="name" required disabled={isPending} />
+      <input name="email" type="email" required disabled={isPending} />
+
+      {state.error && <p className="error">{state.error}</p>}
+
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create User'}
+      </button>
+    </form>
+  );
+}
+```
+
+## Optimistic Updates
+
+```tsx
+'use client';
+
+import { useOptimistic } from 'react';
+import { addItem } from './actions';
+
+export function ItemList({ items }: { items: Item[] }) {
+  const [optimisticItems, addOptimisticItem] = useOptimistic(
+    items,
+    (state, newItem: Item) => [...state, newItem]
+  );
+
+  async function handleAdd(formData: FormData) {
+    const newItem = {
+      id: crypto.randomUUID(),
+      name: formData.get('name') as string,
+      pending: true,
+    };
+
+    addOptimisticItem(newItem);
+    await addItem(formData);
+  }
+
+  return (
+    <>
+      <form action={handleAdd}>
+        <input name="name" />
+        <button type="submit">Add</button>
+      </form>
+
+      <ul>
+        {optimisticItems.map((item) => (
+          <li key={item.id} style={{ opacity: item.pending ? 0.5 : 1 }}>
+            {item.name}
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+}
+```
+
+## Parallel Data Fetching
+
+```tsx
+// Parallel - faster
+export default async function Page() {
+  const [users, products] = await Promise.all([
+    getUsers(),
+    getProducts(),
+  ]);
+
+  return (/* ... */);
+}
+
+// Sequential - slower, avoid
+export default async function Page() {
+  const users = await getUsers();
+  const products = await getProducts(); // Waits for users
+  return (/* ... */);
+}
+```
+
+## Data Fetching with Suspense
+
+```tsx
+import { Suspense } from 'react';
+
+export default function Page() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+
+      <Suspense fallback={<UsersSkeleton />}>
+        <UsersSection />
+      </Suspense>
+
+      <Suspense fallback={<ProductsSkeleton />}>
+        <ProductsSection />
+      </Suspense>
+    </div>
+  );
+}
+
+async function UsersSection() {
+  const users = await getUsers();
+  return <UserList users={users} />;
+}
+```
+
+## Revalidation Patterns
+
+```tsx
+'use server';
+
+// Path-based
+revalidatePath('/users');           // Revalidate specific path
+revalidatePath('/users', 'layout'); // Revalidate layout and children
+
+// Tag-based
+revalidateTag('users');             // Revalidate all with this tag
+
+// Usage with tags
+await fetch('/api/users', {
+  next: { tags: ['users'] }
+});
+```
+
+## Error Handling in Server Actions
+
+```tsx
+'use server';
+
+export async function createUser(formData: FormData) {
+  try {
+    const user = await db.user.create({
+      data: { name: formData.get('name') as string }
+    });
+
+    revalidatePath('/users');
+    return { success: true, user };
+  } catch (error) {
+    // Log for debugging
+    console.error('Failed to create user:', error);
+
+    // Return user-friendly error
+    return { success: false, error: 'Failed to create user' };
+  }
+}
+```