@anhth2/spec-driven-dev-plugin 0.5.0

package/modules/java-spring/architecture-snippets/layered-arch.md

@@ -0,0 +1,201 @@
+# Java Spring Boot — Layered Architecture Code Patterns
+
+## Controller Pattern
+
+```java
+@RestController
+@RequestMapping("/v1/orders")
+@RequiredArgsConstructor
+// @trace.implements=ORDER-UC1-SC1
+// @trace.source=specs/bdd/order/ORDER-UC1-create-order.feature
+public class OrderController {
+
+    private final OrderFacade orderFacade;
+
+    @PostMapping
+    public ResponseEntity<ApiResponse<OrderResponse>> createOrder(
+            @Valid @RequestBody CreateOrderRequest request) {
+        OrderResponse result = orderFacade.createOrder(request);
+        return ResponseEntity.status(HttpStatus.CREATED)
+                .body(ApiResponse.success(result));
+    }
+
+    @GetMapping("/{id}")
+    // @trace.implements=ORDER-UC1-SC2
+    public ResponseEntity<ApiResponse<OrderResponse>> getOrder(@PathVariable Long id) {
+        OrderResponse result = orderFacade.getOrder(id);
+        return ResponseEntity.ok(ApiResponse.success(result));
+    }
+}
+```
+
+## Service Interface Pattern
+
+```java
+public interface OrderService {
+    OrderResponse createOrder(CreateOrderRequest request);
+    OrderResponse getOrderById(Long id);
+    void cancelOrder(Long id);
+}
+```
+
+## Service Implementation Pattern
+
+```java
+@Service
+@RequiredArgsConstructor
+@Transactional(readOnly = true)
+public class OrderServiceImpl implements OrderService {
+
+    private final OrderRepository orderRepository;
+    private final OrderMapper orderMapper;
+
+    @Override
+    @Transactional
+    public OrderResponse createOrder(CreateOrderRequest request) {
+        Order order = orderMapper.toEntity(request);
+        order.setStatus(OrderStatus.PENDING);
+        Order saved = orderRepository.save(order);
+        return orderMapper.toResponse(saved);
+    }
+
+    @Override
+    public OrderResponse getOrderById(Long id) {
+        Order order = orderRepository.findById(id)
+                .orElseThrow(() -> new ResourceNotFoundException("Order", id));
+        return orderMapper.toResponse(order);
+    }
+
+    @Override
+    @Transactional
+    public void cancelOrder(Long id) {
+        Order order = orderRepository.findById(id)
+                .orElseThrow(() -> new ResourceNotFoundException("Order", id));
+        order.setStatus(OrderStatus.CANCELLED);
+    }
+}
+```
+
+## Repository Interface Pattern
+
+```java
+@Repository
+public interface OrderRepository extends JpaRepository<Order, Long> {
+
+    List<Order> findByCustomerIdAndStatus(Long customerId, OrderStatus status);
+
+    @Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.id = :id")
+    Optional<Order> findByIdWithItems(@Param("id") Long id);
+
+    Page<Order> findByCreatedAtBetween(
+            LocalDateTime from, LocalDateTime to, Pageable pageable);
+}
+```
+
+## DTO Pattern
+
+```java
+// Request DTO
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class CreateOrderRequest {
+    @NotNull(message = "customerId is required")
+    private Long customerId;
+
+    @NotEmpty(message = "items must not be empty")
+    private List<OrderItemRequest> items;
+
+    @NotBlank(message = "shippingAddress is required")
+    private String shippingAddress;
+}
+
+// Response DTO
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class OrderResponse {
+    private Long id;
+    private Long customerId;
+    private OrderStatus status;
+    private List<OrderItemResponse> items;
+    private BigDecimal totalAmount;
+    private LocalDateTime createdAt;
+}
+```
+
+## MapStruct Mapper Pattern
+
+```java
+@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.ERROR)
+public interface OrderMapper {
+
+    @Mapping(target = "id", ignore = true)
+    @Mapping(target = "status", ignore = true)
+    @Mapping(target = "createdAt", ignore = true)
+    Order toEntity(CreateOrderRequest request);
+
+    OrderResponse toResponse(Order order);
+
+    List<OrderResponse> toResponseList(List<Order> orders);
+}
+```
+
+## ApiResponse Wrapper Pattern
+
+```java
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class ApiResponse<T> {
+    private boolean success;
+    private T data;
+    private String message;
+    private String errorCode;
+    private LocalDateTime timestamp;
+
+    public static <T> ApiResponse<T> success(T data) {
+        return ApiResponse.<T>builder()
+                .success(true)
+                .data(data)
+                .timestamp(LocalDateTime.now())
+                .build();
+    }
+
+    public static <T> ApiResponse<T> error(String errorCode, String message) {
+        return ApiResponse.<T>builder()
+                .success(false)
+                .errorCode(errorCode)
+                .message(message)
+                .timestamp(LocalDateTime.now())
+                .build();
+    }
+}
+```
+
+## Facade Pattern (optional orchestration layer)
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OrderFacade {
+
+    private final OrderService orderService;
+    private final InventoryService inventoryService;
+    private final NotificationService notificationService;
+
+    public OrderResponse createOrder(CreateOrderRequest request) {
+        // 1. Validate inventory
+        inventoryService.validateAvailability(request.getItems());
+        // 2. Create order
+        OrderResponse order = orderService.createOrder(request);
+        // 3. Reserve inventory
+        inventoryService.reserveItems(order.getId(), request.getItems());
+        // 4. Send confirmation
+        notificationService.sendOrderConfirmation(order);
+        return order;
+    }
+}
+```

package/modules/java-spring/module.yaml

@@ -0,0 +1,15 @@
+name: "Java Spring Boot"
+version: "1.0.0"
+description: "Spring Boot 3.x with layered architecture"
+language: "Java"
+framework: "Spring Boot"
+stack_type: "backend"
+default_layer_order:
+  - DTO
+  - Entity/Model
+  - Repository
+  - Service interface
+  - Service impl
+  - Facade (optional)
+  - Controller
+test_framework: "JUnit 5 + Mockito"

package/modules/java-spring/stack-profile.yaml

@@ -0,0 +1,28 @@
+build:
+  compile: "mvn clean install -DskipTests"
+  test: "mvn test"
+  run: "mvn spring-boot:run"
+
+architecture:
+  style: "Layered (Controller → Facade → Service → Repository)"
+  key_rules:
+    - "Controllers must not contain business logic"
+    - "Services own transaction boundaries (@Transactional)"
+    - "Repositories use Spring Data JPA"
+    - "Facades orchestrate multiple services (optional layer)"
+
+coding_standards:
+  naming:
+    classes: "PascalCase"
+    methods: "camelCase"
+    packages: "lowercase.snake_case"
+  patterns:
+    response_wrapper: "ApiResponse<T>"
+    mapping: "MapStruct"
+    exception_base: "ResourceNotFoundException"
+
+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|integration"

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