agentic-team-templates 0.13.2 → 0.15.0

package/templates/java-expert/.cursorrules/spring-boot.md

@@ -0,0 +1,262 @@
+# Spring Boot Patterns
+
+Production-grade Spring Boot development. Convention over configuration, done right.
+
+## Application Structure
+
+```java
+@SpringBootApplication
+public class Application {
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+}
+// That's it. No XML. No component scanning tricks. Just this.
+```
+
+## REST Controllers
+
+```java
+@RestController
+@RequestMapping("/api/v1/orders")
+@RequiredArgsConstructor
+public class OrderController {
+
+    private final OrderService orderService;
+
+    @GetMapping("/{id}")
+    public ResponseEntity<OrderResponse> getById(@PathVariable UUID id) {
+        return orderService.findById(id)
+            .map(ResponseEntity::ok)
+            .orElse(ResponseEntity.notFound().build());
+    }
+
+    @PostMapping
+    public ResponseEntity<OrderResponse> create(
+            @Valid @RequestBody CreateOrderRequest request) {
+        var order = orderService.create(request);
+        var location = URI.create("/api/v1/orders/" + order.id());
+        return ResponseEntity.created(location).body(order);
+    }
+
+    @GetMapping
+    public Page<OrderResponse> list(
+            @RequestParam(defaultValue = "0") int page,
+            @RequestParam(defaultValue = "20") int size) {
+        return orderService.findAll(PageRequest.of(page, size));
+    }
+}
+```
+
+## Service Layer
+
+```java
+@Service
+@RequiredArgsConstructor
+@Transactional(readOnly = true)
+public class OrderService {
+
+    private final OrderRepository orderRepository;
+    private final InventoryClient inventoryClient;
+    private final ApplicationEventPublisher eventPublisher;
+
+    public Optional<OrderResponse> findById(UUID id) {
+        return orderRepository.findById(id)
+            .map(OrderResponse::from);
+    }
+
+    @Transactional
+    public OrderResponse create(CreateOrderRequest request) {
+        // Validate business rules
+        inventoryClient.checkAvailability(request.items())
+            .orElseThrow(() -> new InsufficientInventoryException(request.items()));
+
+        // Create and persist
+        var order = Order.create(request);
+        orderRepository.save(order);
+
+        // Publish domain event
+        eventPublisher.publishEvent(new OrderCreatedEvent(order.getId()));
+
+        return OrderResponse.from(order);
+    }
+}
+```
+
+## Configuration
+
+```java
+// Strongly typed configuration with validation
+@Validated
+@ConfigurationProperties(prefix = "app.orders")
+public record OrderProperties(
+    @NotNull Duration processingTimeout,
+    @Min(1) @Max(1000) int maxItemsPerOrder,
+    @NotBlank String notificationEmail
+) {}
+
+// Enable in Application class or config
+@EnableConfigurationProperties(OrderProperties.class)
+
+// application.yml
+// app:
+//   orders:
+//     processing-timeout: 30s
+//     max-items-per-order: 50
+//     notification-email: orders@example.com
+```
+
+## Exception Handling
+
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(NotFoundException.class)
+    public ProblemDetail handleNotFound(NotFoundException ex) {
+        var problem = ProblemDetail.forStatusAndDetail(
+            HttpStatus.NOT_FOUND, ex.getMessage());
+        problem.setTitle("Resource Not Found");
+        return problem;
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ProblemDetail handleValidation(MethodArgumentNotValidException ex) {
+        var problem = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
+        problem.setTitle("Validation Failed");
+        var errors = ex.getBindingResult().getFieldErrors().stream()
+            .collect(Collectors.toMap(
+                FieldError::getField,
+                f -> Objects.requireNonNullElse(f.getDefaultMessage(), "Invalid")));
+        problem.setProperty("errors", errors);
+        return problem;
+    }
+
+    @ExceptionHandler(Exception.class)
+    public ProblemDetail handleUnexpected(Exception ex) {
+        log.error("Unexpected error", ex);
+        return ProblemDetail.forStatusAndDetail(
+            HttpStatus.INTERNAL_SERVER_ERROR,
+            "An unexpected error occurred");
+        // Never expose stack traces or internal details to clients
+    }
+}
+```
+
+## Security
+
+```java
+@Configuration
+@EnableMethodSecurity
+public class SecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        return http
+            .csrf(csrf -> csrf.csrfTokenRepository(
+                CookieCsrfTokenRepository.withHttpOnlyFalse()))
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/api/public/**").permitAll()
+                .requestMatchers("/actuator/health").permitAll()
+                .requestMatchers("/api/admin/**").hasRole("ADMIN")
+                .anyRequest().authenticated())
+            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
+            .sessionManagement(session ->
+                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .build();
+    }
+}
+```
+
+## Health Checks
+
+```java
+@Component
+public class ExternalServiceHealthIndicator implements HealthIndicator {
+
+    private final ExternalServiceClient client;
+
+    @Override
+    public Health health() {
+        try {
+            client.ping();
+            return Health.up()
+                .withDetail("service", "external-api")
+                .build();
+        } catch (Exception ex) {
+            return Health.down()
+                .withDetail("service", "external-api")
+                .withException(ex)
+                .build();
+        }
+    }
+}
+
+// application.yml
+// management:
+//   endpoints:
+//     web:
+//       exposure:
+//         include: health,info,prometheus
+//   endpoint:
+//     health:
+//       show-details: when-authorized
+```
+
+## Profiles and Environment
+
+```yaml
+# application.yml — shared defaults
+spring:
+  application:
+    name: order-service
+  jpa:
+    open-in-view: false  # Always disable — prevents lazy loading bugs
+
+---
+# application-local.yml
+spring:
+  config:
+    activate:
+      on-profile: local
+  datasource:
+    url: jdbc:postgresql://localhost:5432/orders
+
+---
+# application-prod.yml
+spring:
+  config:
+    activate:
+      on-profile: prod
+  datasource:
+    url: ${DATABASE_URL}  # From environment
+```
+
+## Anti-Patterns
+
+```java
+// Never: field injection
+@Autowired
+private OrderRepository repository; // Untestable, hides dependencies
+// Use constructor injection (Lombok @RequiredArgsConstructor)
+
+// Never: business logic in controllers
+@PostMapping
+public Order create(@RequestBody CreateOrderRequest request) {
+    var order = new Order();
+    order.setStatus("PENDING");
+    order.setItems(request.items()); // Logic belongs in service/domain
+    return orderRepository.save(order);
+}
+
+// Never: open-in-view (lazy loading in controllers)
+spring.jpa.open-in-view=true // N+1 queries, unclear data access patterns
+// Set to false, use eager fetching or DTOs
+
+// Never: catching and ignoring exceptions
+try { externalService.call(); }
+catch (Exception e) { /* ignore */ }
+// Log, wrap, or rethrow — never swallow
+
+// Never: @Transactional on private methods (Spring proxy can't intercept them)
+```

package/templates/java-expert/.cursorrules/testing.md

@@ -0,0 +1,272 @@
+# Java Testing
+
+Test behavior, not implementation. Every test answers: "what does this code do?"
+
+## Framework Stack
+
+| Tool | Purpose |
+|------|---------|
+| JUnit 5 | Test framework |
+| AssertJ | Fluent assertions |
+| Mockito | Mocking (with strict stubs) |
+| Testcontainers | Real databases/services |
+| Spring Boot Test | Integration testing |
+| WireMock | HTTP API mocking |
+| ArchUnit | Architecture tests |
+
+## Unit Test Structure
+
+```java
+class OrderServiceTest {
+
+    private final OrderRepository repository = mock(OrderRepository.class);
+    private final InventoryClient inventory = mock(InventoryClient.class);
+    private final OrderService sut = new OrderService(repository, inventory);
+
+    @Test
+    void create_withValidRequest_savesAndReturnsOrder() {
+        // Arrange
+        var request = new CreateOrderRequest("customer-1", List.of(
+            new OrderItemRequest("SKU-001", 2)));
+        when(inventory.checkAvailability("SKU-001", 2)).thenReturn(true);
+
+        // Act
+        var result = sut.create(request);
+
+        // Assert
+        assertThat(result.customerId()).isEqualTo("customer-1");
+        assertThat(result.status()).isEqualTo(OrderStatus.PENDING);
+        verify(repository).save(any(Order.class));
+    }
+
+    @Test
+    void create_withInsufficientInventory_throwsException() {
+        var request = new CreateOrderRequest("customer-1", List.of(
+            new OrderItemRequest("SKU-001", 100)));
+        when(inventory.checkAvailability("SKU-001", 100)).thenReturn(false);
+
+        assertThatThrownBy(() -> sut.create(request))
+            .isInstanceOf(InsufficientInventoryException.class)
+            .hasMessageContaining("SKU-001");
+
+        verify(repository, never()).save(any());
+    }
+}
+```
+
+## Test Naming
+
+```java
+// Pattern: method_scenario_expectedBehavior
+@Test void findById_whenExists_returnsUser() {}
+@Test void findById_whenNotFound_returnsEmpty() {}
+@Test void create_withDuplicateEmail_throwsConflictException() {}
+
+// Or descriptive sentences
+@Test void newly_created_order_has_pending_status() {}
+@Test void expired_orders_are_automatically_cancelled() {}
+```
+
+## Parameterized Tests
+
+```java
+@ParameterizedTest
+@CsvSource({
+    "'',       false",
+    "ab,       false",
+    "abc,      true",
+    "valid123, true"
+})
+void validatePassword_checksMinLength(String input, boolean expected) {
+    assertThat(PasswordValidator.isValid(input)).isEqualTo(expected);
+}
+
+@ParameterizedTest
+@MethodSource("invalidOrderRequests")
+void create_withInvalidData_throwsValidationException(CreateOrderRequest request) {
+    assertThatThrownBy(() -> sut.create(request))
+        .isInstanceOf(ValidationException.class);
+}
+
+static Stream<Arguments> invalidOrderRequests() {
+    return Stream.of(
+        Arguments.of(new CreateOrderRequest(null, List.of())),
+        Arguments.of(new CreateOrderRequest("", List.of())),
+        Arguments.of(new CreateOrderRequest("c1", List.of()))
+    );
+}
+```
+
+## Spring Boot Integration Tests
+
+```java
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@Testcontainers
+class OrderControllerIntegrationTest {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");
+
+    @DynamicPropertySource
+    static void configureProperties(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", postgres::getJdbcUrl);
+        registry.add("spring.datasource.username", postgres::getUsername);
+        registry.add("spring.datasource.password", postgres::getPassword);
+    }
+
+    @Autowired
+    private TestRestTemplate restTemplate;
+
+    @Autowired
+    private OrderRepository orderRepository;
+
+    @BeforeEach
+    void setUp() {
+        orderRepository.deleteAll();
+    }
+
+    @Test
+    void postOrders_withValidRequest_returnsCreated() {
+        var request = new CreateOrderRequest("customer-1", List.of(
+            new OrderItemRequest("SKU-001", 2)));
+
+        var response = restTemplate.postForEntity("/api/v1/orders", request, OrderResponse.class);
+
+        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
+        assertThat(response.getBody()).isNotNull();
+        assertThat(response.getBody().customerId()).isEqualTo("customer-1");
+        assertThat(response.getHeaders().getLocation()).isNotNull();
+    }
+
+    @Test
+    void getOrders_whenNotFound_returns404() {
+        var response = restTemplate.getForEntity(
+            "/api/v1/orders/" + UUID.randomUUID(), ProblemDetail.class);
+
+        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.NOT_FOUND);
+    }
+}
+```
+
+## WireMock for External APIs
+
+```java
+@SpringBootTest
+@WireMockTest(httpPort = 8089)
+class PaymentServiceTest {
+
+    @Autowired
+    private PaymentService paymentService;
+
+    @Test
+    void charge_whenPaymentSucceeds_returnsTransactionId() {
+        stubFor(post("/payments/charge")
+            .willReturn(okJson("""
+                {"transactionId": "tx-123", "status": "SUCCESS"}
+                """)));
+
+        var result = paymentService.charge(new ChargeRequest("order-1", BigDecimal.TEN));
+
+        assertThat(result.transactionId()).isEqualTo("tx-123");
+        verify(postRequestedFor(urlEqualTo("/payments/charge"))
+            .withRequestBody(matchingJsonPath("$.orderId", equalTo("order-1"))));
+    }
+
+    @Test
+    void charge_whenPaymentServiceDown_throwsException() {
+        stubFor(post("/payments/charge")
+            .willReturn(serverError()));
+
+        assertThatThrownBy(() -> paymentService.charge(
+            new ChargeRequest("order-1", BigDecimal.TEN)))
+            .isInstanceOf(PaymentException.class);
+    }
+}
+```
+
+## Architecture Tests (ArchUnit)
+
+```java
+class ArchitectureTest {
+
+    private final JavaClasses classes = new ClassFileImporter()
+        .importPackages("com.example.myapp");
+
+    @Test
+    void domain_should_not_depend_on_infrastructure() {
+        noClasses()
+            .that().resideInAPackage("..domain..")
+            .should().dependOnClassesThat()
+            .resideInAnyPackage("..infrastructure..", "..api..")
+            .check(classes);
+    }
+
+    @Test
+    void controllers_should_not_access_repositories_directly() {
+        noClasses()
+            .that().resideInAPackage("..api..")
+            .should().dependOnClassesThat()
+            .resideInAPackage("..persistence..")
+            .check(classes);
+    }
+
+    @Test
+    void services_should_be_annotated_with_service() {
+        classes()
+            .that().resideInAPackage("..application..")
+            .and().haveSimpleNameEndingWith("Service")
+            .should().beAnnotatedWith(Service.class)
+            .check(classes);
+    }
+}
+```
+
+## Test Data Builders
+
+```java
+public class TestOrders {
+
+    public static Order.Builder aValidOrder() {
+        return Order.builder()
+            .customerId("customer-1")
+            .status(OrderStatus.PENDING)
+            .items(List.of(anOrderItem().build()));
+    }
+
+    public static OrderItem.Builder anOrderItem() {
+        return OrderItem.builder()
+            .sku("SKU-" + ThreadLocalRandom.current().nextInt(1000))
+            .quantity(1)
+            .price(BigDecimal.valueOf(9.99));
+    }
+}
+
+// Usage in tests
+var order = TestOrders.aValidOrder()
+    .status(OrderStatus.SHIPPED)
+    .build();
+```
+
+## Anti-Patterns
+
+```java
+// Never: testing implementation details
+verify(repository, times(1)).save(any()); // How, not what
+// Test the outcome: verify the order exists, has correct status
+
+// Never: @SpringBootTest for unit tests (slow startup)
+@SpringBootTest // Loads entire context for testing one service
+class OrderServiceTest {} // Use plain JUnit + Mockito instead
+
+// Never: Thread.sleep in tests
+Thread.sleep(5000); // Flaky and slow
+// Use Awaitility: await().atMost(5, SECONDS).until(() -> condition);
+
+// Never: shared mutable state between tests
+static List<Order> testOrders = new ArrayList<>(); // Tests pollute each other
+// Use @BeforeEach to reset state
+
+// Never: ignoring test failures with @Disabled without a reason
+@Disabled // Why? When will it be fixed?
+@Disabled("Flaky due to #1234 — external API timeout. Fix by 2025-02-01")
+```