@eltonssouza/development-utility-kit 1.0.0

package/.claude/stacks/_template.md

@@ -0,0 +1,116 @@
+---
+stack: <lang>/<framework>           # e.g. java/spring-boot-3, python/django, go/gin
+versions_covered: "<range>"          # e.g. "3.0.x — 3.4.x", "5.0.x — 5.1.x"
+last_validated: <YYYY-MM-DD>         # date of last validation in real project
+validated_against: "<description>"   # e.g. "projeto-x v1.2 (Java 21 + SB 3.2.5)"
+status: active                       # active | deprecated | archived
+pack_owner: "@<github-handle>"       # e.g. "@elton"
+security_review: <YYYY-MM-DD>        # date of last security-focused review
+next_review_due: <YYYY-MM-DD>        # security_review + 12 months
+---
+
+# <Stack name + version>
+
+<Intro 1-3 lines: what this pack covers, when to use it vs alternative pack/version.>
+
+## 1. When to use this pack
+
+- Project declares `Primary stack: <X>` in `## Project Identity`.
+- Build manifest (`pom.xml` / `package.json` / `pyproject.toml` / `go.mod` / etc.) declares versions within `versions_covered`.
+- (Optional) Greenfield/legacy guidance — when to prefer next-major pack instead.
+
+## 2. Stack baseline (what this pack assumes)
+
+| Component | Version range | Notes |
+|---|---|---|
+| <language> | <range> | <notes — LTS, EOL dates> |
+| <framework> | <range> | <key feature for this major> |
+| <build tool> | <range> | <Maven Wrapper, npm, etc.> |
+| <test framework> | <range> | <what to avoid — e.g. never H2 as Postgres> |
+| <observability> | <stack> | <Micrometer, OpenTelemetry, etc.> |
+
+## 3. Project structure
+
+```
+<tree of canonical folder layout for this stack>
+```
+
+## 4. Code patterns
+
+### <Pattern name 1 — e.g. DTOs>
+<Real compilable snippet showing the canonical pattern + 1-line rule.>
+
+### <Pattern name 2 — e.g. Error handling>
+<Snippet + rule.>
+
+### <Pattern name 3, 4, 5...>
+
+## 5. Testing
+
+### Unit
+<Snippet + framework versions + rules.>
+
+### Integration
+<Snippet — REAL test pattern, not pseudocode.>
+
+### <Other test types if relevant — slice, contract, mutation, e2e>
+
+## 6. Build & run commands
+
+```bash
+<exact commands a dev would run — build, test, run, lint, coverage>
+```
+
+## 7. Security (per ADR-007 + ADR-027 — MANDATORY section)
+
+### 7.1 Authentication & Authorization
+<Stack-specific auth: framework class names, hashing, MFA hooks>
+
+### 7.2 CORS
+<Snippet — never `*` in prod>
+
+### 7.3 Validation & input sanitization
+<SQL injection, XSS, path traversal — stack-specific mitigation>
+
+### 7.4 Secrets management
+<Env vars, vault, never in committed files>
+
+### 7.5 Rate limiting
+<Library + config snippet for public endpoints>
+
+### 7.6 OWASP Top 10 mapping
+
+| OWASP | Mitigation in this stack |
+|---|---|
+| A01 Broken Access Control | <stack-specific> |
+| A02 Cryptographic Failures | <stack-specific> |
+| A03 Injection | <stack-specific> |
+| A04 Insecure Design | <stack-specific> |
+| A05 Security Misconfiguration | <stack-specific> |
+| A06 Vulnerable Components | <CVE scanner + Renovate/Dependabot> |
+| A07 Auth Failures | <rate limit + account lock + MFA> |
+| A08 Data Integrity | <signature verification, supply chain, SBOM> |
+| A09 Logging Failures | <structured logs + correlation ID + no PII> |
+| A10 SSRF | <allowlist for outbound, validate URLs> |
+
+### 7.7 LGPD / GDPR / compliance specifics (if applicable)
+<PII tagging, soft-delete, data subject access, encryption at rest>
+
+## 8. Anti-patterns (block in code-review)
+
+| ❌ Bad | ✅ Good | Why |
+|---|---|---|
+| <bad pattern> | <good replacement> | <reason> |
+| ... | ... | ... |
+
+## 9. Migration hints — <this version> → <next major>
+
+<Short list of breaking changes when migrating. Points to `migrator` agent.>
+
+## 10. References
+
+- ADR-007 (Senior+ gate thresholds)
+- ADR-026 (Generic agents + packs architecture)
+- ADR-027 (Pack governance)
+- <Official framework migration guide URLs>
+- <OWASP / compliance references>

package/.claude/stacks/java/spring-boot-3.md

@@ -0,0 +1,376 @@
+---
+stack: java/spring-boot-3
+versions_covered: "3.0.x — 3.4.x"
+last_validated: 2026-05-27
+validated_against: "sandbox — Java 21 LTS + Spring Boot 3.2.5"
+status: active
+pack_owner: "@elton"
+security_review: 2026-05-27
+next_review_due: 2027-05-27
+---
+
+# Java 17/21 + Spring Boot 3.x
+
+Knowledge pack for projects on Java 17 (minimum) or Java 21 LTS + Spring Boot 3.x. Covers projects in production that have not yet migrated to Java 25 + Spring Boot 4 (covered by `spring-boot-4.md`).
+
+## 1. When to use this pack
+
+- Project declares `Primary stack: Java 17 + Spring Boot 3.x` or `Java 21 + Spring Boot 3.x` in `## Project Identity`.
+- `pom.xml` declares `<java.version>17|21</java.version>` and `<spring-boot.version>3.0.x — 3.4.x</spring-boot.version>`.
+- Greenfield: prefer `spring-boot-4.md` (Java 25 + SB 4). This pack is for **maintained legacy**.
+
+## 2. Stack baseline (what this pack assumes)
+
+| Component | Version range | Notes |
+|---|---|---|
+| Java | 17 (min) / 21 (LTS preferred) | Java 17 ELS until 2029; 21 LTS until 2031 |
+| Spring Boot | 3.0.x – 3.4.x | 3.0 = jakarta migration cutoff; 3.2 = RestClient + Virtual Threads |
+| Jakarta EE | 9+ (jakarta.* namespace) | NEVER mix with javax.* |
+| JPA / Hibernate | Hibernate 6.x (jakarta.persistence) | Schema validation via Flyway/Liquibase, never Hibernate auto |
+| Spring Security | 6.x | SecurityFilterChain Bean (WebSecurityConfigurerAdapter removed) |
+| Validation | Jakarta Validation 3.x | `jakarta.validation.constraints.*` |
+| Tomcat / Jetty / Undertow | 10.1+ (Servlet 6.0) | Tomcat default |
+| Build | Maven 3.9+ or Gradle 8.5+ | Maven Wrapper / Gradle Wrapper committed |
+| Tests | JUnit 5.10+, Mockito 5.x, Testcontainers 1.20+ | Never H2 as Postgres stand-in |
+| Observability | Micrometer Observation API + Prometheus | Tracing via OpenTelemetry W3C |
+
+## 3. Project structure (DDD)
+
+```
+backend/
+├── src/main/java/com/<company>/<project>/
+│   ├── domain/           ← pure POJOs, value objects, domain services, repository PORTS (interfaces)
+│   ├── application/      ← use cases (1 public method each), record DTOs req/res, mappers
+│   ├── infrastructure/   ← JPA adapters, JpaRepository, RestClient adapters, security, config
+│   └── web/              ← @RestController, @ControllerAdvice, filters
+├── src/main/resources/
+│   ├── application.yml
+│   ├── application-{dev,prod}.yml
+│   └── db/migration/V<ts>__<verb>_<subject>.sql   ← Flyway migrations
+└── src/test/java/com/<company>/<project>/
+    ├── <pkg>...Test.java   ← unit (JUnit + Mockito)
+    └── <pkg>...IT.java     ← integration (Testcontainers)
+```
+
+## 4. Code patterns
+
+### DTOs as records (req/res separated)
+
+```java
+// application/dto/CreateProductRequest.java
+public record CreateProductRequest(
+    @NotBlank @Size(max = 120) String name,
+    @NotNull @Positive BigDecimal price,
+    @NotNull @PositiveOrZero Integer stock
+) {}
+
+// application/dto/ProductResponse.java
+public record ProductResponse(
+    UUID id, String name, BigDecimal price, Integer stock, Instant createdAt
+) {}
+```
+
+**Rule**: never expose JPA `@Entity` to controllers. Mapper layer is explicit (`ProductMapper.toResponse(entity)`).
+
+### Controller + ProblemDetail (RFC 9457)
+
+```java
+@RestController
+@RequestMapping("/api/v1/products")
+@RequiredArgsConstructor
+public class ProductController {
+    private final CreateProductUseCase createUseCase;
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    public ProductResponse create(@Valid @RequestBody CreateProductRequest req) {
+        return createUseCase.execute(req);
+    }
+}
+
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ProblemDetail handleValidation(MethodArgumentNotValidException ex) {
+        var pd = ProblemDetail.forStatus(HttpStatus.UNPROCESSABLE_ENTITY);
+        pd.setTitle("Validation failed");
+        pd.setProperty("errors", ex.getBindingResult().getFieldErrors().stream()
+            .map(e -> Map.of("field", e.getField(), "msg", e.getDefaultMessage()))
+            .toList());
+        return pd;
+    }
+}
+```
+
+### Transactions
+
+- `@Transactional(readOnly = true)` on query methods (avoids dirty-check overhead).
+- `@Transactional` on commands. Propagation = REQUIRED (default). Explicit `REQUIRES_NEW` only with documented reason.
+- Never `@Transactional` on controllers — keep on `application/` use cases.
+
+### External calls (RestClient since SB 3.2)
+
+```java
+// infrastructure/adapter/PaymentGatewayAdapter.java
+@Component
+public class PaymentGatewayAdapter implements PaymentGateway {
+    private final RestClient client;
+
+    public PaymentGatewayAdapter(RestClient.Builder builder, AppProps props) {
+        this.client = builder
+            .baseUrl(props.paymentGatewayUrl())
+            .requestFactory(ClientHttpRequestFactoryBuilder.detect()
+                .build(ClientHttpRequestFactorySettings.defaults()
+                    .withConnectTimeout(Duration.ofSeconds(3))
+                    .withReadTimeout(Duration.ofSeconds(10))))
+            .build();
+    }
+
+    @Override
+    @Retry(name = "payment-gateway")
+    @CircuitBreaker(name = "payment-gateway")
+    public PaymentResult charge(ChargeCommand cmd) {
+        try {
+            return client.post()
+                .uri("/charges")
+                .body(cmd)
+                .retrieve()
+                .body(PaymentResult.class);
+        } catch (RestClientResponseException e) {
+            throw new PaymentGatewayException("status=" + e.getStatusCode(), e);
+        }
+    }
+}
+```
+
+**Rules**: explicit timeout (connect + read), retry policy (Resilience4j), circuit breaker on external calls. Map foreign exceptions to domain exceptions.
+
+### Pagination
+
+```java
+@GetMapping
+public Page<ProductResponse> list(Pageable pageable) {
+    return service.findAll(pageable).map(ProductMapper::toResponse);
+}
+```
+
+Client passes `?page=0&size=20&sort=name,asc`. Response wraps `content`, `totalElements`, `totalPages`, `number`, `size`.
+
+## 5. Testing
+
+### Unit (JUnit 5 + Mockito + AssertJ)
+
+```java
+@ExtendWith(MockitoExtension.class)
+class CreateProductUseCaseTest {
+    @Mock ProductRepository repo;
+    @InjectMocks CreateProductUseCase useCase;
+
+    @Test
+    void rejectsNegativePrice() {
+        var cmd = new CreateProductCommand("widget", BigDecimal.valueOf(-1), 10);
+        assertThatThrownBy(() -> useCase.execute(cmd))
+            .isInstanceOf(BusinessRuleException.class)
+            .hasMessageContaining("price");
+    }
+}
+```
+
+### Integration (Testcontainers, NEVER H2)
+
+```java
+@SpringBootTest
+@Testcontainers
+@ActiveProfiles("test")
+class ProductRepositoryIT {
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");
+
+    @DynamicPropertySource
+    static void props(DynamicPropertyRegistry r) {
+        r.add("spring.datasource.url", postgres::getJdbcUrl);
+        r.add("spring.datasource.username", postgres::getUsername);
+        r.add("spring.datasource.password", postgres::getPassword);
+    }
+
+    @Autowired ProductRepository repo;
+    // ...
+}
+```
+
+### Web slice (@WebMvcTest)
+
+```java
+@WebMvcTest(ProductController.class)
+class ProductControllerTest {
+    @Autowired MockMvc mvc;
+    @MockBean CreateProductUseCase useCase;
+
+    @Test
+    void returns422OnInvalidPayload() throws Exception {
+        mvc.perform(post("/api/v1/products")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("{}"))
+            .andExpect(status().isUnprocessableEntity())
+            .andExpect(jsonPath("$.title").value("Validation failed"));
+    }
+}
+```
+
+### Mutation (PIT)
+
+Target ≥ 70% on `domain/` + `application/`. Run via:
+```bash
+./mvnw pitest:mutationCoverage
+```
+
+## 6. Build & run commands
+
+```bash
+./mvnw clean verify                    # full build + tests + coverage
+./mvnw spring-boot:run                 # local dev (port 8080)
+./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
+./mvnw spring-boot:test-run            # with hot-reload (devtools)
+./mvnw spotbugs:check                  # static analysis
+./mvnw org.owasp:dependency-check-maven:check  # CVE scan
+./mvnw pitest:mutationCoverage         # mutation testing
+```
+
+## 7. Security (per ADR-007 + ADR-027)
+
+### 7.1 Authentication & Authorization
+
+- **Spring Security 6** with `SecurityFilterChain` Bean (NEVER `WebSecurityConfigurerAdapter` — removed).
+- **JWT validation** via `spring-boot-starter-oauth2-resource-server` for stateless APIs.
+- **`@PreAuthorize`** on controller methods or use cases. Avoid URL-based authorization for fine-grained rules.
+- **Password hashing**: `BCryptPasswordEncoder(strength = 12)`. NEVER MD5/SHA1.
+
+```java
+@Configuration
+@EnableMethodSecurity
+public class SecurityConfig {
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        return http
+            .csrf(csrf -> csrf.disable())  // stateless API; enable for stateful UI
+            .cors(Customizer.withDefaults())
+            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/api/v1/auth/**", "/actuator/health").permitAll()
+                .anyRequest().authenticated()
+            )
+            .oauth2ResourceServer(oauth -> oauth.jwt(Customizer.withDefaults()))
+            .headers(h -> h
+                .contentSecurityPolicy(csp -> csp.policyDirectives("default-src 'self'"))
+                .httpStrictTransportSecurity(hsts -> hsts.maxAgeInSeconds(31536000).includeSubDomains(true))
+                .frameOptions(f -> f.deny())
+            )
+            .build();
+    }
+}
+```
+
+### 7.2 CORS
+
+NEVER `*` in production. Explicit list:
+
+```java
+@Bean
+public CorsConfigurationSource corsConfigurationSource() {
+    var config = new CorsConfiguration();
+    config.setAllowedOrigins(List.of("https://app.example.com"));
+    config.setAllowedMethods(List.of("GET","POST","PUT","DELETE","OPTIONS"));
+    config.setAllowedHeaders(List.of("Authorization","Content-Type"));
+    config.setAllowCredentials(true);
+    config.setMaxAge(3600L);
+    var source = new UrlBasedCorsConfigurationSource();
+    source.registerCorsConfiguration("/api/**", config);
+    return source;
+}
+```
+
+### 7.3 Validation & input sanitization
+
+- **All `@RequestBody`** must be `@Valid`. ProblemDetail returns 422 on violation.
+- **HTML/XSS**: sanitize via OWASP Java HTML Sanitizer if rendering user input back. Never trust client.
+- **SQL injection**: NEVER concatenate. Use `@Query` with named params or Specifications.
+- **Path traversal**: validate file paths against allowlist; reject `..` sequences.
+
+### 7.4 Secrets management
+
+- NEVER in `application.properties` or `application.yml` committed to git.
+- Use environment variables (`spring.datasource.password=${DB_PASSWORD}`) or Spring Cloud Config + Vault.
+- Local dev: `application-local.yml` in `.gitignore` OR `~/.secrets/<project>.env`.
+- Production: Vault, AWS Secrets Manager, Azure Key Vault.
+
+### 7.5 Rate limiting
+
+For public endpoints (login, signup, password reset) — Bucket4j:
+
+```java
+@Component
+public class RateLimitFilter extends OncePerRequestFilter {
+    private final Bucket bucket = Bucket.builder()
+        .addLimit(Bandwidth.classic(10, Refill.intervally(10, Duration.ofMinutes(1))))
+        .build();
+    // applies on /api/v1/auth/*
+}
+```
+
+### 7.6 OWASP coverage (Top 10)
+
+| OWASP | Mitigation in this stack |
+|---|---|
+| A01 Broken Access Control | `@PreAuthorize` + IDOR check (always validate principal owns resource) |
+| A02 Cryptographic Failures | BCrypt 12; JWT signed RS256 (never HS256 in distributed system); HTTPS only |
+| A03 Injection | JPA parameterized queries; never `String.format` SQL; input validation |
+| A04 Insecure Design | Threat model + ADR for new bounded contexts |
+| A05 Security Misconfiguration | SecurityFilterChain explicit; headers via `.headers()`; `/actuator/*` restricted |
+| A06 Vulnerable Components | OWASP dependency-check in CI; Renovate/Dependabot bumps |
+| A07 Auth Failures | Rate limit on auth; `@Lock` on user account after N failures; MFA where critical |
+| A08 Data Integrity | JWT signature; Maven artifact checksums; supply chain via SBOM |
+| A09 Logging Failures | Structured JSON logs + correlation ID via MDC; AUDIT topic separated; PII never logged |
+| A10 SSRF | Allowlist of outbound hosts in `application.yml`; RestClient validates URL against list |
+
+### 7.7 LGPD specifics (if applicable)
+
+- Identify PII fields (email, CPF, phone) and tag with `@JsonIgnore` on logging serializers.
+- Right to deletion: implement soft-delete + audit log of deletion request.
+- Data subject access: endpoint to export user's data in machine-readable format.
+- Encryption at rest for sensitive columns (e.g. via JPA `AttributeConverter` + AES-256-GCM).
+
+## 8. Anti-patterns (block in code-review)
+
+| ❌ Bad | ✅ Good | Why |
+|---|---|---|
+| `@Entity` returned from controller | `@Entity` → mapper → `record Response` | Decouples API contract from DB |
+| `javax.validation.constraints.*` | `jakarta.validation.constraints.*` | SB 3 uses jakarta namespace |
+| `WebSecurityConfigurerAdapter` | `SecurityFilterChain` Bean | Removed in Spring Security 6 |
+| `RestTemplate` for new code | `RestClient` (SB 3.2+) | Modern, fluent, supports interception |
+| `H2` in tests | `Testcontainers` Postgres | H2 has different SQL dialect |
+| `@Autowired` field injection | Constructor injection (`@RequiredArgsConstructor`) | Testable, immutable, final fields |
+| `var` in method signature | Full type in signature | Public API contract should be explicit |
+| `// TODO` committed | `docs/brain/architecture/tech-debt.md` | Trackable |
+| `log.info(token)` | `log.info("token=***")` redaction | Never log credentials/PII |
+| `password.equals(input)` | `passwordEncoder.matches(input, hash)` | Timing-safe + hashed comparison |
+
+## 9. Migration hints — Spring Boot 3.x → 4.x
+
+When migrating a project from this pack to `spring-boot-4.md`:
+
+- Java 17/21 → 25 (LTS). Check libs for Java 25 compatibility.
+- Spring Boot 3.x → 4.0: review breaking changes in `spring-boot-migrator-3.0-to-4.0.md` (official docs).
+- `RestClient` API may evolve — review docs.
+- ProblemDetail enhancements (more fields, MDC integration).
+- Native compilation maturity (Spring Boot 4 + GraalVM 23+).
+- Use `migrator` agent — it knows both packs and proposes ADR per major cross.
+
+## 10. References
+
+- ADR-007 (Senior+ gate thresholds — apply to projects using this pack)
+- ADR-026 (Generic agents + packs architecture)
+- ADR-027 (This pack's governance — frontmatter, security review)
+- Spring Boot 3.x release notes: https://github.com/spring-projects/spring-boot/wiki
+- Spring Security 6 migration: https://docs.spring.io/spring-security/reference/6.0/migration.html
+- OWASP Top 10 (2021): https://owasp.org/Top10/
+- Jakarta EE migration guide: https://www.eclipse.org/community/eclipse_newsletter/2022/march/1.php