codecruise 0.1.0

package/config/agents/stack/nextjs/rules/critical.md

@@ -0,0 +1,391 @@
+# Critical Rules - Next.js
+
+Must-follow rules. Violations block PR merge.
+
+---
+
+## Component Model
+
+### NEXT-001: Default to Server Components
+
+```typescript
+// GOOD - Server Component (default)
+async function UserList() {
+  const users = await getUsers(); // Direct server fetch
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+
+// BAD - Unnecessary client component
+'use client';
+import { useEffect, useState } from 'react';
+
+function UserList() {
+  const [users, setUsers] = useState([]);
+  useEffect(() => {
+    fetch('/api/users').then(r => r.json()).then(setUsers);
+  }, []);
+  // ... waterfall, slower
+}
+```
+
+### NEXT-002: Mark client components explicitly
+
+```typescript
+// Required for:
+// - useState, useEffect, useRef
+// - onClick, onChange, onSubmit
+// - Browser APIs (localStorage, window)
+// - Third-party hooks
+
+'use client'; // Must be first line
+
+import { useState } from 'react';
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+### NEXT-003: Minimize client component boundaries
+
+```typescript
+// BAD - Entire page is client
+'use client';
+export default function DashboardPage() {
+  const [filter, setFilter] = useState('all');
+  const users = useUsers(); // All rendering on client
+  return <div>...</div>;
+}
+
+// GOOD - Only interactive parts are client
+export default async function DashboardPage() {
+  const users = await getUsers(); // Server fetch
+
+  return (
+    <div>
+      <FilterBar /> {/* Client component for interactivity */}
+      <UserList users={users} /> {/* Server component with data */}
+    </div>
+  );
+}
+```
+
+---
+
+## Data Fetching
+
+### NEXT-004: Use Server Actions for mutations
+
+```typescript
+// BAD - API route for simple mutation
+// app/api/users/route.ts + client fetch
+
+// GOOD - Server Action
+// app/actions/user.ts
+'use server';
+
+import { revalidatePath } from 'next/cache';
+
+export async function createUser(formData: FormData) {
+  const data = Object.fromEntries(formData);
+  await db.user.create({ data });
+  revalidatePath('/users');
+}
+
+// In component
+<form action={createUser}>...</form>
+```
+
+### NEXT-005: Validate all inputs in Server Actions
+
+```typescript
+'use server';
+
+import { z } from 'zod';
+
+const schema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2),
+});
+
+export async function createUser(formData: FormData) {
+  const raw = Object.fromEntries(formData);
+
+  // Always validate - formData can be spoofed
+  const result = schema.safeParse(raw);
+  if (!result.success) {
+    return { error: 'Invalid input', details: result.error.flatten() };
+  }
+
+  await db.user.create({ data: result.data });
+  return { success: true };
+}
+```
+
+### NEXT-006: Handle loading and error states
+
+```typescript
+// With Suspense
+import { Suspense } from 'react';
+import { ErrorBoundary } from 'react-error-boundary';
+
+export default function Page() {
+  return (
+    <ErrorBoundary fallback={<ErrorState />}>
+      <Suspense fallback={<LoadingState />}>
+        <AsyncComponent />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+
+// With loading.tsx and error.tsx
+// app/dashboard/loading.tsx
+export default function Loading() {
+  return <Skeleton className="h-96" />;
+}
+
+// app/dashboard/error.tsx
+'use client';
+export default function Error({ error, reset }) {
+  return (
+    <div>
+      <p>Something went wrong</p>
+      <Button onClick={reset}>Try again</Button>
+    </div>
+  );
+}
+```
+
+---
+
+## Security
+
+### NEXT-007: Never expose secrets to client
+
+```typescript
+// BAD - Exposed to client bundle
+const API_KEY = process.env.API_KEY;
+
+// GOOD - Server-only
+// In Server Component or Server Action
+const API_KEY = process.env.API_KEY; // Only accessible on server
+
+// Or explicitly mark
+import 'server-only';
+export const secret = process.env.SECRET;
+```
+
+### NEXT-008: Validate auth in Server Actions
+
+```typescript
+'use server';
+
+import { getSession } from '@/lib/auth';
+import { redirect } from 'next/navigation';
+
+export async function deleteUser(userId: string) {
+  const session = await getSession();
+
+  // Always check auth
+  if (!session) {
+    redirect('/login');
+  }
+
+  // Check authorization
+  if (session.user.role !== 'ADMIN') {
+    throw new Error('Unauthorized');
+  }
+
+  await db.user.delete({ where: { id: userId } });
+}
+```
+
+### NEXT-009: Sanitize user-generated content
+
+```typescript
+import DOMPurify from 'isomorphic-dompurify';
+
+// For rendering user HTML
+function UserContent({ html }: { html: string }) {
+  const clean = DOMPurify.sanitize(html, {
+    ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a', 'p'],
+    ALLOWED_ATTR: ['href'],
+  });
+
+  return <div dangerouslySetInnerHTML={{ __html: clean }} />;
+}
+
+// Prefer structured content over raw HTML
+function UserBio({ bio }: { bio: string }) {
+  // Just text, no HTML
+  return <p className="whitespace-pre-wrap">{bio}</p>;
+}
+```
+
+---
+
+## Routing
+
+### NEXT-010: Use proper navigation methods
+
+```typescript
+// For links - use Link component
+import Link from 'next/link';
+<Link href="/dashboard">Dashboard</Link>
+
+// For programmatic navigation in Client Components
+'use client';
+import { useRouter } from 'next/navigation';
+const router = useRouter();
+router.push('/dashboard');
+
+// For Server Actions/Components
+import { redirect } from 'next/navigation';
+redirect('/dashboard'); // Throws, stops execution
+```
+
+### NEXT-011: Protect routes at layout level
+
+```typescript
+// app/dashboard/layout.tsx
+import { getSession } from '@/lib/auth';
+import { redirect } from 'next/navigation';
+
+export default async function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const session = await getSession();
+
+  if (!session) {
+    redirect('/login');
+  }
+
+  return (
+    <div className="flex">
+      <Sidebar user={session.user} />
+      <main className="flex-1">{children}</main>
+    </div>
+  );
+}
+```
+
+---
+
+## Rendering
+
+### NEXT-012: Add proper metadata
+
+```typescript
+// Static metadata
+export const metadata = {
+  title: 'Dashboard',
+  description: 'Your dashboard overview',
+};
+
+// Dynamic metadata
+export async function generateMetadata({ params }) {
+  const user = await getUser(params.id);
+  return {
+    title: user.name,
+    description: `Profile of ${user.name}`,
+  };
+}
+
+// With template
+// app/layout.tsx
+export const metadata = {
+  title: {
+    template: '%s | MyApp',
+    default: 'MyApp',
+  },
+};
+```
+
+### NEXT-013: Use Image component for images
+
+```typescript
+// BAD
+<img src="/hero.jpg" alt="Hero" />
+
+// GOOD
+import Image from 'next/image';
+
+<Image
+  src="/hero.jpg"
+  alt="Hero image"
+  width={1200}
+  height={600}
+  priority // For above-the-fold images
+/>
+
+// For fill mode
+<div className="relative h-64">
+  <Image
+    src={user.avatar}
+    alt={user.name}
+    fill
+    className="object-cover"
+    sizes="(max-width: 768px) 100vw, 50vw"
+  />
+</div>
+```
+
+---
+
+## State Management
+
+### NEXT-014: Avoid unnecessary client state
+
+```typescript
+// BAD - Client state for server data
+'use client';
+const [users, setUsers] = useState([]);
+useEffect(() => {
+  fetchUsers().then(setUsers);
+}, []);
+
+// GOOD - Server fetch, no client state needed
+async function UserList() {
+  const users = await getUsers();
+  return <ul>...</ul>;
+}
+
+// OK - Client state for UI state only
+'use client';
+const [isOpen, setIsOpen] = useState(false);
+const [filter, setFilter] = useState('all');
+```
+
+### NEXT-015: Use URL state for shareable state
+
+```typescript
+'use client';
+
+import { useSearchParams, useRouter, usePathname } from 'next/navigation';
+
+function FilterBar() {
+  const searchParams = useSearchParams();
+  const router = useRouter();
+  const pathname = usePathname();
+
+  function setFilter(value: string) {
+    const params = new URLSearchParams(searchParams);
+    params.set('filter', value);
+    router.push(`${pathname}?${params.toString()}`);
+  }
+
+  return (
+    <select
+      value={searchParams.get('filter') ?? 'all'}
+      onChange={(e) => setFilter(e.target.value)}
+    >
+      <option value="all">All</option>
+      <option value="active">Active</option>
+    </select>
+  );
+}
+```