@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/java/spring-boot-architecture/references/auto-configuration.md

@@ -0,0 +1,158 @@
+# Spring Boot Auto-Configuration
+
+## Custom Auto-Configuration
+
+```java
+// 1. Create auto-configuration class
+@AutoConfiguration
+@ConditionalOnClass(MyService.class)
+@EnableConfigurationProperties(MyProperties.class)
+public class MyAutoConfiguration {
+
+    @Bean
+    @ConditionalOnMissingBean
+    public MyService myService(MyProperties properties) {
+        return new MyServiceImpl(properties);
+    }
+
+    @Bean
+    @ConditionalOnProperty(
+        prefix = "my.feature",
+        name = "enabled",
+        havingValue = "true",
+        matchIfMissing = false
+    )
+    public FeatureService featureService() {
+        return new FeatureServiceImpl();
+    }
+}
+
+// 2. Register in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
+// com.example.autoconfigure.MyAutoConfiguration
+```
+
+## Conditional Annotations
+
+```java
+// Property conditions
+@ConditionalOnProperty(name = "feature.enabled", havingValue = "true")
+@ConditionalOnProperty(name = "feature.enabled", matchIfMissing = true)
+
+// Class conditions
+@ConditionalOnClass(DataSource.class)
+@ConditionalOnMissingClass("org.mongodb.Driver")
+
+// Bean conditions
+@ConditionalOnBean(DataSource.class)
+@ConditionalOnMissingBean(MyService.class)
+@ConditionalOnSingleCandidate(DataSource.class)
+
+// Resource conditions
+@ConditionalOnResource(resources = "classpath:schema.sql")
+
+// Web conditions
+@ConditionalOnWebApplication
+@ConditionalOnNotWebApplication
+@ConditionalOnWebApplication(type = Type.SERVLET)
+@ConditionalOnWebApplication(type = Type.REACTIVE)
+
+// Expression conditions
+@ConditionalOnExpression("${feature.a.enabled} and ${feature.b.enabled}")
+
+// Cloud platform
+@ConditionalOnCloudPlatform(CloudPlatform.KUBERNETES)
+```
+
+## Ordering Auto-Configuration
+
+```java
+@AutoConfiguration(
+    after = DataSourceAutoConfiguration.class,
+    before = JpaRepositoriesAutoConfiguration.class
+)
+public class MyAutoConfiguration {
+    // Runs after DataSource, before JPA repositories
+}
+
+// With @AutoConfigureOrder (for non-auto-config)
+@Configuration
+@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)
+public class EarlyConfiguration {}
+```
+
+## Creating Starters
+
+```
+my-spring-boot-starter/
+├── pom.xml
+├── src/main/java/
+│   └── com/example/autoconfigure/
+│       ├── MyAutoConfiguration.java
+│       └── MyProperties.java
+└── src/main/resources/
+    └── META-INF/
+        ├── spring/
+        │   └── org.springframework.boot.autoconfigure.AutoConfiguration.imports
+        └── additional-spring-configuration-metadata.json
+```
+
+**AutoConfiguration.imports:**
+```
+com.example.autoconfigure.MyAutoConfiguration
+```
+
+**Configuration metadata (IDE support):**
+```json
+{
+  "properties": [
+    {
+      "name": "my.service.enabled",
+      "type": "java.lang.Boolean",
+      "description": "Enable MyService auto-configuration.",
+      "defaultValue": true
+    },
+    {
+      "name": "my.service.timeout",
+      "type": "java.time.Duration",
+      "description": "Connection timeout.",
+      "defaultValue": "30s"
+    }
+  ]
+}
+```
+
+## Debugging Auto-Configuration
+
+```yaml
+# Enable debug logging
+debug: true
+
+# Or specific logging
+logging:
+  level:
+    org.springframework.boot.autoconfigure: DEBUG
+```
+
+```bash
+# Actuator endpoint
+GET /actuator/conditions
+
+# Shows:
+# - positiveMatches: Conditions that matched
+# - negativeMatches: Conditions that didn't match
+# - unconditionalClasses: Auto-configs without conditions
+```
+
+## Disabling Auto-Configuration
+
+```java
+@SpringBootApplication(exclude = {
+    DataSourceAutoConfiguration.class,
+    HibernateJpaAutoConfiguration.class
+})
+public class Application {}
+
+// Or via properties
+spring.autoconfigure.exclude=\
+  org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration
+```

package/rules/java/spring-boot-architecture/references/configuration-properties.md

@@ -0,0 +1,202 @@
+# Configuration Properties
+
+## Type-Safe Configuration
+
+```java
+// Using record (immutable, recommended)
+@ConfigurationProperties(prefix = "app")
+@Validated
+public record AppProperties(
+    @NotBlank String name,
+    @NotNull Duration timeout,
+    @Min(1) @Max(100) int maxRetries,
+    @Valid ServerProperties server,
+    Map<String, String> metadata,
+    List<String> allowedOrigins
+) {
+    public record ServerProperties(
+        String host,
+        @Min(1) @Max(65535) int port,
+        boolean ssl
+    ) {}
+}
+
+// Using class (when mutability needed)
+@ConfigurationProperties(prefix = "app")
+@Validated
+public class AppProperties {
+    @NotBlank
+    private String name;
+
+    @DurationUnit(ChronoUnit.SECONDS)
+    private Duration timeout = Duration.ofSeconds(30);
+
+    // getters and setters
+}
+```
+
+## Binding Configuration
+
+```yaml
+# application.yml
+app:
+  name: My Application
+  timeout: 30s           # Duration
+  max-retries: 3         # kebab-case → camelCase
+  server:
+    host: localhost
+    port: 8080
+    ssl: true
+  metadata:
+    version: "1.0"
+    env: production
+  allowed-origins:
+    - http://localhost:3000
+    - https://example.com
+```
+
+## Relaxed Binding
+
+Spring Boot supports multiple formats:
+
+```yaml
+# All equivalent for "firstName" property
+app:
+  firstName: John       # standard camel case
+  first-name: John      # kebab-case (recommended in YAML)
+  first_name: John      # underscore notation
+  FIRST_NAME: John      # uppercase (environment variables)
+```
+
+## Validation
+
+```java
+@ConfigurationProperties(prefix = "app.database")
+@Validated
+public record DatabaseProperties(
+    @NotBlank String url,
+    @NotBlank String username,
+    @NotBlank String password,
+    @Min(1) @Max(100) int poolSize,
+    @DurationMin(seconds = 1) @DurationMax(minutes = 5) Duration connectionTimeout
+) {}
+
+// Custom validation
+public record SecurityProperties(
+    @NotBlank String secretKey
+) {
+    public SecurityProperties {
+        if (secretKey.length() < 32) {
+            throw new IllegalArgumentException("Secret key must be at least 32 characters");
+        }
+    }
+}
+```
+
+## Nested Properties
+
+```java
+@ConfigurationProperties(prefix = "app")
+public record AppProperties(
+    @NestedConfigurationProperty
+    DatabaseProperties database,
+
+    @NestedConfigurationProperty
+    CacheProperties cache,
+
+    Map<String, ServiceProperties> services
+) {
+    public record DatabaseProperties(
+        String url,
+        String username
+    ) {}
+
+    public record CacheProperties(
+        Duration ttl,
+        int maxSize
+    ) {}
+
+    public record ServiceProperties(
+        String url,
+        Duration timeout
+    ) {}
+}
+```
+
+```yaml
+app:
+  database:
+    url: jdbc:postgresql://localhost/db
+    username: admin
+  cache:
+    ttl: 5m
+    max-size: 1000
+  services:
+    user-service:
+      url: http://users:8080
+      timeout: 10s
+    order-service:
+      url: http://orders:8080
+      timeout: 30s
+```
+
+## Constructor Binding
+
+```java
+// Immutable with constructor binding (default for records)
+@ConfigurationProperties(prefix = "app")
+public record AppProperties(
+    String name,
+    Duration timeout,
+    ServerProperties server
+) {
+    // Default values via compact constructor
+    public AppProperties {
+        if (timeout == null) {
+            timeout = Duration.ofSeconds(30);
+        }
+    }
+
+    public record ServerProperties(String host, int port) {
+        public ServerProperties {
+            if (port == 0) {
+                port = 8080;
+            }
+        }
+    }
+}
+```
+
+## Enabling Configuration Properties
+
+```java
+// Option 1: On configuration class
+@Configuration
+@EnableConfigurationProperties(AppProperties.class)
+public class AppConfig {}
+
+// Option 2: Component scan (not recommended)
+@ConfigurationProperties(prefix = "app")
+@Component  // Scanned automatically
+public class AppProperties {}
+
+// Option 3: ConfigurationPropertiesScan
+@SpringBootApplication
+@ConfigurationPropertiesScan("com.example.config")
+public class Application {}
+```
+
+## Environment Variable Override
+
+```bash
+# Override nested properties
+APP_DATABASE_URL=jdbc:postgresql://prod/db
+APP_SERVER_PORT=80
+
+# Override list items
+APP_ALLOWED_ORIGINS_0=http://example.com
+APP_ALLOWED_ORIGINS_1=http://api.example.com
+
+# Override map items
+APP_SERVICES_USERSERVICE_URL=http://users:8080
+```

package/rules/java/spring-boot-web/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: Spring Boot Web
+description: REST controller patterns, request handling, validation, exception handling, and WebFlux.
+metadata:
+  labels: [java, spring-boot, web, rest, api]
+  triggers:
+    files: ['**/*Controller.java', '**/*RestController.java']
+    keywords: [Controller, RestController, RequestMapping, GetMapping, PostMapping, PutMapping, DeleteMapping, ResponseBody, RequestBody, PathVariable, RequestParam]
+---
+
+# Spring Boot Web Standards
+
+## REST Controller
+
+```java
+@RestController
+@RequestMapping("/api/v1/users")
+@RequiredArgsConstructor
+public class UserController {
+
+    private final UserService userService;
+
+    @GetMapping
+    public List<UserResponse> findAll(
+            @RequestParam(defaultValue = "0") int page,
+            @RequestParam(defaultValue = "20") int size) {
+        return userService.findAll(PageRequest.of(page, size))
+            .map(UserResponse::from)
+            .getContent();
+    }
+
+    @GetMapping("/{id}")
+    public UserResponse findById(@PathVariable Long id) {
+        return userService.findById(id)
+            .map(UserResponse::from)
+            .orElseThrow(() -> new ResourceNotFoundException("User", id));
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    public UserResponse create(@Valid @RequestBody CreateUserRequest request) {
+        User user = userService.create(request);
+        return UserResponse.from(user);
+    }
+
+    @PutMapping("/{id}")
+    public UserResponse update(
+            @PathVariable Long id,
+            @Valid @RequestBody UpdateUserRequest request) {
+        User user = userService.update(id, request);
+        return UserResponse.from(user);
+    }
+
+    @DeleteMapping("/{id}")
+    @ResponseStatus(HttpStatus.NO_CONTENT)
+    public void delete(@PathVariable Long id) {
+        userService.delete(id);
+    }
+}
+```
+
+## Request DTOs with Validation
+
+```java
+public record CreateUserRequest(
+    @NotBlank @Size(min = 2, max = 100)
+    String name,
+
+    @NotBlank @Email
+    String email,
+
+    @NotBlank @Size(min = 8)
+    @Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d).*$",
+             message = "must contain letters and numbers")
+    String password
+) {}
+
+public record UpdateUserRequest(
+    @Size(min = 2, max = 100)
+    String name,
+
+    @Email
+    String email
+) {}
+```
+
+## Response DTOs
+
+```java
+public record UserResponse(
+    Long id,
+    String name,
+    String email,
+    LocalDateTime createdAt
+) {
+    public static UserResponse from(User user) {
+        return new UserResponse(
+            user.getId(),
+            user.getName(),
+            user.getEmail(),
+            user.getCreatedAt()
+        );
+    }
+}
+
+// Paginated response
+public record PageResponse<T>(
+    List<T> content,
+    int page,
+    int size,
+    long totalElements,
+    int totalPages,
+    boolean last
+) {
+    public static <T> PageResponse<T> from(Page<T> page) {
+        return new PageResponse<>(
+            page.getContent(),
+            page.getNumber(),
+            page.getSize(),
+            page.getTotalElements(),
+            page.getTotalPages(),
+            page.isLast()
+        );
+    }
+}
+```
+
+## Exception Handling
+
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(ResourceNotFoundException.class)
+    @ResponseStatus(HttpStatus.NOT_FOUND)
+    public ErrorResponse handleNotFound(ResourceNotFoundException ex) {
+        return new ErrorResponse("NOT_FOUND", ex.getMessage());
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    @ResponseStatus(HttpStatus.BAD_REQUEST)
+    public ErrorResponse handleValidation(MethodArgumentNotValidException ex) {
+        Map<String, String> errors = ex.getBindingResult()
+            .getFieldErrors()
+            .stream()
+            .collect(Collectors.toMap(
+                FieldError::getField,
+                FieldError::getDefaultMessage,
+                (a, b) -> a
+            ));
+        return new ErrorResponse("VALIDATION_ERROR", "Validation failed", errors);
+    }
+
+    @ExceptionHandler(Exception.class)
+    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
+    public ErrorResponse handleGeneric(Exception ex) {
+        log.error("Unexpected error", ex);
+        return new ErrorResponse("INTERNAL_ERROR", "An unexpected error occurred");
+    }
+}
+
+public record ErrorResponse(
+    String code,
+    String message,
+    Map<String, String> details
+) {
+    public ErrorResponse(String code, String message) {
+        this(code, message, null);
+    }
+}
+```
+
+## Request Mapping Options
+
+```java
+// Path variables
+@GetMapping("/{userId}/orders/{orderId}")
+public Order getOrder(
+    @PathVariable Long userId,
+    @PathVariable Long orderId) {}
+
+// Query parameters
+@GetMapping("/search")
+public List<User> search(
+    @RequestParam String query,
+    @RequestParam(required = false) String status,
+    @RequestParam(defaultValue = "name") String sortBy) {}
+
+// Headers
+@PostMapping
+public void create(
+    @RequestHeader("X-Request-Id") String requestId,
+    @RequestHeader(value = "X-Tenant-Id", required = false) String tenantId) {}
+
+// Request body
+@PostMapping
+public void create(@RequestBody @Valid CreateRequest request) {}
+
+// Multipart file
+@PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+public void upload(@RequestPart("file") MultipartFile file) {}
+```
+
+## Best Practices
+
+1. **Use records for DTOs** - immutable, concise
+2. **Validate at controller level** with @Valid
+3. **Return appropriate HTTP status codes**
+4. **Use @RestControllerAdvice** for global exception handling
+5. **Never expose entities** - always use DTOs
+6. **Version your API** - /api/v1/resource
+
+## References
+
+- [REST Controller Patterns](references/rest-controller-patterns.md) - Advanced patterns
+- [Validation Patterns](references/validation-patterns.md) - Custom validators, groups
+- [Exception Handling](references/exception-handling.md) - Global handlers, ProblemDetail

package/rules/java/spring-boot-web/references/REFERENCE.md

@@ -0,0 +1,17 @@
+# Spring Boot Web References
+
+## References
+
+- [**REST Controller Patterns**](rest-controller-patterns.md) - HATEOAS, async controllers, streaming
+- [**Validation Patterns**](validation-patterns.md) - Custom validators, validation groups, cross-field
+- [**Exception Handling**](exception-handling.md) - RFC 7807 ProblemDetail, error responses
+
+## Quick Checks
+
+- [ ] Use @RestController for REST APIs
+- [ ] Validate input with @Valid on @RequestBody
+- [ ] Use records for request/response DTOs
+- [ ] Return proper HTTP status codes
+- [ ] Global exception handling with @RestControllerAdvice
+- [ ] Never expose JPA entities in API responses
+- [ ] Version API endpoints (/api/v1/...)

package/rules/java/spring-cloud/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: Spring Cloud
+description: Service discovery, configuration, circuit breakers, load balancing, and API gateway.
+metadata:
+  labels: [java, spring-boot, cloud, microservices]
+  triggers:
+    files: ['bootstrap.yml', 'application.yml', '**/*Discovery*.java', '**/*Client*.java']
+    keywords: [SpringCloud, DiscoveryClient, CircuitBreaker, Resilience4j, FeignClient, Gateway, LoadBalancer]
+---
+
+# Spring Cloud Standards
+
+## Service Discovery (Eureka)
+
+```java
+// Discovery Server
+@SpringBootApplication
+@EnableEurekaServer
+public class DiscoveryServerApplication {}
+
+// Client registration
+@SpringBootApplication
+@EnableDiscoveryClient
+public class UserServiceApplication {}
+```
+
+```yaml
+# Client configuration
+spring:
+  application:
+    name: user-service
+eureka:
+  client:
+    service-url:
+      defaultZone: http://localhost:8761/eureka
+  instance:
+    prefer-ip-address: true
+```
+
+## Feign Client
+
+```java
+@FeignClient(
+    name = "order-service",
+    fallbackFactory = OrderClientFallbackFactory.class
+)
+public interface OrderClient {
+
+    @GetMapping("/api/orders/{userId}")
+    List<Order> getOrdersByUser(@PathVariable Long userId);
+
+    @PostMapping("/api/orders")
+    Order createOrder(@RequestBody CreateOrderRequest request);
+}
+
+@Component
+public class OrderClientFallbackFactory implements FallbackFactory<OrderClient> {
+    @Override
+    public OrderClient create(Throwable cause) {
+        return new OrderClient() {
+            @Override
+            public List<Order> getOrdersByUser(Long userId) {
+                log.warn("Fallback: returning empty orders", cause);
+                return List.of();
+            }
+            // ...
+        };
+    }
+}
+```
+
+## Circuit Breaker (Resilience4j)
+
+```java
+@Service
+public class PaymentService {
+
+    @CircuitBreaker(name = "payment", fallbackMethod = "fallback")
+    @Retry(name = "payment")
+    @TimeLimiter(name = "payment")
+    public CompletableFuture<PaymentResult> process(Payment payment) {
+        return CompletableFuture.supplyAsync(() -> paymentGateway.process(payment));
+    }
+
+    public CompletableFuture<PaymentResult> fallback(Payment payment, Throwable t) {
+        return CompletableFuture.completedFuture(PaymentResult.pending());
+    }
+}
+```
+
+```yaml
+resilience4j:
+  circuitbreaker:
+    instances:
+      payment:
+        sliding-window-size: 10
+        failure-rate-threshold: 50
+        wait-duration-in-open-state: 30s
+  retry:
+    instances:
+      payment:
+        max-attempts: 3
+        wait-duration: 500ms
+```
+
+## References
+
+- [Service Discovery](references/service-discovery.md) - Eureka, Consul patterns
+- [Circuit Breaker](references/circuit-breaker.md) - Resilience4j configuration

package/rules/java/spring-cloud/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Spring Cloud References
+
+## References
+
+- [**Service Discovery**](service-discovery.md) - Eureka, Consul, Kubernetes
+- [**Circuit Breaker**](circuit-breaker.md) - Resilience4j patterns
+
+## Quick Checks
+
+- [ ] Use Resilience4j (not Hystrix - deprecated)
+- [ ] Configure fallbacks for all external calls
+- [ ] Set appropriate circuit breaker thresholds
+- [ ] Use FeignClient for declarative HTTP clients