maestro-bundle 1.3.0 → 1.4.0

package/templates/bundle-jhipster-monorepo/skills/jhipster-security/SKILL.md

@@ -1,15 +1,31 @@
 ---
 name: jhipster-security
-description: Configurar segurança no JHipster com JWT, OAuth2, roles e permissões. Use quando precisar implementar autenticação, autorização, roles, ou proteger endpoints.
+description: Configure security in JHipster with JWT, OAuth2, roles, and permissions. Use when implementing authentication, authorization, roles, protecting endpoints, or configuring CORS/CSRF.
+version: 1.0.0
+author: Maestro
 ---
 
 # JHipster Security
 
-## JWT (padrão monorepo)
+Configure and customize security in JHipster applications using JWT, OAuth2/Keycloak, role-based access control, and method-level security.
 
-O JHipster gera JWT automaticamente. Customizar:
+## When to Use
+- When protecting REST endpoints by role
+- When creating custom roles and authorities
+- When configuring JWT or OAuth2/Keycloak
+- When adding method-level security (@PreAuthorize)
+- When setting up CORS, CSRF, or rate limiting
 
-### Proteger endpoints por role
+## Available Operations
+1. Configure endpoint security by role
+2. Create custom roles and authorities
+3. Add method-level security annotations
+4. Configure OAuth2 with Keycloak
+5. Apply security checklist
+
+## Multi-Step Workflow
+
+### Step 1: Configure Endpoint Protection
 
 ```java
 @Configuration
@@ -31,18 +47,24 @@ public class SecurityConfiguration {
 }
 ```
 
-### Criar roles customizadas
+### Step 2: Define Custom Roles
 
 ```java
 public final class AuthoritiesConstants {
     public static final String ADMIN = "ROLE_ADMIN";
     public static final String USER = "ROLE_USER";
-    public static final String AGENT = "ROLE_AGENT";        // Agentes AI
-    public static final String TECH_LEAD = "ROLE_TECH_LEAD"; // Aprovador de merge
+    public static final String AGENT = "ROLE_AGENT";        // AI Agents
+    public static final String TECH_LEAD = "ROLE_TECH_LEAD"; // Merge approver
 }
 ```
 
-### Segurança no método
+Add roles to Liquibase data:
+```bash
+# Edit authority.csv to add new roles
+cat src/main/resources/config/liquibase/data/authority.csv
+```
+
+### Step 3: Add Method-Level Security
 
 ```java
 @Service
@@ -50,17 +72,17 @@ public class DemandServiceImpl implements DemandService {
 
     @PreAuthorize("hasAuthority('ROLE_TECH_LEAD')")
     public void approveMerge(Long demandId) {
-        // Somente tech lead pode aprovar merge
+        // Only tech lead can approve merge
     }
 
     @PreAuthorize("#login == authentication.name or hasAuthority('ROLE_ADMIN')")
     public DemandDTO findByUser(String login) {
-        // Usuário vê só suas demands, admin vê todas
+        // User sees only their demands, admin sees all
     }
 }
 ```
 
-## OAuth2 + Keycloak (recomendado para microservices)
+### Step 4: Configure OAuth2 + Keycloak (for production)
 
 ```yaml
 # application.yml
@@ -78,12 +100,77 @@ spring:
             scope: openid,profile,email
 ```
 
-## Checklist de segurança
+```bash
+# Start Keycloak with Docker
+docker-compose -f src/main/docker/keycloak.yml up -d
+
+# Access Keycloak admin console
+# URL: http://localhost:9080
+# User: admin / Password: admin
+```
+
+### Step 5: Apply Security Checklist
+
+```bash
+# Verify no hardcoded secrets
+grep -r "password\|secret\|api.key" src/main/resources/ --include="*.yml" --include="*.properties"
+
+# Check CORS configuration
+grep -r "cors" src/main/java/ --include="*.java"
+
+# Verify HTTPS configuration for prod profile
+grep -r "ssl\|https" src/main/resources/config/application-prod.yml
+```
+
+Checklist:
+- [ ] Rate limiting on public endpoints
+- [ ] CORS properly configured (not `*` in production)
+- [ ] CSRF enabled for browser, disabled for API
+- [ ] Secrets in environment variables, never in code
+- [ ] Passwords with BCrypt (JHipster default)
+- [ ] Audit trail for critical operations
+- [ ] HTTPS in production
+
+### Step 6: Test Security
+
+```bash
+# Run security-related tests
+./mvnw test -Dtest="*Security*,*Auth*"
+
+# Test endpoint protection manually
+curl -v http://localhost:8080/api/demands  # Should return 401
+curl -v -H "Authorization: Bearer <token>" http://localhost:8080/api/demands  # Should return 200
+```
 
-- [ ] Rate limiting nos endpoints públicos
-- [ ] CORS configurado corretamente (não `*` em prod)
-- [ ] CSRF habilitado para browser, desabilitado para API
-- [ ] Secrets em variáveis de ambiente, nunca no código
-- [ ] Senhas com BCrypt (padrão JHipster)
-- [ ] Audit trail para operações críticas
-- [ ] HTTPS em produção
+## Resources
+- `references/security-checklist.md` - Complete security checklist for JHipster applications
+
+## Examples
+### Example 1: Protect an Endpoint by Role
+User asks: "Only admins should access the /api/admin/reports endpoint"
+Response approach:
+1. Add `.requestMatchers("/api/admin/reports/**").hasAuthority(AuthoritiesConstants.ADMIN)` to SecurityConfiguration
+2. Run `./mvnw test -Dtest="*Security*"` to verify
+3. Test manually with curl
+
+### Example 2: Add a Custom Role
+User asks: "Create a TECH_LEAD role that can approve merges"
+Response approach:
+1. Add `ROLE_TECH_LEAD` to `AuthoritiesConstants`
+2. Add to `authority.csv` in Liquibase data
+3. Add `@PreAuthorize("hasAuthority('ROLE_TECH_LEAD')")` to the approval method
+4. Run `./mvnw test`
+
+### Example 3: Setup Keycloak
+User asks: "Configure OAuth2 with Keycloak for this project"
+Response approach:
+1. Add OAuth2 configuration to `application.yml`
+2. Start Keycloak with `docker-compose -f src/main/docker/keycloak.yml up -d`
+3. Configure realm and client in Keycloak admin console
+4. Test login flow
+
+## Notes
+- JWT is the default for monorepo; OAuth2/Keycloak recommended for microservices
+- Always use `@PreAuthorize` for fine-grained access control in services
+- Never expose security configuration details in API responses
+- Test both authenticated and unauthenticated access in integration tests

package/templates/bundle-jhipster-monorepo/skills/jhipster-security/references/security-checklist.md

@@ -0,0 +1,47 @@
+# JHipster Security Checklist
+
+## Authentication
+- [ ] JWT or OAuth2/OIDC properly configured
+- [ ] Token expiration set appropriately
+- [ ] Refresh token mechanism in place
+- [ ] Password policy enforced (BCrypt, min length)
+
+## Authorization
+- [ ] Endpoints protected with proper roles
+- [ ] Method-level security with @PreAuthorize where needed
+- [ ] User can only access their own resources (data isolation)
+- [ ] Admin endpoints separated under /api/admin/
+
+## API Security
+- [ ] Rate limiting on public endpoints
+- [ ] Input validation on all request bodies (@Valid)
+- [ ] CORS configured (not wildcard in production)
+- [ ] CSRF enabled for browser clients
+- [ ] Content-Type validation
+- [ ] Response does not leak internal details
+
+## Data Security
+- [ ] No hardcoded secrets in source code
+- [ ] Secrets stored in environment variables or vault
+- [ ] Parameterized queries (no SQL injection)
+- [ ] Sensitive data encrypted at rest
+- [ ] Passwords hashed with BCrypt
+
+## Infrastructure
+- [ ] HTTPS enforced in production
+- [ ] Security headers configured (X-Frame-Options, CSP, etc.)
+- [ ] Audit trail for critical operations
+- [ ] Logging does not contain sensitive data
+- [ ] Dependencies scanned for vulnerabilities
+
+## Commands for Verification
+```bash
+# Check for hardcoded secrets
+grep -rn "password\|secret\|api.key" src/ --include="*.java" --include="*.yml"
+
+# Run security tests
+./mvnw test -Dtest="*Security*,*Auth*"
+
+# Check dependencies for vulnerabilities
+./mvnw dependency-check:check
+```

package/templates/bundle-jhipster-monorepo/skills/jhipster-spring/SKILL.md

@@ -1,19 +1,39 @@
 ---
 name: jhipster-spring
-description: Desenvolver backend Spring Boot no JHipster com services, repositories, DTOs, MapStruct e Spring Security. Use quando precisar criar endpoints, services, ou customizar o backend JHipster.
+description: Develop Spring Boot backend in JHipster with controllers, services, repositories, DTOs, and MapStruct mappers. Use when creating endpoints, services, repositories, or customizing the JHipster backend.
+version: 1.0.0
+author: Maestro
 ---
 
 # JHipster Spring Boot
 
-## Camadas no JHipster
+Develop and customize the Spring Boot backend generated by JHipster, following the layered architecture with Controllers, Services, Repositories, DTOs, and MapStruct Mappers.
+
+## When to Use
+- When creating new REST endpoints
+- When implementing service layer business logic
+- When creating custom repository queries
+- When defining DTOs and MapStruct mappers
+- When customizing generated backend code
+
+## Available Operations
+1. Create REST controllers with pagination and filtering
+2. Implement service layer with transaction management
+3. Define DTOs using Java Records
+4. Create MapStruct mappers
+5. Add custom repository queries with Spring Data JPA
+
+## Multi-Step Workflow
+
+### Step 1: Understand the Layer Architecture
 
 ```
-Controller (web/rest/) → Service (service/) → Repository (repository/) → Entity (domain/)
-                          ↕
-                      DTO + Mapper (service/dto/ + service/mapper/)
+Controller (web/rest/) --> Service (service/) --> Repository (repository/) --> Entity (domain/)
+                            |
+                        DTO + Mapper (service/dto/ + service/mapper/)
 ```
 
-## Controller — REST API
+### Step 2: Create the Controller
 
 ```java
 @RestController
@@ -61,7 +81,7 @@ public class DemandResource {
 }
 ```
 
-## Service — Lógica de aplicação
+### Step 3: Implement the Service
 
 ```java
 @Service
@@ -98,7 +118,7 @@ public class DemandServiceImpl implements DemandService {
 }
 ```
 
-## DTO — Records (Java 21)
+### Step 4: Define DTOs with Java Records
 
 ```java
 public record CreateDemandDTO(
@@ -116,7 +136,7 @@ public record DemandDTO(
 ) {}
 ```
 
-## MapStruct Mapper
+### Step 5: Create MapStruct Mapper
 
 ```java
 @Mapper(componentModel = "spring", uses = {TaskMapper.class})
@@ -131,7 +151,7 @@ public interface DemandMapper extends EntityMapper<DemandDTO, Demand> {
 }
 ```
 
-## Repository — Spring Data JPA
+### Step 6: Add Repository Queries
 
 ```java
 @Repository
@@ -146,10 +166,58 @@ public interface DemandRepository extends JpaRepository<Demand, Long>, JpaSpecif
 }
 ```
 
-## Regras
+### Step 7: Build and Test
+
+```bash
+# Compile
+./mvnw compile
+
+# Run tests
+./mvnw test
+
+# Run specific test class
+./mvnw test -Dtest="DemandResourceIT"
+
+# Run the application
+./mvnw spring-boot:run
+
+# Test endpoint
+curl http://localhost:8080/api/v1/demands
+```
 
-- Constructor injection sempre (nunca `@Autowired` em campo)
-- `@Transactional(readOnly = true)` em queries
-- `@Transactional` apenas no Service, nunca no Controller
-- DTOs na API, Entities no domínio — nunca misturar
-- Validação com Bean Validation (`@Valid`) no Controller
+## Resources
+- `references/spring-layers.md` - Spring Boot layer conventions and patterns
+
+## Examples
+### Example 1: Create a New REST Endpoint
+User asks: "Create an endpoint to list demands filtered by status"
+Response approach:
+1. Add `@GetMapping` to controller with `@RequestParam` for status
+2. Implement service method with status filter
+3. Add `findByStatus()` to repository
+4. Create DTO if needed
+5. Run `./mvnw test`
+
+### Example 2: Add a Custom Query
+User asks: "I need to fetch a demand with all its tasks eagerly loaded"
+Response approach:
+1. Add `@Query` method to `DemandRepository` with `LEFT JOIN FETCH`
+2. Call from service layer
+3. Map to DTO including tasks
+4. Run `./mvnw test`
+
+### Example 3: Create DTOs for a New Feature
+User asks: "Create request/response DTOs for the demand creation endpoint"
+Response approach:
+1. Create `CreateDemandDTO` record with validation annotations
+2. Create `DemandDTO` record for the response
+3. Create MapStruct mapper
+4. Use in controller with `@Valid @RequestBody`
+5. Run `./mvnw test`
+
+## Notes
+- Always use constructor injection (never `@Autowired` on fields)
+- Use `@Transactional(readOnly = true)` on query methods
+- `@Transactional` only in Service layer, never in Controller
+- DTOs at the API boundary, Entities in the domain -- never mix
+- Validation with Bean Validation (`@Valid`) in the Controller

package/templates/bundle-jhipster-monorepo/skills/jhipster-spring/references/spring-layers.md

@@ -0,0 +1,41 @@
+# Spring Boot Layer Conventions
+
+## Architecture
+```
+Controller (web/rest/) --> Service (service/) --> Repository (repository/) --> Entity (domain/)
+                            |
+                        DTO + Mapper (service/dto/ + service/mapper/)
+```
+
+## Controller Rules
+- `@RestController` + `@RequestMapping`
+- Constructor injection for dependencies
+- `@Valid @RequestBody` for input validation
+- Return `ResponseEntity` for proper HTTP semantics
+- Use `PaginationUtil` for paginated responses
+- No business logic -- delegate to service
+
+## Service Rules
+- `@Service` + `@Transactional`
+- `@Transactional(readOnly = true)` for read operations
+- Business logic and orchestration live here
+- Work with Entities internally, return DTOs externally
+- Constructor injection for repositories and mappers
+
+## Repository Rules
+- Extend `JpaRepository` and optionally `JpaSpecificationExecutor`
+- Use Spring Data derived query methods
+- Use `@Query` with JPQL for complex queries
+- `LEFT JOIN FETCH` for eager loading relationships
+
+## DTO Rules
+- Use Java Records (Java 21)
+- Validation annotations on request DTOs
+- Separate Create/Update/Response DTOs
+- Never expose Entity directly in API
+
+## Mapper Rules
+- Use MapStruct with `@Mapper(componentModel = "spring")`
+- Extend `EntityMapper<DTO, Entity>` from JHipster
+- Use `@Mapping` for field-level customization
+- `uses = {OtherMapper.class}` for nested mappings

package/templates/bundle-jhipster-monorepo/skills/testing-strategy/SKILL.md

@@ -1,27 +1,46 @@
 ---
 name: testing-strategy
-description: Implementar estratégia de testes com unitários, integração e e2e usando Pytest ou JUnit. Use quando for escrever testes, definir estratégia de testes, ou melhorar cobertura.
+description: Implement testing strategy with unit, integration, and e2e tests using Pytest or JUnit. Use when writing tests, defining test strategy, improving coverage, or setting up test infrastructure.
+version: 1.0.0
+author: Maestro
 ---
 
-# Estratégia de Testes
+# Testing Strategy
 
-## Pirâmide
+Implement a comprehensive testing strategy following the test pyramid with unit tests for domain logic, integration tests for infrastructure, and e2e tests for critical flows.
+
+## When to Use
+- When writing tests for new features
+- When defining the test strategy for a module
+- When improving test coverage
+- When setting up test infrastructure (fixtures, factories)
+- When reviewing test quality
+
+## Available Operations
+1. Write unit tests for domain entities and value objects
+2. Write integration tests for repositories
+3. Write API integration tests for controllers
+4. Set up test fixtures and factories
+5. Run tests with coverage reporting
+
+## Multi-Step Workflow
+
+### Step 1: Understand the Test Pyramid
 
 ```
-        /  E2E  \          Poucos, lentos, caros
-       /  Integr. \        Moderados
-      / Unitários   \      Muitos, rápidos, baratos
+        /  E2E  \          Few, slow, expensive
+       /  Integr. \        Moderate
+      / Unit Tests  \      Many, fast, cheap
 ```
 
-## Testes Unitários — Domínio
-
-Testar regras de negócio sem infraestrutura.
+### Step 2: Write Unit Tests for Domain Logic
+Test business rules without infrastructure dependencies.
 
 ```python
 # tests/domain/test_demand.py
 class TestDemand:
     def test_should_decompose_new_demand(self):
-        demand = Demand(id=DemandId.generate(), description="Criar CRUD")
+        demand = Demand(id=DemandId.generate(), description="Create CRUD")
         planner = FakePlanner(tasks=[Task(...), Task(...)])
 
         tasks = demand.decompose(planner)
@@ -30,14 +49,14 @@ class TestDemand:
         assert demand.status == DemandStatus.PLANNED
 
     def test_should_reject_decompose_if_already_planned(self):
-        demand = Demand(id=DemandId.generate(), description="Criar CRUD")
+        demand = Demand(id=DemandId.generate(), description="Create CRUD")
         demand.decompose(FakePlanner(tasks=[Task(...)]))
 
         with pytest.raises(DemandAlreadyDecomposedException):
             demand.decompose(FakePlanner(tasks=[]))
 
     def test_should_not_allow_more_than_20_tasks(self):
-        demand = Demand(id=DemandId.generate(), description="Mega projeto")
+        demand = Demand(id=DemandId.generate(), description="Large project")
         for i in range(20):
             demand.add_task(Task(...))
 
@@ -45,7 +64,7 @@ class TestDemand:
             demand.add_task(Task(...))
 ```
 
-## Testes Unitários — Value Objects
+### Step 3: Write Unit Tests for Value Objects
 
 ```python
 class TestComplianceScore:
@@ -62,7 +81,7 @@ class TestComplianceScore:
             ComplianceScore(150.0)
 ```
 
-## Testes de Integração — Repositórios
+### Step 4: Write Integration Tests for Repositories
 
 ```python
 # tests/infrastructure/test_pg_demand_repository.py
@@ -84,12 +103,74 @@ class TestPgDemandRepository:
         assert found.description == "Test"
 ```
 
-## Naming
-
+### Step 5: Run Tests with Coverage
+
+```bash
+# Python with Pytest
+pytest --cov=src --cov-report=html --cov-fail-under=80
+pytest tests/domain/ -v          # Unit tests only
+pytest tests/infrastructure/ -v  # Integration tests only
+
+# Java with Maven
+./mvnw test                                    # All tests
+./mvnw test -Dtest="*DomainTest"              # Domain tests only
+./mvnw test -Dtest="*RepositoryIT"            # Repository integration tests
+./mvnw test -Dtest="*ResourceIT"              # API integration tests
+./mvnw verify -Pcoverage                       # With coverage report
+
+# Angular
+npm test                        # Unit tests
+npm run test -- --code-coverage # With coverage
+npm run e2e                     # End-to-end tests
 ```
-test_should_<resultado>_when_<condição>
 
-test_should_return_error_when_email_is_invalid
-test_should_decompose_demand_when_status_is_created
-test_should_reject_merge_when_conflicts_exist
+### Step 6: Review Coverage Report
+
+```bash
+# Python
+open htmlcov/index.html
+
+# Java (JaCoCo)
+open target/site/jacoco/index.html
+
+# Angular
+open coverage/index.html
 ```
+
+## Resources
+- `references/test-naming.md` - Test naming conventions and patterns
+
+## Examples
+### Example 1: Test a New Entity
+User asks: "Write tests for the Demand entity"
+Response approach:
+1. Test happy path: create, decompose, complete
+2. Test invariants: max tasks, status transitions
+3. Test edge cases: empty description, null values
+4. Use `test_should_<result>_when_<condition>` naming
+5. Run `pytest tests/domain/test_demand.py -v`
+
+### Example 2: Test a Repository
+User asks: "Write integration tests for the DemandRepository"
+Response approach:
+1. Set up test database fixture with rollback
+2. Test save and find operations
+3. Test query methods (findByStatus, etc.)
+4. Test not-found scenarios
+5. Run `pytest tests/infrastructure/ -v`
+
+### Example 3: Improve Test Coverage
+User asks: "Our coverage is at 60%, we need 80%"
+Response approach:
+1. Run `pytest --cov=src --cov-report=html` to see uncovered lines
+2. Identify untested domain logic (highest priority)
+3. Write tests for uncovered business rules first
+4. Then cover integration points
+5. Verify with `pytest --cov-fail-under=80`
+
+## Notes
+- Test naming convention: `test_should_<result>_when_<condition>`
+- Domain tests should have ZERO infrastructure dependencies
+- Integration tests should use rollback to avoid polluting the database
+- Minimum coverage target: 80% for business logic
+- Use fakes/stubs for domain tests, real implementations for integration tests

package/templates/bundle-jhipster-monorepo/skills/testing-strategy/references/test-naming.md

@@ -0,0 +1,55 @@
+# Test Naming Conventions
+
+## Pattern
+```
+test_should_<expected_result>_when_<condition>
+```
+
+## Examples
+```
+test_should_return_error_when_email_is_invalid
+test_should_decompose_demand_when_status_is_created
+test_should_reject_merge_when_conflicts_exist
+test_should_allocate_agent_when_team_has_capacity
+test_should_raise_exception_when_score_exceeds_100
+test_should_complete_demand_when_all_tasks_done
+```
+
+## Java/JUnit Equivalent
+```java
+@Test
+void shouldReturnErrorWhenEmailIsInvalid() { ... }
+
+@Test
+void shouldDecomposeDemandWhenStatusIsCreated() { ... }
+```
+
+## Test Structure (AAA Pattern)
+```python
+def test_should_decompose_new_demand(self):
+    # Arrange
+    demand = Demand(id=DemandId.generate(), description="Create CRUD")
+    planner = FakePlanner(tasks=[Task(...), Task(...)])
+
+    # Act
+    tasks = demand.decompose(planner)
+
+    # Assert
+    assert len(tasks) == 2
+    assert demand.status == DemandStatus.PLANNED
+```
+
+## Test Categories
+| Category | Location | Dependencies | Speed |
+|---|---|---|---|
+| Unit (Domain) | tests/domain/ | None | Fast |
+| Unit (Application) | tests/application/ | Mocked | Fast |
+| Integration | tests/infrastructure/ | DB, Kafka | Medium |
+| API/Controller | tests/api/ | Full stack | Medium |
+| E2E | tests/e2e/ | Full system | Slow |
+
+## Coverage Targets
+- Domain logic: 90%+
+- Application layer: 80%+
+- Infrastructure: 70%+
+- Overall minimum: 80%