guardian-framework 0.1.22 → 0.1.24

package/templates/pi/skills/nextjs-enterprise-codegen.md

@@ -0,0 +1,383 @@
+---
+name: nextjs-enterprise-codegen
+description: Full reference for Next.js enterprise code generation with DDD + Clean Architecture. Covers module structure, server/client boundary, data fetching, state management, design system integration, error handling, testing, security, performance, and accessibility. Loaded on-demand via agents/nextjs-codegen.md skill.
+---
+
+# Next.js Enterprise Code Generation — DDD + Clean Architecture
+
+> Canonical skill for generating production-grade Next.js code with DDD patterns.
+> All code MUST follow these patterns. Validators enforce compliance.
+>
+> For design system and styling patterns, see: `.pi/skills/design-system-enterprise-codegen.md`
+
+---
+
+## 1. Project Structure — DDD with Next.js App Router
+
+```
+src/
+  module/                              # One bounded context
+    domain/                            # Pure business logic, zero framework imports
+      entity.ts                        # Domain entities with encapsulated state
+      value.ts                         # Immutable value objects
+      events.ts                        # Domain events
+      errors.ts                        # Typed error classes
+    application/                       # Application logic
+      store.ts                         # Zustand / Jotai state (client-only)
+      actions.ts                       # Server Actions (server-only)
+      queries.ts                       # React Query hooks for data fetching
+      dto.ts                           # Command/Query DTOs
+    infrastructure/                    # External adapters
+      api-client.ts                    # fetch wrapper, error handling, retry
+      auth.ts                          # Auth provider SDK wrapper
+      analytics.ts                     # Analytics SDK wrapper
+    interfaces/                        # UI layer
+      page.tsx                         # App Router page (default: Server Component)
+      component.client.tsx             # Client Component with 'use client'
+      layout.tsx                       # Layout wrapper
+  shared/                              # Cross-module shared code
+    ui/                                # Design system components
+      button/
+      card/
+      modal/
+    lib/                               # Shared utilities
+    hooks/                             # Shared React hooks
+```
+
+### Dependency Rule
+```
+domain → application → infrastructure → interfaces
+                  ↕
+            shared/ (no framework deps)
+```
+
+- **domain/** — zero React/Next.js imports. Pure TypeScript.
+- **application/** — imports from domain. May import from `shared/lib/`.
+- **infrastructure/** — imports from domain + application. Wraps external SDKs.
+- **interfaces/** — imports from application. Contains all React/Next.js code.
+
+---
+
+## 2. Server/Client Boundary
+
+This is the most critical architectural decision in Next.js. Get it wrong and you lose the benefits of both paradigms.
+
+### What goes where
+
+| Layer | Renders on | 'use client'? | Can use |
+|-------|-----------|---------------|---------|
+| `interfaces/page.tsx` | Server | No | `async`, `cookies()`, `headers()`, direct DB |
+| `interfaces/*.client.tsx` | Client | Yes | `useState`, `useEffect`, `onClick`, browser APIs |
+| `application/store.ts` | Client | Depends | Zustand, Jotai |
+| `application/actions.ts` | Server | No | `'use server'`, `revalidatePath()` |
+| `application/queries.ts` | Client | Yes | React Query, SWR |
+| `domain/`, `infrastructure/` | Both | No | Pure TS, fetch |
+
+### Pattern: Island Architecture
+
+```
+┌─────────────────────────────────────────┐
+│ page.tsx (Server Component)             │
+│  <header>Static header</header>         │
+│  <ProductList>                           │
+│    {products.map(p => <ProductCard/>)}  │  ← Server-rendered
+│  </ProductList>                          │
+│  <CheckoutButton.client.tsx>            │  ← Client island
+│    <AddToCartButton/>                   │
+│    <PriceSummary/>                      │
+│  </CheckoutButton.client.tsx>           │
+└─────────────────────────────────────────┘
+```
+
+### Rules
+- ✅ Default to Server Components. Add `'use client'` only when you need interactivity.
+- ✅ Push client state DOWN to the leaf components that need it.
+- ✅ Use Server Actions for mutations, client handlers for optimistic updates.
+- ❌ Never put `'use client'` on a page wrapper — only on interactive islands.
+- ❌ Never import server-only code (actions, DB queries) in client components.
+
+---
+
+## 3. Data Fetching Patterns
+
+### Server Component Fetch (Default)
+
+```typescript
+// interfaces/products/page.tsx — Server Component, async
+import { ProductService } from '../../application/actions';
+
+export default async function ProductsPage() {
+  const products = await ProductService.list();  // Direct call, no API route
+
+  return (
+    <div>
+      {products.map(p => (
+        <ProductCard key={p.id} product={p} />   // Server-rendered
+      ))}
+    </div>
+  );
+}
+```
+
+### Client Data Fetching (React Query)
+
+```typescript
+// application/queries.ts
+import { useQuery } from '@tanstack/react-query';
+import { apiClient } from '../infrastructure/api-client';
+
+export function useProducts() {
+  return useQuery({
+    queryKey: ['products'],
+    queryFn: () => apiClient.get('/api/products'),
+    staleTime: 30_000,           // 30s before refetch
+    gcTime: 5 * 60 * 1000,       // 5min cache
+  });
+}
+
+// interfaces/product-list.client.tsx
+'use client';
+export function ProductList() {
+  const { data, isLoading } = useProducts();
+  if (isLoading) return <Skeleton />;
+  return data.map(p => <ProductCard key={p.id} product={p} />);
+}
+```
+
+### Server Actions (Mutations)
+
+```typescript
+// application/actions.ts
+'use server';
+import { revalidatePath } from 'next/cache';
+import { Cart } from '../domain/entity';
+
+export async function addToCart(productId: string, quantity: number) {
+  const cart = await loadCart();
+  cart.addItem(productId, quantity);
+  await saveCart(cart);
+  revalidatePath('/cart');       // Revalidate without full page reload
+  return { success: true };
+}
+```
+
+### Rules
+- ✅ Server Components for initial data — zero client JS for the first render
+- ✅ React Query for client-side data that needs realtime/stale-while-revalidate
+- ✅ Server Actions for mutations — no API route boilerplate
+- ❌ Never fetch in Server Components for data that needs realtime updates
+- ❌ Never use `useEffect` for data fetching — use React Query or Server Actions
+
+---
+
+## 4. State Management
+
+| State type | Tool | Location |
+|-----------|------|----------|
+| Server state (data) | React Query / SWR | `application/queries.ts` |
+| Client state (UI) | Zustand / Jotai | `application/store.ts` |
+| URL state (filters, page) | `useSearchParams` | `interfaces/*.client.tsx` |
+| Form state | React Hook Form + Zod | `interfaces/*.client.tsx` |
+| Server mutations | Server Actions | `application/actions.ts` |
+
+```typescript
+// application/store.ts — Zustand store
+import { create } from 'zustand';
+import { devtools } from 'zustand/middleware';
+import { Cart } from '../domain/entity';
+
+interface CartState {
+  cart: Cart | null;
+  isOpen: boolean;  // UI state — cart drawer toggle
+  addItem: (productId: string, qty: number) => Promise<void>;
+  toggleCart: () => void;
+}
+
+export const useCartStore = create<CartState>()(
+  devtools(
+    (set) => ({
+      cart: null,
+      isOpen: false,
+      addItem: async (productId, qty) => {
+        // Call Server Action, update local state optimistically
+      },
+      toggleCart: () => set(s => ({ isOpen: !s.isOpen })),
+    }),
+    { name: 'cart-store' },
+  ),
+);
+```
+
+### Rules
+- ✅ Separate server state (React Query) from client state (Zustand)
+- ✅ Keep UI-only state (modals, toggles) local with `useState` when possible
+- ✅ Use Zustand slices for complex domains
+- ❌ Don't put server data in Zustand — that's what React Query is for
+
+---
+
+## 5. Design System & CSS Architecture
+
+### Structure
+
+```
+shared/
+  ui/                                    # Design system components
+    tokens/                              # Design tokens
+      colors.ts
+      typography.ts
+      spacing.ts
+    button/
+      button.tsx                         # Component
+      button.module.css                  # Styles
+      button.test.tsx                    # Tests
+    card/
+    modal/
+    form/
+      input.tsx
+      select.tsx
+```
+
+### Styling Strategy
+
+| Approach | When to use |
+|----------|-------------|
+| CSS Modules (`*.module.css`) | Component-scoped styles in design system |
+| Tailwind utility classes | Layout, spacing, one-off adjustments |
+| CSS Variables (`var(--color-primary)`) | Design tokens, theming |
+| `clsx` / `tailwind-merge` | Conditional class composition |
+
+```typescript
+// shared/ui/button/button.tsx
+import { type VariantProps, cva } from 'class-variance-authority';
+import { cn } from '../../lib/utils';
+
+const buttonVariants = cva(
+  'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors',
+  {
+    variants: {
+      variant: {
+        primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+      },
+      size: {
+        sm: 'h-9 px-3',
+        md: 'h-10 px-4 py-2',
+        lg: 'h-11 px-8',
+      },
+    },
+    defaultVariants: { variant: 'primary', size: 'md' },
+  },
+);
+
+interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+export function Button({ className, variant, size, ...props }: ButtonProps) {
+  return <button className={cn(buttonVariants({ variant, size }), className)} {...props} />;
+}
+```
+
+### Design System Rules
+- ✅ Design tokens in `shared/ui/tokens/` — single source of truth for colors, spacing, typography
+- ✅ Components use `cva` (class-variance-authority) for variant props
+- ✅ CSS Modules for component styles, Tailwind for layout
+- ✅ Dark mode via `class` strategy on `<html>` element
+- ❌ No inline styles (`style={{}}`) except for dynamic values (animations, transforms)
+- ❌ No CSS-in-JS libraries (styled-components, emotion) — they break Server Components
+
+---
+
+## 6. Error Handling
+
+```typescript
+// domain/errors.ts — Typed domain errors
+export class DomainError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly status: number = 400,
+  ) {
+    super(message);
+    this.name = 'DomainError';
+  }
+
+  static notFound(id: string) {
+    return new DomainError('NOT_FOUND', `Resource ${id} not found`, 404);
+  }
+}
+
+// interfaces/error.tsx — Next.js error boundary
+'use client';
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+  return (
+    <div role="alert">
+      <h2>Something went wrong</h2>
+      <button onClick={() => reset()}>Try again</button>
+    </div>
+  );
+}
+
+// interfaces/not-found.tsx — Next.js 404 boundary
+export default function NotFound() {
+  return <div>Page not found</div>;
+}
+```
+
+---
+
+## 7. Testing Patterns
+
+| Test type | Tool | What to test |
+|-----------|------|-------------|
+| Unit | Vitest | `domain/` entities, value objects |
+| Component | Vitest + Testing Library | `interfaces/` components |
+| Integration | Vitest + MSW | API client with mocked server |
+| E2E | Playwright | Full user flows |
+
+```typescript
+// domain/entity.test.ts — Pure unit test, no React
+import { Cart } from './entity';
+
+describe('Cart', () => {
+  it('adds item', () => {
+    const cart = new Cart();
+    cart.addItem({ id: '1', name: 'Test', price: 100 }, 2);
+    expect(cart.total).toBe(200);
+  });
+});
+```
+
+---
+
+## 8. Anti-Patterns — NEVER DO
+
+```typescript
+// ❌ Business logic in components
+export default function Page() {
+  const [cart, setCart] = useState([]);  // BAD — belongs in domain/
+}
+
+// ❌ Data fetching in client components without React Query
+useEffect(() => { fetch('/api/data').then(setData); }, []);  // BAD
+
+// ❌ 'use client' on the entire page
+'use client';  // BAD — only add to interactive islands
+
+// ❌ Inline styles
+<div style={{ marginLeft: '16px' }}>  // BAD — use Tailwind or CSS Modules
+
+// ❌ Mixing server/client concerns
+import { cookies } from 'next/headers';  // BAD in client component
+
+// ❌ Global CSS for component styles
+h1 { color: blue; }  // BAD — use CSS Modules or Tailwind
+```
+
+---
+
+*Version: 1.1.0*
+*Last updated: 2026-07-03*