@anhth2/spec-driven-dev-plugin 0.5.0

package/core/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/bdd/order/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/bdd/order/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/bdd/order/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/bdd/order/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/core/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/core/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/bdd/{domain}/{UC-ID}.feature"
+  verifies: "// @trace.verifies={UC-ID}"
+  test_type: "// @trace.test_type=unit|e2e"

package/core/modules/php-laravel/architecture-snippets/service-repository.md

@@ -0,0 +1,302 @@
+# PHP Laravel — Service-Repository Architecture Patterns
+
+## Form Request (Validation Layer)
+
+```php
+<?php
+// app/Http/Requests/Order/CreateOrderRequest.php
+
+namespace App\Http\Requests\Order;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class CreateOrderRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true; // auth handled by middleware
+    }
+
+    public function rules(): array
+    {
+        return [
+            'customer_id'     => ['required', 'integer', 'exists:customers,id'],
+            'items'           => ['required', 'array', 'min:1'],
+            'items.*.product_id' => ['required', 'integer', 'exists:products,id'],
+            'items.*.quantity'   => ['required', 'integer', 'min:1'],
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'items.required' => 'At least one order item is required.',
+        ];
+    }
+}
+```
+
+## Repository Interface + Eloquent Implementation
+
+```php
+<?php
+// app/Repositories/OrderRepositoryInterface.php
+
+namespace App\Repositories;
+
+use App\Models\Order;
+use Illuminate\Contracts\Pagination\LengthAwarePaginator;
+
+interface OrderRepositoryInterface
+{
+    public function findById(int $id): ?Order;
+    public function findByCustomer(int $customerId, int $perPage = 15): LengthAwarePaginator;
+    public function create(array $data): Order;
+    public function updateStatus(int $id, string $status): bool;
+}
+```
+
+```php
+<?php
+// app/Repositories/Eloquent/OrderRepository.php
+
+namespace App\Repositories\Eloquent;
+
+use App\Models\Order;
+use App\Repositories\OrderRepositoryInterface;
+use Illuminate\Contracts\Pagination\LengthAwarePaginator;
+
+class OrderRepository implements OrderRepositoryInterface
+{
+    public function findById(int $id): ?Order
+    {
+        return Order::with(['items.product', 'customer'])->find($id);
+    }
+
+    public function findByCustomer(int $customerId, int $perPage = 15): LengthAwarePaginator
+    {
+        return Order::where('customer_id', $customerId)
+            ->with('items')
+            ->latest()
+            ->paginate($perPage);
+    }
+
+    public function create(array $data): Order
+    {
+        return Order::create($data);
+    }
+
+    public function updateStatus(int $id, string $status): bool
+    {
+        return Order::where('id', $id)->update(['status' => $status]) > 0;
+    }
+}
+```
+
+## Service Layer
+
+```php
+<?php
+// app/Services/Order/OrderService.php
+
+namespace App\Services\Order;
+
+use App\Exceptions\BusinessException;
+use App\Models\Order;
+use App\Repositories\OrderRepositoryInterface;
+use Illuminate\Support\Facades\DB;
+
+class OrderService
+{
+    // @trace.implements=ORD-UC1-SC1
+    // @trace.source=specs/bdd/order/ORD-UC1.feature
+    public function __construct(
+        private readonly OrderRepositoryInterface $orderRepository
+    ) {}
+
+    public function createOrder(int $customerId, array $items): Order
+    {
+        return DB::transaction(function () use ($customerId, $items) {
+            $order = $this->orderRepository->create([
+                'customer_id' => $customerId,
+                'status'      => 'pending',
+            ]);
+
+            foreach ($items as $item) {
+                $order->items()->create([
+                    'product_id' => $item['product_id'],
+                    'quantity'   => $item['quantity'],
+                ]);
+            }
+
+            return $order->load('items.product');
+        });
+    }
+
+    public function cancelOrder(int $orderId): void
+    {
+        $order = $this->orderRepository->findById($orderId);
+
+        if (!$order) {
+            throw new BusinessException("Order #{$orderId} not found.", 404);
+        }
+
+        if ($order->status !== 'pending') {
+            throw new BusinessException("Only pending orders can be cancelled.", 422);
+        }
+
+        $this->orderRepository->updateStatus($orderId, 'cancelled');
+    }
+}
+```
+
+## Resource Controller
+
+```php
+<?php
+// app/Http/Controllers/Order/OrderController.php
+
+namespace App\Http\Controllers\Order;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Order\CreateOrderRequest;
+use App\Http\Resources\Order\OrderResource;
+use App\Services\Order\OrderService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class OrderController extends Controller
+{
+    public function __construct(
+        private readonly OrderService $orderService
+    ) {}
+
+    // @trace.implements=ORD-UC1-SC1
+    // @trace.source=specs/bdd/order/ORD-UC1.feature
+    public function store(CreateOrderRequest $request): JsonResponse
+    {
+        $order = $this->orderService->createOrder(
+            customerId: $request->validated('customer_id'),
+            items: $request->validated('items')
+        );
+
+        return response()->json([
+            'status'  => 'success',
+            'message' => 'Order created successfully.',
+            'data'    => new OrderResource($order),
+        ], 201);
+    }
+
+    // @trace.implements=ORD-UC2-SC1
+    // @trace.source=specs/bdd/order/ORD-UC2.feature
+    public function destroy(int $id): JsonResponse
+    {
+        $this->orderService->cancelOrder($id);
+
+        return response()->json([
+            'status'  => 'success',
+            'message' => 'Order cancelled.',
+        ]);
+    }
+}
+```
+
+## API Resource (Response Transformer)
+
+```php
+<?php
+// app/Http/Resources/Order/OrderResource.php
+
+namespace App\Http\Resources\Order;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class OrderResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id'          => $this->id,
+            'status'      => $this->status,
+            'customer_id' => $this->customer_id,
+            'items'       => OrderItemResource::collection($this->whenLoaded('items')),
+            'created_at'  => $this->created_at->toISOString(),
+        ];
+    }
+}
+```
+
+## Feature Test (HTTP Layer)
+
+```php
+<?php
+// tests/Feature/Order/CreateOrderTest.php
+
+namespace Tests\Feature\Order;
+
+use App\Models\Customer;
+use App\Models\Product;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+// @trace.verifies=ORD-UC1
+// @trace.test_type=feature
+class CreateOrderTest extends TestCase
+{
+    use RefreshDatabase;
+
+    /** @test */
+    public function it_creates_order_successfully(): void
+    {
+        $customer = Customer::factory()->create();
+        $product  = Product::factory()->create(['stock' => 10]);
+
+        $response = $this->actingAs($customer)
+            ->postJson('/api/v1/orders', [
+                'customer_id' => $customer->id,
+                'items' => [
+                    ['product_id' => $product->id, 'quantity' => 2],
+                ],
+            ]);
+
+        $response->assertStatus(201)
+            ->assertJsonStructure(['status', 'data' => ['id', 'status', 'items']]);
+
+        $this->assertDatabaseHas('orders', ['customer_id' => $customer->id, 'status' => 'pending']);
+    }
+
+    /** @test */
+    public function it_returns_422_when_items_are_empty(): void
+    {
+        $customer = Customer::factory()->create();
+
+        $response = $this->actingAs($customer)
+            ->postJson('/api/v1/orders', ['customer_id' => $customer->id, 'items' => []]);
+
+        $response->assertStatus(422)
+            ->assertJsonValidationErrors(['items']);
+    }
+}
+```
+
+## Service Provider Binding
+
+```php
+<?php
+// app/Providers/RepositoryServiceProvider.php
+
+namespace App\Providers;
+
+use App\Repositories\Eloquent\OrderRepository;
+use App\Repositories\OrderRepositoryInterface;
+use Illuminate\Support\ServiceProvider;
+
+class RepositoryServiceProvider extends ServiceProvider
+{
+    public function register(): void
+    {
+        $this->app->bind(OrderRepositoryInterface::class, OrderRepository::class);
+    }
+}
+```

package/core/modules/php-laravel/module.yaml

@@ -0,0 +1,15 @@
+name: "PHP Laravel"
+version: "1.0.0"
+description: "Laravel 11 backend with service-repository pattern"
+language: "PHP"
+framework: "Laravel"
+stack_type: "backend"
+default_layer_order:
+  - Form Request (validation)
+  - Model / Eloquent
+  - Repository interface
+  - Repository impl
+  - Service
+  - Controller (Resource Controller)
+  - Resource (API response transformer)
+test_framework: "PHPUnit + Pest"