@edupia-tutor/spec-driven-docs 0.14.0

package/modules/nextjs/architecture-snippets/app-router-patterns.md

@@ -0,0 +1,269 @@
+# Next.js App Router — Server Components, Server Actions & DAL Patterns
+
+## Data Access Layer (server-only)
+
+```typescript
+// lib/dal/orders.dal.ts
+// @trace.source=specs/order/order-management/bdd/ORD-UC1.feature
+import 'server-only'; // prevents accidental import on client
+import { db } from '@/lib/db';
+import type { Order } from '@/types/order';
+
+export async function getOrderById(id: number): Promise<Order | null> {
+  return db.order.findUnique({
+    where: { id },
+    include: { items: { include: { product: true } }, customer: true },
+  });
+}
+
+export async function listOrdersByCustomer(customerId: number): Promise<Order[]> {
+  return db.order.findMany({
+    where: { customerId },
+    include: { items: true },
+    orderBy: { createdAt: 'desc' },
+  });
+}
+```
+
+## Server Component (Data Fetching + Layout)
+
+```tsx
+// app/(dashboard)/orders/page.tsx
+// @trace.implements=ORD-UC1-SC1
+// @trace.source=specs/order/order-management/bdd/ORD-UC1.feature
+import { listOrdersByCustomer } from '@/lib/dal/orders.dal';
+import { getCurrentUser } from '@/lib/auth';
+import { OrderCard } from './_components/OrderCard';
+import { EmptyState } from '@/components/ui/EmptyState';
+
+export default async function OrdersPage() {
+  const user = await getCurrentUser();
+  const orders = await listOrdersByCustomer(user.id);
+
+  return (
+    <section>
+      <h1>My Orders</h1>
+      {orders.length === 0 ? (
+        <EmptyState message="No orders yet." />
+      ) : (
+        <ul>
+          {orders.map(order => (
+            <OrderCard key={order.id} order={order} />
+          ))}
+        </ul>
+      )}
+    </section>
+  );
+}
+```
+
+## Zod Schema (shared server + client)
+
+```typescript
+// lib/validations/order.schema.ts
+import { z } from 'zod';
+
+export const createOrderSchema = z.object({
+  customerId: z.number().positive(),
+  items: z.array(z.object({
+    productId: z.number().positive(),
+    quantity: z.number().int().min(1, 'Quantity must be at least 1'),
+  })).min(1, 'At least one item is required'),
+});
+
+export type CreateOrderInput = z.infer<typeof createOrderSchema>;
+```
+
+## Server Action (Mutation)
+
+```typescript
+// lib/actions/order.actions.ts
+'use server';
+// @trace.implements=ORD-UC2-SC1
+// @trace.source=specs/order/order-management/bdd/ORD-UC2.feature
+
+import { revalidatePath } from 'next/cache';
+import { redirect } from 'next/navigation';
+import { createOrderSchema } from '@/lib/validations/order.schema';
+import { db } from '@/lib/db';
+import { getCurrentUser } from '@/lib/auth';
+
+// Returns { error } on failure, redirects on success
+export async function createOrder(formData: FormData) {
+  const user = await getCurrentUser();
+
+  const parsed = createOrderSchema.safeParse({
+    customerId: user.id,
+    items: JSON.parse(formData.get('items') as string),
+  });
+
+  if (!parsed.success) {
+    return { error: parsed.error.flatten().fieldErrors };
+  }
+
+  try {
+    await db.order.create({
+      data: {
+        customerId: parsed.data.customerId,
+        status: 'pending',
+        items: {
+          create: parsed.data.items.map(item => ({
+            productId: item.productId,
+            quantity: item.quantity,
+          })),
+        },
+      },
+    });
+  } catch {
+    return { error: { _form: ['Failed to create order. Please try again.'] } };
+  }
+
+  revalidatePath('/orders');
+  redirect('/orders');
+}
+
+export async function cancelOrder(orderId: number) {
+  const user = await getCurrentUser();
+
+  const order = await db.order.findFirst({
+    where: { id: orderId, customerId: user.id },
+  });
+
+  if (!order) return { error: 'Order not found.' };
+  if (order.status !== 'pending') return { error: 'Only pending orders can be cancelled.' };
+
+  await db.order.update({ where: { id: orderId }, data: { status: 'cancelled' } });
+
+  revalidatePath('/orders');
+  return { success: true };
+}
+```
+
+## Client Component (Interactive UI)
+
+```tsx
+// app/(dashboard)/orders/_components/CancelOrderButton.tsx
+'use client';
+// @trace.implements=ORD-UC3-SC1
+// @trace.source=specs/order/order-management/bdd/ORD-UC3.feature
+import { useTransition } from 'react';
+import { cancelOrder } from '@/lib/actions/order.actions';
+
+interface Props {
+  orderId: number;
+  disabled?: boolean;
+}
+
+export function CancelOrderButton({ orderId, disabled }: Props) {
+  const [isPending, startTransition] = useTransition();
+
+  const handleCancel = () => {
+    startTransition(async () => {
+      const result = await cancelOrder(orderId);
+      if (result?.error) {
+        alert(result.error); // replace with toast in real app
+      }
+    });
+  };
+
+  return (
+    <button
+      onClick={handleCancel}
+      disabled={disabled || isPending}
+      className="btn-danger"
+    >
+      {isPending ? 'Cancelling...' : 'Cancel Order'}
+    </button>
+  );
+}
+```
+
+## API Route (for webhooks / external consumers)
+
+```typescript
+// app/api/orders/webhook/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { verifyWebhookSignature } from '@/lib/webhook';
+import { db } from '@/lib/db';
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+
+  if (!verifyWebhookSignature(request, body)) {
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
+  }
+
+  if (body.event === 'payment.completed') {
+    await db.order.update({
+      where: { id: body.orderId },
+      data: { status: 'paid', paidAt: new Date() },
+    });
+  }
+
+  return NextResponse.json({ received: true });
+}
+```
+
+## Loading + Error Boundaries
+
+```tsx
+// app/(dashboard)/orders/loading.tsx
+export default function OrdersLoading() {
+  return (
+    <div className="order-skeleton">
+      {Array.from({ length: 3 }).map((_, i) => (
+        <div key={i} className="skeleton-card animate-pulse" />
+      ))}
+    </div>
+  );
+}
+```
+
+```tsx
+// app/(dashboard)/orders/error.tsx
+'use client';
+export default function OrdersError({ error, reset }: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div className="error-state">
+      <p>Failed to load orders: {error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+## Playwright E2E Test
+
+```typescript
+// e2e/orders/create-order.spec.ts
+// @trace.verifies=ORD-UC2
+// @trace.test_type=e2e
+import { test, expect } from '@playwright/test';
+import { loginAs } from '../fixtures/auth';
+
+test.describe('Create Order', () => {
+  test.use({ storageState: 'e2e/.auth/customer.json' }); // reuse auth state
+
+  test('customer creates an order successfully', async ({ page }) => {
+    await page.goto('/orders/new');
+
+    await page.getByLabel('Product').selectOption({ label: 'Wireless Headphones' });
+    await page.getByLabel('Quantity').fill('2');
+    await page.getByRole('button', { name: 'Add to Cart' }).click();
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page).toHaveURL(/\/orders\/\d+/);
+    await expect(page.getByText('Order placed successfully')).toBeVisible();
+  });
+
+  test('shows validation error when cart is empty', async ({ page }) => {
+    await page.goto('/orders/new');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('At least one item is required')).toBeVisible();
+  });
+});
+```

package/modules/nextjs/module.yaml

@@ -0,0 +1,14 @@
+name: "Next.js"
+version: "1.0.0"
+description: "Next.js 14+ App Router with Server Components, Server Actions, and React Query"
+language: "TypeScript"
+framework: "Next.js"
+stack_type: "fullstack"
+default_layer_order:
+  - Types / interfaces
+  - Server Actions (mutations)
+  - Data access layer (DAL) — server-side DB/API calls
+  - Server Components (data fetching + layout)
+  - Client Components (interactive UI)
+  - API Routes (for external consumers / webhooks)
+test_framework: "Vitest + React Testing Library + Playwright (E2E)"

package/modules/nextjs/stack-profile.yaml

@@ -0,0 +1,74 @@
+build:
+  compile: "npm run build"
+  test: "npm test"
+  run: "npm run dev"
+  lint: "npm run lint"
+  e2e: "npx playwright test"
+
+architecture:
+  style: "App Router — Server Components + Server Actions + Client Components"
+  key_rules:
+    - "Default to Server Components — only add 'use client' when interactivity is needed"
+    - "Data fetching happens in Server Components or Server Actions — never in useEffect"
+    - "Server Actions handle all mutations (form submits, data writes)"
+    - "Data Access Layer (DAL) abstracts all DB/external API calls — used only on server"
+    - "Client Components are 'leaf nodes' — keep them small and focused on interactivity"
+    - "API Routes (/api) used only for external consumers or webhooks, not for own UI"
+    - "Use Next.js cache() and unstable_cache for data memoization"
+  folder_structure: |
+    app/
+    ├── (auth)/               ← route group: auth pages
+    ├── (dashboard)/          ← route group: authenticated pages
+    │   └── orders/
+    │       ├── page.tsx      ← Server Component (list page)
+    │       ├── [id]/
+    │       │   └── page.tsx  ← Server Component (detail page)
+    │       └── _components/  ← feature-scoped Client Components
+    ├── api/                  ← API Routes (webhooks, external consumers)
+    └── layout.tsx
+    lib/
+    ├── dal/                  ← Data Access Layer (server-only DB/API calls)
+    │   └── orders.dal.ts
+    ├── actions/              ← Server Actions
+    │   └── order.actions.ts
+    └── validations/          ← Zod schemas (shared server+client)
+        └── order.schema.ts
+    components/
+    └── ui/                   ← shared primitive Client Components
+
+coding_standards:
+  naming:
+    server_components: "PascalCase, no suffix — co-locate in app/ route folder"
+    client_components: "PascalCase + 'use client' at top — in _components/ folders"
+    server_actions: "camelCase verb + noun (e.g., createOrder, cancelOrder) in lib/actions/"
+    dal_functions: "camelCase (e.g., getOrderById, listOrdersByCustomer) in lib/dal/"
+    files:
+      page: "app/{route}/page.tsx"
+      layout: "app/{route}/layout.tsx"
+      server_action: "lib/actions/{domain}.actions.ts"
+      dal: "lib/dal/{domain}.dal.ts"
+      schema: "lib/validations/{domain}.schema.ts"
+  patterns:
+    mutations: "Server Actions with useFormState / useTransition"
+    data_fetching: "Server Component async/await + fetch with revalidate options"
+    client_state: "Zustand or Context API (avoid for server-derived data)"
+    forms: "React Hook Form (client) OR native <form> with Server Actions"
+    error_handling: "error.tsx (route-level) + try/catch in Server Actions returning {error}"
+    loading: "loading.tsx (Suspense boundary) per route segment"
+    auth: "next-auth v5 (Auth.js) or middleware-based session check"
+
+testing:
+  unit: "Vitest + React Testing Library for Client Components"
+  integration: "Vitest + MSW for Server Actions"
+  e2e: "Playwright — full browser tests"
+  patterns:
+    - "Test Server Components by rendering with async render utilities"
+    - "Mock fetch/DB calls for Server Action tests"
+    - "Playwright tests cover full user flows (auth → action → result)"
+    - "Use @playwright/test fixtures for auth state reuse"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  verifies: "// @trace.verifies={UC-ID}"
+  test_type: "// @trace.test_type=unit|e2e"

package/modules/nuxt/module.yaml

@@ -0,0 +1,14 @@
+name: "Nuxt"
+version: "1.0.0"
+description: "Nuxt 3 with SSR/SSG, Composition API, Pinia, and useFetch"
+language: "TypeScript"
+framework: "Nuxt 3"
+stack_type: "frontend"
+default_layer_order:
+  - Types / interfaces
+  - Server API routes (server/api/)
+  - Composables (useFetch / useAsyncData)
+  - State store (Pinia)
+  - UI components (presentational)
+  - Page components (pages/)
+test_framework: "Vitest + Vue Test Utils + @nuxt/test-utils"

package/modules/nuxt/stack-profile.yaml

@@ -0,0 +1,58 @@
+build:
+  compile: "npm run build"
+  test: "npm run test"
+  run: "npm run dev"
+  lint: "npm run lint"
+
+architecture:
+  style: "Pages + Composables + Server routes (SSR/SSG)"
+  key_rules:
+    - "Pages in pages/ are route-level containers — no business logic"
+    - "Business logic in composables/ using useAsyncData or useFetch"
+    - "Server-side logic in server/api/ routes (nitro)"
+    - "Client-only state in Pinia stores; server state via useAsyncData"
+    - "Shared UI primitives in components/ui/, auto-imported by Nuxt"
+    - "Use useRoute/useRouter instead of $route/$router in Composition API"
+    - "'use client' equivalent: wrap client-only code in onMounted or <ClientOnly>"
+  folder_structure: |
+    ├── components/
+    │   └── ui/           ← auto-imported UI primitives (BaseButton, BaseInput...)
+    ├── composables/      ← auto-imported composables (useOrderList...)
+    ├── pages/            ← file-based routing
+    ├── server/
+    │   └── api/          ← nitro server routes (GET /api/orders.ts)
+    ├── stores/           ← Pinia stores (auto-imported)
+    ├── plugins/          ← Nuxt plugins
+    └── utils/            ← auto-imported utilities
+
+coding_standards:
+  naming:
+    components: "PascalCase (auto-imported, e.g., OrderList, BaseButton)"
+    composables: "camelCase with 'use' prefix (auto-imported, e.g., useOrderList)"
+    stores: "camelCase + Store suffix via defineStore()"
+    server_routes: "method.path.ts (e.g., get.orders.ts or [id].get.ts)"
+    files:
+      component: "{Feature}.vue"
+      composable: "use{Feature}.ts"
+      store: "{feature}.store.ts"
+      server_route: "{resource}.get.ts / {resource}.post.ts"
+  patterns:
+    data_fetching: "useAsyncData() for SSR data, useFetch() for client fetches"
+    global_state: "Pinia stores"
+    forms: "VeeValidate + Zod"
+    api_client: "$fetch (ofetch) — built-in to Nuxt, SSR-compatible"
+    ssr_hydration: "useState() for shared SSR/client state to avoid hydration mismatch"
+
+testing:
+  unit: "Vitest + @nuxt/test-utils"
+  e2e: "Playwright via @nuxt/test-utils/e2e"
+  patterns:
+    - "Use mountSuspended() for components that need Nuxt context"
+    - "Use registerEndpoint() to mock server routes in tests"
+    - "Test pages with renderSuspended() from @nuxt/test-utils"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  verifies: "// @trace.verifies={UC-ID}"
+  test_type: "// @trace.test_type=unit|integration"