maestro-bundle 1.3.1 → 1.4.0

package/templates/bundle-jhipster-microservices/skills/jhipster-gateway/SKILL.md

@@ -1,15 +1,31 @@
 ---
 name: jhipster-gateway
-description: Configurar o JHipster Gateway com Spring Cloud Gateway, roteamento, rate limiting e frontend Angular. Use quando precisar configurar rotas do gateway, load balancing, ou CORS entre serviços.
+description: Configure the JHipster Gateway with Spring Cloud Gateway, routing, rate limiting, CORS, and frontend Angular. Use when configuring gateway routes, load balancing, rate limiting, or CORS between services.
+version: 1.0.0
+author: Maestro
 ---
 
 # JHipster Gateway
 
-## O que é
+Configure and manage the JHipster Gateway as the single entry point for microservices, handling routing, rate limiting, CORS, and serving the Angular frontend.
 
-O Gateway é o ponto de entrada único. Ele roteia requests para os microsserviços, serve o frontend Angular e gerencia autenticação.
+## When to Use
+- When configuring routes to backend microservices
+- When setting up rate limiting on API endpoints
+- When configuring CORS for cross-origin requests
+- When checking health/status of backend services
+- When debugging routing issues
 
-## Roteamento
+## Available Operations
+1. Configure service routes with load balancing
+2. Add rate limiting per route
+3. Configure CORS policies
+4. Monitor service health via actuator
+5. Add custom gateway filters
+
+## Multi-Step Workflow
+
+### Step 1: Configure Routes
 
 ```yaml
 # application.yml
@@ -33,7 +49,7 @@ spring:
         - TokenRelay
 ```
 
-## Rate Limiting no Gateway
+### Step 2: Add Rate Limiting
 
 ```yaml
 spring:
@@ -63,7 +79,7 @@ public KeyResolver userKeyResolver() {
 }
 ```
 
-## CORS
+### Step 3: Configure CORS
 
 ```java
 @Bean
@@ -80,7 +96,7 @@ public CorsWebFilter corsFilter() {
 }
 ```
 
-## Health check dos serviços
+### Step 4: Enable Health Monitoring
 
 ```yaml
 management:
@@ -93,4 +109,60 @@ management:
       enabled: true
 ```
 
-Acessar `GET /actuator/gateway/routes` para ver rotas ativas.
+```bash
+# View active routes
+curl http://localhost:8080/actuator/gateway/routes
+
+# Check service health
+curl http://localhost:8080/actuator/health
+```
+
+### Step 5: Build and Verify
+
+```bash
+# Build gateway
+./mvnw compile
+
+# Run gateway
+./mvnw spring-boot:run
+
+# Verify routing works
+curl http://localhost:8080/api/demands
+curl http://localhost:8080/api/agents
+
+# Run tests
+./mvnw test
+```
+
+## Resources
+- `references/gateway-config.md` - Gateway routing and filter configuration reference
+
+## Examples
+### Example 1: Add a New Service Route
+User asks: "Route /api/bundles to the new bundle-service"
+Response approach:
+1. Add route entry in `application.yml` with `lb://bundle-service` URI
+2. Add path predicate for `/api/bundles/**`
+3. Restart gateway and verify with `curl http://localhost:8080/api/bundles`
+
+### Example 2: Add Rate Limiting
+User asks: "Limit the demands API to 10 requests per second"
+Response approach:
+1. Add `RequestRateLimiter` filter to the demand-service route
+2. Configure `replenishRate` and `burstCapacity`
+3. Add `KeyResolver` bean for user-based limiting
+4. Test with load tool or rapid curl requests
+
+### Example 3: Debug Routing Issues
+User asks: "Requests to /api/agents return 404"
+Response approach:
+1. Check `curl http://localhost:8080/actuator/gateway/routes` for the route
+2. Verify agent-service is registered in Consul/Eureka
+3. Check agent-service health: `curl http://localhost:8080/actuator/health`
+4. Review gateway logs for routing errors
+
+## Notes
+- The Gateway is the single entry point -- all client traffic goes through it
+- `lb://` prefix enables load-balanced routing via service discovery
+- `TokenRelay` filter forwards OAuth2 tokens to downstream services
+- Frontend Angular app is served by the Gateway

package/templates/bundle-jhipster-microservices/skills/jhipster-gateway/references/gateway-config.md

@@ -0,0 +1,43 @@
+# Gateway Configuration Reference
+
+## Route Configuration
+```yaml
+spring:
+  cloud:
+    gateway:
+      routes:
+        - id: service-name          # Unique route ID
+          uri: lb://service-name    # Load-balanced URI via discovery
+          predicates:
+            - Path=/api/resource/** # Path matching
+          filters:
+            - TokenRelay            # Forward OAuth2 token
+```
+
+## Built-in Filters
+| Filter | Purpose |
+|---|---|
+| `TokenRelay` | Forward OAuth2 token to downstream |
+| `RequestRateLimiter` | Rate limit requests |
+| `CircuitBreaker` | Circuit breaker pattern |
+| `Retry` | Retry failed requests |
+| `StripPrefix` | Remove path prefix |
+| `AddRequestHeader` | Add header to request |
+
+## Rate Limiting
+```yaml
+filters:
+  - name: RequestRateLimiter
+    args:
+      redis-rate-limiter.replenishRate: 10   # Requests per second
+      redis-rate-limiter.burstCapacity: 20   # Max burst
+      key-resolver: "#{@userKeyResolver}"    # Key resolver bean
+```
+
+## Useful Endpoints
+```bash
+GET /actuator/gateway/routes       # List all routes
+GET /actuator/health               # Service health
+GET /actuator/gateway/globalfilters # Global filters
+GET /actuator/gateway/routefilters  # Route filters
+```

package/templates/bundle-jhipster-microservices/skills/jhipster-kafka/SKILL.md

@@ -1,11 +1,31 @@
 ---
 name: jhipster-kafka
-description: Configurar Apache Kafka no JHipster para comunicação assíncrona entre microsserviços com eventos de domínio. Use quando precisar de messaging, eventos entre serviços, ou processamento assíncrono.
+description: Configure Apache Kafka in JHipster for asynchronous communication between microservices with domain events. Use when setting up messaging, event-driven communication, producers, consumers, or dead letter queues.
+version: 1.0.0
+author: Maestro
 ---
 
-# Kafka no JHipster Microservices
+# Kafka in JHipster Microservices
 
-## Setup
+Configure Apache Kafka for asynchronous event-driven communication between JHipster microservices using domain events, producers, consumers, and dead letter queues.
+
+## When to Use
+- When setting up asynchronous messaging between services
+- When implementing domain events (DemandCreated, TaskCompleted, etc.)
+- When creating Kafka producers and consumers
+- When configuring dead letter queues for failed messages
+- When designing event schemas
+
+## Available Operations
+1. Set up Kafka with Docker Compose
+2. Define domain events as Java records
+3. Create Kafka producers
+4. Create idempotent consumers
+5. Configure dead letter queues
+
+## Multi-Step Workflow
+
+### Step 1: Start Kafka with Docker Compose
 
 ```yaml
 # docker-compose/kafka.yml
@@ -29,26 +49,37 @@ services:
       KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
 ```
 
-## Tópicos por domínio
+```bash
+# Start Kafka
+docker-compose -f docker-compose/kafka.yml up -d
+
+# Verify Kafka is running
+docker-compose logs kafka | tail -5
+
+# List topics
+docker exec -it kafka kafka-topics --list --bootstrap-server localhost:29092
+```
+
+### Step 2: Design Topics by Bounded Context
 
-| Tópico | Producer | Consumer | Evento |
+| Topic | Producer | Consumer | Events |
 |---|---|---|---|
 | `demand-events` | demand-service | agent-service, tracking-service | DemandCreated, DemandDecomposed |
 | `agent-events` | agent-service | demand-service, tracking-service | AgentAllocated, TaskCompleted |
 | `bundle-events` | bundle-service | agent-service | BundleUpdated, SkillAdded |
 | `tracking-events` | tracking-service | gateway (WebSocket) | MetricsUpdated |
 
-## Eventos de domínio
+### Step 3: Define Domain Events
 
 ```java
-// Evento base
-public sealed interface DomainEvent permits DemandCreated, DemandDecomposed, TaskCompleted {
+// Events are immutable records with eventId and timestamp
+public sealed interface DomainEvent
+    permits DemandCreated, DemandDecomposed, TaskCompleted {
     String eventId();
     Instant occurredAt();
     String aggregateId();
 }
 
-// Eventos específicos
 public record DemandCreated(
     String eventId,
     Instant occurredAt,
@@ -68,7 +99,7 @@ public record TaskCompleted(
 ) implements DomainEvent {}
 ```
 
-## Producer
+### Step 4: Create Producer
 
 ```java
 @Service
@@ -83,7 +114,8 @@ public class DemandEventProducer {
                 if (ex != null) {
                     log.error("Failed to publish event {}", event.eventId(), ex);
                 } else {
-                    log.info("Published {} to partition {}", event.eventId(),
+                    log.info("Published {} to partition {}",
+                        event.eventId(),
                         result.getRecordMetadata().partition());
                 }
             });
@@ -91,7 +123,7 @@ public class DemandEventProducer {
 }
 ```
 
-## Consumer com idempotência
+### Step 5: Create Idempotent Consumer
 
 ```java
 @Service
@@ -103,7 +135,7 @@ public class DemandEventConsumer {
 
     @KafkaListener(topics = "demand-events", groupId = "agent-service")
     public void onDemandEvent(DomainEvent event) {
-        // Idempotência: ignorar evento já processado
+        // Idempotency: skip already processed events
         if (processedEventRepo.existsById(event.eventId())) {
             log.info("Event {} already processed, skipping", event.eventId());
             return;
@@ -112,7 +144,7 @@ public class DemandEventConsumer {
         switch (event) {
             case DemandDecomposed e -> allocationService.allocateForDemand(e);
             case DemandCreated e -> log.info("Demand created: {}", e.aggregateId());
-            default -> log.warn("Unknown event type: {}", event.getClass().getSimpleName());
+            default -> log.warn("Unknown event type: {}", event.getClass());
         }
 
         processedEventRepo.save(new ProcessedEvent(event.eventId(), Instant.now()));
@@ -120,9 +152,10 @@ public class DemandEventConsumer {
 }
 ```
 
-## Dead Letter Queue
+### Step 6: Configure Dead Letter Queue
 
 ```yaml
+# application.yml
 spring:
   cloud:
     stream:
@@ -135,11 +168,71 @@ spring:
               autoCommitOnError: false
 ```
 
-## Regras
+### Step 7: Verify and Monitor
+
+```bash
+# List topics
+docker exec kafka kafka-topics --list --bootstrap-server localhost:29092
+
+# Consume from a topic (for debugging)
+docker exec kafka kafka-console-consumer \
+  --bootstrap-server localhost:29092 \
+  --topic demand-events \
+  --from-beginning
+
+# Check consumer group lag
+docker exec kafka kafka-consumer-groups \
+  --bootstrap-server localhost:29092 \
+  --group agent-service \
+  --describe
+
+# Check DLQ for failed messages
+docker exec kafka kafka-console-consumer \
+  --bootstrap-server localhost:29092 \
+  --topic demand-events-dlq \
+  --from-beginning
+
+# Run tests
+./mvnw test -Dtest="*EventProducer*,*EventConsumer*"
+```
 
-- Um tópico por bounded context (não por entidade)
-- Consumers DEVEM ser idempotentes
-- DLQ para eventos que falharam
-- Events são imutáveis (records)
-- Incluir `eventId` e `occurredAt` em todo evento
-- Consumer group = nome do serviço
+## Resources
+- `references/kafka-patterns.md` - Kafka messaging patterns and best practices
+- `references/event-schema.md` - Domain event schema conventions
+
+## Examples
+
+### Example 1: Add New Event Type
+User asks: "Create a TaskCompleted event"
+Response approach:
+1. Create `TaskCompleted` record implementing `DomainEvent`
+2. Add to sealed interface permits list
+3. Publish from agent-service when task completes
+4. Add consumer in demand-service to update demand status
+5. Run `./mvnw test`
+
+### Example 2: Debug Missing Events
+User asks: "Consumers are not receiving events"
+Response approach:
+1. Check Kafka is running: `docker-compose logs kafka`
+2. Verify topic exists: `kafka-topics --list`
+3. Check consumer group: `kafka-consumer-groups --describe`
+4. Produce test message: `kafka-console-producer`
+5. Check DLQ for errors
+
+### Example 3: Handle Duplicate Events
+User asks: "Consumer is processing the same event twice"
+Response approach:
+1. Add `ProcessedEvent` entity and repository
+2. Check `processedEventRepo.existsById(eventId)` before processing
+3. Save event ID after successful processing
+4. Test with duplicate messages
+
+## Notes
+- One topic per bounded context (not per entity)
+- Consumers MUST be idempotent (same event can arrive 2x)
+- DLQ for events that failed processing
+- Events are immutable (Java records)
+- Always include `eventId` and `occurredAt` in every event
+- Consumer group = service name
+- Use `aggregateId` as Kafka message key for ordering

package/templates/bundle-jhipster-microservices/skills/jhipster-kafka/references/kafka-events.md

@@ -0,0 +1,39 @@
+# Kafka Event Design Patterns
+
+## Event Structure
+```java
+public sealed interface DomainEvent {
+    String eventId();       // Unique ID for idempotency
+    Instant occurredAt();   // When it happened
+    String aggregateId();   // For partitioning
+}
+```
+
+## Topic Naming
+- One topic per bounded context
+- Format: `<context>-events` (e.g., `demand-events`, `agent-events`)
+- DLQ: `<topic>-dlq` (e.g., `demand-events-dlq`)
+
+## Consumer Group Naming
+- Group = service name (e.g., `agent-service`)
+- Each service gets its own group for independent consumption
+
+## Idempotency Pattern
+```java
+if (processedEventRepo.existsById(event.eventId())) return;
+// process event
+processedEventRepo.save(new ProcessedEvent(event.eventId(), Instant.now()));
+```
+
+## Error Handling
+1. Retry (automatic, configurable)
+2. Dead Letter Queue (after max retries)
+3. Monitor DLQ for failed events
+4. Manual replay from DLQ after fixing
+
+## Monitoring Commands
+```bash
+kafka-topics --list --bootstrap-server localhost:9092
+kafka-consumer-groups --describe --group <group> --bootstrap-server localhost:9092
+kafka-console-consumer --topic <topic> --from-beginning --bootstrap-server localhost:9092
+```

package/templates/bundle-jhipster-microservices/skills/jhipster-registry/SKILL.md

@@ -1,14 +1,34 @@
 ---
 name: jhipster-registry
-description: Configurar service discovery com JHipster Registry (Consul ou Eureka) e configuração centralizada. Use quando precisar registrar serviços, configurar discovery, ou centralizar configurações.
+description: Configure service discovery with Consul or Eureka and centralized configuration. Use when registering services, configuring discovery, centralizing configuration, or troubleshooting service registration.
+version: 1.0.0
+author: Maestro
 ---
 
 # JHipster Registry / Service Discovery
 
-## Consul (recomendado)
+Configure and manage service discovery using Consul (recommended) for automatic service registration, health checks, and centralized configuration.
+
+## When to Use
+- When setting up service discovery for new microservices
+- When configuring centralized application properties
+- When troubleshooting service registration issues
+- When setting up Feign clients for inter-service communication
+- When configuring health checks
+
+## Available Operations
+1. Set up Consul with Docker Compose
+2. Configure service registration in each microservice
+3. Store shared configuration in Consul KV
+4. Set up Feign clients with service discovery
+5. Monitor service health
+
+## Multi-Step Workflow
+
+### Step 1: Start Consul with Docker Compose
 
-### Docker Compose
 ```yaml
+# docker-compose/consul.yml
 consul:
   image: consul:1.15
   ports:
@@ -16,9 +36,21 @@ consul:
   command: agent -server -bootstrap -ui -client=0.0.0.0
 ```
 
-### Configuração no serviço
+```bash
+docker-compose -f docker-compose/consul.yml up -d
+
+# Verify Consul is running
+curl http://localhost:8500/v1/status/leader
+
+# Open Consul UI
+# http://localhost:8500
+```
+
+### Step 2: Configure Service Registration
+
+Add to each microservice's `application.yml`:
+
 ```yaml
-# application.yml de cada microsserviço
 spring:
   cloud:
     consul:
@@ -35,12 +67,10 @@ spring:
         default-context: application
 ```
 
-### Configuração centralizada no Consul
-
-Colocar configs compartilhadas no Consul KV store:
+### Step 3: Store Shared Configuration in Consul KV
 
 ```yaml
-# config/application/data no Consul KV
+# config/application/data in Consul KV store
 spring:
   datasource:
     type: com.zaxxer.hikari.HikariDataSource
@@ -54,30 +84,69 @@ management:
         include: health,info,prometheus
 ```
 
-## Service-to-Service communication
+```bash
+# Add config to Consul KV via CLI
+consul kv put config/application/data @shared-config.yml
+
+# Or via HTTP API
+curl -X PUT -d @shared-config.yml http://localhost:8500/v1/kv/config/application/data
+```
 
-Cada serviço se registra automaticamente. Para chamar outro serviço:
+### Step 4: Set Up Feign Clients
 
 ```java
-// Feign Client com discovery
+// Feign Client uses service discovery automatically
 @FeignClient(name = "agent-service")
 public interface AgentServiceClient {
     @GetMapping("/api/agents/{id}")
     AgentDTO getAgent(@PathVariable Long id);
 }
-
-// O nome "agent-service" é resolvido via Consul/Eureka
+// The name "agent-service" is resolved via Consul
 ```
 
-## Health checks
+### Step 5: Verify Service Registration
 
-- Consul verifica `/management/health` de cada serviço
-- Se um serviço ficar unhealthy, Consul remove do registry
-- Gateway para de rotear para instâncias unhealthy automaticamente
+```bash
+# List registered services
+curl http://localhost:8500/v1/catalog/services
 
-## Regras
+# Check specific service instances
+curl http://localhost:8500/v1/health/service/demand-service
+
+# Check service health in Consul UI
+# http://localhost:8500/ui/dc1/services
+```
 
-- Todo serviço DEVE se registrar no discovery
-- Health check endpoint DEVE responder em < 1s
-- Usar `instance-id` com random para permitir múltiplas instâncias
-- Configs compartilhadas no Consul KV, específicas no application.yml local
+## Resources
+- `references/consul-config.md` - Consul configuration and KV store reference
+
+## Examples
+### Example 1: Register a New Service
+User asks: "Register the new bundle-service with Consul"
+Response approach:
+1. Add Consul discovery config to `application.yml`
+2. Set `spring.application.name: bundle-service`
+3. Configure health check path
+4. Start the service and verify in Consul UI
+
+### Example 2: Add Shared Configuration
+User asks: "Share database pool settings across all services"
+Response approach:
+1. Write shared config YAML
+2. Store in Consul KV under `config/application/data`
+3. Verify services pick up the configuration on restart
+
+### Example 3: Debug Service Not Found
+User asks: "Feign client cannot find agent-service"
+Response approach:
+1. Check Consul UI for the service registration
+2. Verify health check is passing: `curl http://localhost:8500/v1/health/service/agent-service`
+3. Check `spring.cloud.consul` config in the failing service
+4. Review service logs for registration errors
+
+## Notes
+- Every service MUST register with discovery
+- Health check endpoint MUST respond in < 1s
+- Use `instance-id` with random value for multiple instances
+- Shared configs in Consul KV, service-specific in local `application.yml`
+- Gateway stops routing to unhealthy instances automatically

package/templates/bundle-jhipster-microservices/skills/jhipster-registry/references/consul-config.md

@@ -0,0 +1,61 @@
+# Consul Configuration Reference
+
+## Service Registration
+```yaml
+spring:
+  cloud:
+    consul:
+      host: consul
+      port: 8500
+      discovery:
+        service-name: ${spring.application.name}
+        health-check-path: /management/health
+        health-check-interval: 15s
+        instance-id: ${spring.application.name}:${random.value}
+```
+
+## Centralized Config
+```yaml
+spring:
+  cloud:
+    consul:
+      config:
+        enabled: true
+        format: yaml
+        default-context: application  # Shared config key prefix
+```
+
+## KV Store Paths
+| Path | Scope |
+|---|---|
+| `config/application/data` | Shared by all services |
+| `config/demand-service/data` | Specific to demand-service |
+| `config/agent-service/data` | Specific to agent-service |
+
+## CLI Commands
+```bash
+# List services
+consul catalog services
+
+# Check service health
+consul catalog nodes -service=demand-service
+
+# Put KV data
+consul kv put config/application/data @config.yml
+
+# Get KV data
+consul kv get config/application/data
+```
+
+## HTTP API
+```bash
+# List services
+curl http://localhost:8500/v1/catalog/services
+
+# Service health
+curl http://localhost:8500/v1/health/service/demand-service
+
+# KV operations
+curl -X PUT -d @config.yml http://localhost:8500/v1/kv/config/application/data
+curl http://localhost:8500/v1/kv/config/application/data?raw
+```