@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

package/.agent/rules/java/patterns.md

@@ -1,146 +1,146 @@
----
-paths:
-  - "**/*.java"
----
-# Java Patterns
-
-> This file extends [common/patterns.md](../common/patterns.md) with Java-specific content.
-
-## Repository Pattern
-
-Encapsulate data access behind an interface:
-
-```java
-public interface OrderRepository {
-    Optional<Order> findById(Long id);
-    List<Order> findAll();
-    Order save(Order order);
-    void deleteById(Long id);
-}
-```
-
-Concrete implementations handle storage details (JPA, JDBC, in-memory for tests).
-
-## Service Layer
-
-Business logic in service classes; keep controllers and repositories thin:
-
-```java
-public class OrderService {
-    private final OrderRepository orderRepository;
-    private final PaymentGateway paymentGateway;
-
-    public OrderService(OrderRepository orderRepository, PaymentGateway paymentGateway) {
-        this.orderRepository = orderRepository;
-        this.paymentGateway = paymentGateway;
-    }
-
-    public OrderSummary placeOrder(CreateOrderRequest request) {
-        var order = Order.from(request);
-        paymentGateway.charge(order.total());
-        var saved = orderRepository.save(order);
-        return OrderSummary.from(saved);
-    }
-}
-```
-
-## Constructor Injection
-
-Always use constructor injection — never field injection:
-
-```java
-// GOOD — constructor injection (testable, immutable)
-public class NotificationService {
-    private final EmailSender emailSender;
-
-    public NotificationService(EmailSender emailSender) {
-        this.emailSender = emailSender;
-    }
-}
-
-// BAD — field injection (untestable without reflection, requires framework magic)
-public class NotificationService {
-    @Inject // or @Autowired
-    private EmailSender emailSender;
-}
-```
-
-## DTO Mapping
-
-Use records for DTOs. Map at service/controller boundaries:
-
-```java
-public record OrderResponse(Long id, String customer, BigDecimal total) {
-    public static OrderResponse from(Order order) {
-        return new OrderResponse(order.getId(), order.getCustomerName(), order.getTotal());
-    }
-}
-```
-
-## Builder Pattern
-
-Use for objects with many optional parameters:
-
-```java
-public class SearchCriteria {
-    private final String query;
-    private final int page;
-    private final int size;
-    private final String sortBy;
-
-    private SearchCriteria(Builder builder) {
-        this.query = builder.query;
-        this.page = builder.page;
-        this.size = builder.size;
-        this.sortBy = builder.sortBy;
-    }
-
-    public static class Builder {
-        private String query = "";
-        private int page = 0;
-        private int size = 20;
-        private String sortBy = "id";
-
-        public Builder query(String query) { this.query = query; return this; }
-        public Builder page(int page) { this.page = page; return this; }
-        public Builder size(int size) { this.size = size; return this; }
-        public Builder sortBy(String sortBy) { this.sortBy = sortBy; return this; }
-        public SearchCriteria build() { return new SearchCriteria(this); }
-    }
-}
-```
-
-## Sealed Types for Domain Models
-
-```java
-public sealed interface PaymentResult permits PaymentSuccess, PaymentFailure {
-    record PaymentSuccess(String transactionId, BigDecimal amount) implements PaymentResult {}
-    record PaymentFailure(String errorCode, String message) implements PaymentResult {}
-}
-
-// Exhaustive handling (Java 21+)
-String message = switch (result) {
-    case PaymentSuccess s -> "Paid: " + s.transactionId();
-    case PaymentFailure f -> "Failed: " + f.errorCode();
-};
-```
-
-## API Response Envelope
-
-Consistent API responses:
-
-```java
-public record ApiResponse<T>(boolean success, T data, String error) {
-    public static <T> ApiResponse<T> ok(T data) {
-        return new ApiResponse<>(true, data, null);
-    }
-    public static <T> ApiResponse<T> error(String message) {
-        return new ApiResponse<>(false, null, message);
-    }
-}
-```
-
-## References
-
-See skill: `springboot-patterns` for Spring Boot architecture patterns.
-See skill: `jpa-patterns` for entity design and query optimization.
+---
+paths:
+  - "**/*.java"
+---
+# Java Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Java-specific content.
+
+## Repository Pattern
+
+Encapsulate data access behind an interface:
+
+```java
+public interface OrderRepository {
+    Optional<Order> findById(Long id);
+    List<Order> findAll();
+    Order save(Order order);
+    void deleteById(Long id);
+}
+```
+
+Concrete implementations handle storage details (JPA, JDBC, in-memory for tests).
+
+## Service Layer
+
+Business logic in service classes; keep controllers and repositories thin:
+
+```java
+public class OrderService {
+    private final OrderRepository orderRepository;
+    private final PaymentGateway paymentGateway;
+
+    public OrderService(OrderRepository orderRepository, PaymentGateway paymentGateway) {
+        this.orderRepository = orderRepository;
+        this.paymentGateway = paymentGateway;
+    }
+
+    public OrderSummary placeOrder(CreateOrderRequest request) {
+        var order = Order.from(request);
+        paymentGateway.charge(order.total());
+        var saved = orderRepository.save(order);
+        return OrderSummary.from(saved);
+    }
+}
+```
+
+## Constructor Injection
+
+Always use constructor injection — never field injection:
+
+```java
+// GOOD — constructor injection (testable, immutable)
+public class NotificationService {
+    private final EmailSender emailSender;
+
+    public NotificationService(EmailSender emailSender) {
+        this.emailSender = emailSender;
+    }
+}
+
+// BAD — field injection (untestable without reflection, requires framework magic)
+public class NotificationService {
+    @Inject // or @Autowired
+    private EmailSender emailSender;
+}
+```
+
+## DTO Mapping
+
+Use records for DTOs. Map at service/controller boundaries:
+
+```java
+public record OrderResponse(Long id, String customer, BigDecimal total) {
+    public static OrderResponse from(Order order) {
+        return new OrderResponse(order.getId(), order.getCustomerName(), order.getTotal());
+    }
+}
+```
+
+## Builder Pattern
+
+Use for objects with many optional parameters:
+
+```java
+public class SearchCriteria {
+    private final String query;
+    private final int page;
+    private final int size;
+    private final String sortBy;
+
+    private SearchCriteria(Builder builder) {
+        this.query = builder.query;
+        this.page = builder.page;
+        this.size = builder.size;
+        this.sortBy = builder.sortBy;
+    }
+
+    public static class Builder {
+        private String query = "";
+        private int page = 0;
+        private int size = 20;
+        private String sortBy = "id";
+
+        public Builder query(String query) { this.query = query; return this; }
+        public Builder page(int page) { this.page = page; return this; }
+        public Builder size(int size) { this.size = size; return this; }
+        public Builder sortBy(String sortBy) { this.sortBy = sortBy; return this; }
+        public SearchCriteria build() { return new SearchCriteria(this); }
+    }
+}
+```
+
+## Sealed Types for Domain Models
+
+```java
+public sealed interface PaymentResult permits PaymentSuccess, PaymentFailure {
+    record PaymentSuccess(String transactionId, BigDecimal amount) implements PaymentResult {}
+    record PaymentFailure(String errorCode, String message) implements PaymentResult {}
+}
+
+// Exhaustive handling (Java 21+)
+String message = switch (result) {
+    case PaymentSuccess s -> "Paid: " + s.transactionId();
+    case PaymentFailure f -> "Failed: " + f.errorCode();
+};
+```
+
+## API Response Envelope
+
+Consistent API responses:
+
+```java
+public record ApiResponse<T>(boolean success, T data, String error) {
+    public static <T> ApiResponse<T> ok(T data) {
+        return new ApiResponse<>(true, data, null);
+    }
+    public static <T> ApiResponse<T> error(String message) {
+        return new ApiResponse<>(false, null, message);
+    }
+}
+```
+
+## References
+
+See skill: `springboot-patterns` for Spring Boot architecture patterns.
+See skill: `jpa-patterns` for entity design and query optimization.

package/.agent/rules/java/security.md

@@ -1,100 +1,100 @@
----
-paths:
-  - "**/*.java"
----
-# Java Security
-
-> This file extends [common/security.md](../common/security.md) with Java-specific content.
-
-## Secrets Management
-
-- Never hardcode API keys, tokens, or credentials in source code
-- Use environment variables: `System.getenv("API_KEY")`
-- Use a secret manager (Vault, AWS Secrets Manager) for production secrets
-- Keep local config files with secrets in `.gitignore`
-
-```java
-// BAD
-private static final String API_KEY = "sk-abc123...";
-
-// GOOD — environment variable
-String apiKey = System.getenv("PAYMENT_API_KEY");
-Objects.requireNonNull(apiKey, "PAYMENT_API_KEY must be set");
-```
-
-## SQL Injection Prevention
-
-- Always use parameterized queries — never concatenate user input into SQL
-- Use `PreparedStatement` or your framework's parameterized query API
-- Validate and sanitize any input used in native queries
-
-```java
-// BAD — SQL injection via string concatenation
-Statement stmt = conn.createStatement();
-String sql = "SELECT * FROM orders WHERE name = '" + name + "'";
-stmt.executeQuery(sql);
-
-// GOOD — PreparedStatement with parameterized query
-PreparedStatement ps = conn.prepareStatement("SELECT * FROM orders WHERE name = ?");
-ps.setString(1, name);
-
-// GOOD — JDBC template
-jdbcTemplate.query("SELECT * FROM orders WHERE name = ?", mapper, name);
-```
-
-## Input Validation
-
-- Validate all user input at system boundaries before processing
-- Use Bean Validation (`@NotNull`, `@NotBlank`, `@Size`) on DTOs when using a validation framework
-- Sanitize file paths and user-provided strings before use
-- Reject input that fails validation with clear error messages
-
-```java
-// Validate manually in plain Java
-public Order createOrder(String customerName, BigDecimal amount) {
-    if (customerName == null || customerName.isBlank()) {
-        throw new IllegalArgumentException("Customer name is required");
-    }
-    if (amount == null || amount.compareTo(BigDecimal.ZERO) <= 0) {
-        throw new IllegalArgumentException("Amount must be positive");
-    }
-    return new Order(customerName, amount);
-}
-```
-
-## Authentication and Authorization
-
-- Never implement custom auth crypto — use established libraries
-- Store passwords with bcrypt or Argon2, never MD5/SHA1
-- Enforce authorization checks at service boundaries
-- Clear sensitive data from logs — never log passwords, tokens, or PII
-
-## Dependency Security
-
-- Run `mvn dependency:tree` or `./gradlew dependencies` to audit transitive dependencies
-- Use OWASP Dependency-Check or Snyk to scan for known CVEs
-- Keep dependencies updated — set up Dependabot or Renovate
-
-## Error Messages
-
-- Never expose stack traces, internal paths, or SQL errors in API responses
-- Map exceptions to safe, generic client messages at handler boundaries
-- Log detailed errors server-side; return generic messages to clients
-
-```java
-// Log the detail, return a generic message
-try {
-    return orderService.findById(id);
-} catch (OrderNotFoundException ex) {
-    log.warn("Order not found: id={}", id);
-    return ApiResponse.error("Resource not found");  // generic, no internals
-} catch (Exception ex) {
-    log.error("Unexpected error processing order id={}", id, ex);
-    return ApiResponse.error("Internal server error");  // never expose ex.getMessage()
-}
-```
-
-## References
-
-See skill: `springboot-security` for Spring Security authentication and authorization patterns.
-See skill: `security-review` for general security checklists.
+---
+paths:
+  - "**/*.java"
+---
+# Java Security
+
+> This file extends [common/security.md](../common/security.md) with Java-specific content.
+
+## Secrets Management
+
+- Never hardcode API keys, tokens, or credentials in source code
+- Use environment variables: `System.getenv("API_KEY")`
+- Use a secret manager (Vault, AWS Secrets Manager) for production secrets
+- Keep local config files with secrets in `.gitignore`
+
+```java
+// BAD
+private static final String API_KEY = "sk-abc123...";
+
+// GOOD — environment variable
+String apiKey = System.getenv("PAYMENT_API_KEY");
+Objects.requireNonNull(apiKey, "PAYMENT_API_KEY must be set");
+```
+
+## SQL Injection Prevention
+
+- Always use parameterized queries — never concatenate user input into SQL
+- Use `PreparedStatement` or your framework's parameterized query API
+- Validate and sanitize any input used in native queries
+
+```java
+// BAD — SQL injection via string concatenation
+Statement stmt = conn.createStatement();
+String sql = "SELECT * FROM orders WHERE name = '" + name + "'";
+stmt.executeQuery(sql);
+
+// GOOD — PreparedStatement with parameterized query
+PreparedStatement ps = conn.prepareStatement("SELECT * FROM orders WHERE name = ?");
+ps.setString(1, name);
+
+// GOOD — JDBC template
+jdbcTemplate.query("SELECT * FROM orders WHERE name = ?", mapper, name);
+```
+
+## Input Validation
+
+- Validate all user input at system boundaries before processing
+- Use Bean Validation (`@NotNull`, `@NotBlank`, `@Size`) on DTOs when using a validation framework
+- Sanitize file paths and user-provided strings before use
+- Reject input that fails validation with clear error messages
+
+```java
+// Validate manually in plain Java
+public Order createOrder(String customerName, BigDecimal amount) {
+    if (customerName == null || customerName.isBlank()) {
+        throw new IllegalArgumentException("Customer name is required");
+    }
+    if (amount == null || amount.compareTo(BigDecimal.ZERO) <= 0) {
+        throw new IllegalArgumentException("Amount must be positive");
+    }
+    return new Order(customerName, amount);
+}
+```
+
+## Authentication and Authorization
+
+- Never implement custom auth crypto — use established libraries
+- Store passwords with bcrypt or Argon2, never MD5/SHA1
+- Enforce authorization checks at service boundaries
+- Clear sensitive data from logs — never log passwords, tokens, or PII
+
+## Dependency Security
+
+- Run `mvn dependency:tree` or `./gradlew dependencies` to audit transitive dependencies
+- Use OWASP Dependency-Check or Snyk to scan for known CVEs
+- Keep dependencies updated — set up Dependabot or Renovate
+
+## Error Messages
+
+- Never expose stack traces, internal paths, or SQL errors in API responses
+- Map exceptions to safe, generic client messages at handler boundaries
+- Log detailed errors server-side; return generic messages to clients
+
+```java
+// Log the detail, return a generic message
+try {
+    return orderService.findById(id);
+} catch (OrderNotFoundException ex) {
+    log.warn("Order not found: id={}", id);
+    return ApiResponse.error("Resource not found");  // generic, no internals
+} catch (Exception ex) {
+    log.error("Unexpected error processing order id={}", id, ex);
+    return ApiResponse.error("Internal server error");  // never expose ex.getMessage()
+}
+```
+
+## References
+
+See skill: `springboot-security` for Spring Security authentication and authorization patterns.
+See skill: `security-review` for general security checklists.