maestro-bundle 1.3.1 → 1.4.0

package/templates/bundle-jhipster-microservices/skills/jhipster-angular/references/angular-microservices.md

@@ -0,0 +1,40 @@
+# Angular Patterns for Microservices
+
+## Architecture
+- Angular app lives in the Gateway
+- Gateway routes API calls transparently to microservices
+- From Angular's view, it is a single API
+
+## Data Aggregation Pattern
+```typescript
+// Use forkJoin to fetch from multiple services simultaneously
+forkJoin({
+  demands: this.demandService.query(),
+  agents: this.agentService.query(),
+}).subscribe(({ demands, agents }) => {
+  // Combine data
+});
+```
+
+## Resilience Pattern
+```typescript
+// Wrap each service call with catchError
+this.demandService.query().pipe(
+  catchError(() => of([]))  // Return empty on failure
+)
+```
+
+## Real-Time Pattern
+```typescript
+// WebSocket via STOMP through Gateway
+this.stompClient.watch('/topic/events').pipe(
+  map(msg => JSON.parse(msg.body))
+).subscribe(event => { /* handle */ });
+```
+
+## Best Practices
+- Always handle partial failures
+- Show fallback UI when a service is unavailable
+- Use lazy loading for feature modules
+- Keep entity services in `entities/` directory
+- Custom aggregation services outside `entities/`

package/templates/bundle-jhipster-microservices/skills/jhipster-angular/references/angular-structure.md

@@ -0,0 +1,59 @@
+# JHipster Angular Structure Reference
+
+## Directory Layout
+```
+src/main/webapp/app/
+  entities/                    # Generated CRUD per entity
+    <entity>/
+      <entity>.model.ts        # TypeScript interface
+      <entity>.routes.ts       # Lazy-loaded routes
+      service/<entity>.service.ts
+      list/<entity>.component.ts
+      detail/<entity>-detail.component.ts
+      update/<entity>-update.component.ts
+      delete/<entity>-delete-dialog.component.ts
+  shared/                      # Shared modules and components
+    date/                      # Date utilities
+    filter/                    # Filter components
+    pagination/                # Pagination components
+    sort/                      # Sort directives
+  core/                        # Core services
+    auth/                      # Authentication
+    interceptor/               # HTTP interceptors
+    util/                      # Utility services
+  layouts/                     # Page layouts
+    main/                      # Main layout
+    navbar/                    # Navigation bar
+    footer/                    # Footer
+  config/                      # App configuration
+```
+
+## Key Conventions
+- All components are `standalone: true`
+- Use `SharedModule` for common imports
+- Lazy loading for entity routes
+- JHipster's `TranslateService` for i18n
+- `AlertService` for user notifications
+- `SortDirective` and `SortByDirective` for table sorting
+- `PaginationComponent` for paginated lists
+
+## Service Pattern
+```typescript
+@Injectable({ providedIn: 'root' })
+export class EntityService {
+  private resourceUrl = 'api/entities';
+
+  constructor(private http: HttpClient) {}
+
+  query(req?: any): Observable<HttpResponse<IEntity[]>> {
+    const options = createRequestOption(req);
+    return this.http.get<IEntity[]>(this.resourceUrl, { params: options, observe: 'response' });
+  }
+}
+```
+
+## Custom Component Best Practices
+- Place custom components outside `entities/` to avoid regeneration conflicts
+- Mark any changes to generated files with `// CUSTOM` comments
+- Use standalone components with explicit imports
+- Follow JHipster naming: `jhi-` prefix for entity components

package/templates/bundle-jhipster-microservices/skills/jhipster-docker-k8s/SKILL.md

@@ -1,19 +1,42 @@
 ---
 name: jhipster-docker-k8s
-description: Deploy de microsserviços JHipster com Docker Compose (dev) e Kubernetes/K3s (prod). Use quando precisar containerizar serviços JHipster, criar docker-compose, ou fazer deploy em K8s.
+description: Deploy JHipster microservices with Docker Compose for development and Kubernetes/K3s for production. Use when containerizing services, creating docker-compose, deploying to K8s, or scaling services.
+version: 1.0.0
+author: Maestro
 ---
 
-# Docker & Kubernetes para JHipster Microservices
+# Docker & Kubernetes for JHipster Microservices
 
-## Docker Compose — Dev
+Deploy JHipster microservices using Docker Compose for local development and Kubernetes/K3s for production.
+
+## When to Use
+- When setting up local development environment
+- When containerizing a microservice
+- When deploying to Kubernetes/K3s
+- When scaling services
+- When troubleshooting container issues
+
+## Available Operations
+1. Generate Docker Compose with JHipster
+2. Build Docker images with Jib
+3. Generate Kubernetes manifests with JHipster
+4. Deploy to K3s cluster
+5. Scale and manage services
+
+## Multi-Step Workflow
+
+### Step 1: Generate Docker Compose
 
 ```bash
-# Gerar docker-compose via JHipster
+# Generate docker-compose via JHipster (from project root)
 jhipster docker-compose
 
-# Ou usar o gerado pelo JDL deployment
+# Or use JDL deployment block
+jhipster import-jdl jhipster-jdl.jdl
 ```
 
+### Step 2: Configure Docker Compose for Dev
+
 ```yaml
 # docker-compose/docker-compose.yml
 services:
@@ -24,9 +47,6 @@ services:
     environment:
       - SPRING_PROFILES_ACTIVE=dev
       - SPRING_CLOUD_CONSUL_HOST=consul
-    depends_on:
-      - consul
-      - keycloak
 
   demand-service:
     image: demand-service:latest
@@ -46,24 +66,6 @@ services:
       POSTGRES_USER: demand
       POSTGRES_PASSWORD: demand
 
-  agent-service:
-    image: agent-service:latest
-    environment:
-      - SPRING_PROFILES_ACTIVE=dev
-      - SPRING_CLOUD_CONSUL_HOST=consul
-      - SPRING_DATASOURCE_URL=jdbc:postgresql://agent-db:5432/agent
-    depends_on:
-      - agent-db
-      - consul
-      - kafka
-
-  agent-db:
-    image: postgres:16
-    environment:
-      POSTGRES_DB: agent
-      POSTGRES_USER: agent
-      POSTGRES_PASSWORD: agent
-
   consul:
     image: consul:1.15
     ports:
@@ -95,89 +97,121 @@ services:
     environment:
       KEYCLOAK_ADMIN: admin
       KEYCLOAK_ADMIN_PASSWORD: admin
-    command: start-dev --import-realm
-    volumes:
-      - ./keycloak-realm.json:/opt/keycloak/data/import/realm.json
+    command: start-dev
 ```
 
-## Kubernetes — Prod
+### Step 3: Build Docker Images
 
 ```bash
-# Gerar manifests via JHipster
-jhipster kubernetes
-```
+# Build all services with Jib (no Docker daemon)
+./mvnw -ntp verify -DskipTests jib:dockerBuild -Pprod
 
-### Deployment por serviço
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: demand-service
-  namespace: maestro
-spec:
-  replicas: 2
-  selector:
-    matchLabels:
-      app: demand-service
-  template:
-    spec:
-      containers:
-        - name: demand-service
-          image: registry.local/demand-service:1.0.0
-          ports:
-            - containerPort: 8081
-          resources:
-            requests:
-              memory: "512Mi"
-              cpu: "500m"
-            limits:
-              memory: "1Gi"
-              cpu: "1000m"
-          readinessProbe:
-            httpGet:
-              path: /management/health/readiness
-              port: 8081
-            initialDelaySeconds: 30
-          livenessProbe:
-            httpGet:
-              path: /management/health/liveness
-              port: 8081
-            initialDelaySeconds: 60
-          env:
-            - name: SPRING_PROFILES_ACTIVE
-              value: prod
-            - name: SPRING_DATASOURCE_URL
-              valueFrom:
-                secretKeyRef:
-                  name: demand-service-db
-                  key: url
+# Or build specific service
+cd demand-service && ./mvnw -ntp verify -DskipTests jib:dockerBuild
+
+# Tag and push to registry
+docker tag demand-service:latest registry.local/demand-service:1.0.0
+docker push registry.local/demand-service:1.0.0
 ```
 
-## Build de imagens
+### Step 4: Run Locally with Docker Compose
 
 ```bash
-# Build com Jib (padrão JHipster, sem Docker daemon)
-./mvnw -ntp verify -DskipTests jib:dockerBuild -Pprod
+# Start all services
+docker-compose -f docker-compose/docker-compose.yml up -d
+
+# Check status
+docker-compose ps
+
+# View logs of a specific service
+docker-compose logs -f demand-service
+
+# Stop all
+docker-compose down
 
-# Ou com Docker
-docker build -t demand-service:1.0.0 .
+# Stop and remove volumes (clean start)
+docker-compose down -v
 ```
 
-## Comandos úteis
+### Step 5: Generate Kubernetes Manifests
 
 ```bash
-# Dev: subir tudo
-docker-compose -f docker-compose/docker-compose.yml up -d
+# Generate K8s manifests via JHipster
+jhipster kubernetes
 
-# Dev: ver logs de um serviço
-docker-compose logs -f demand-service
+# Or via JDL deployment block
+```
 
-# Prod: deploy
+### Step 6: Deploy to Kubernetes/K3s
+
+```bash
+# Apply all manifests
 kubectl apply -f k8s/
 
-# Prod: rollback
-kubectl rollout undo deployment/demand-service -n maestro
+# Check deployment status
+kubectl get pods -n maestro
+kubectl get svc -n maestro
 
-# Prod: escalar
+# Watch pod logs
+kubectl logs -f deployment/demand-service -n maestro
+
+# Scale a service
 kubectl scale deployment demand-service --replicas=3 -n maestro
+
+# Rollback a deployment
+kubectl rollout undo deployment/demand-service -n maestro
+
+# Check events for troubleshooting
+kubectl get events -n maestro --sort-by=.lastTimestamp
 ```
+
+### Step 7: Verify
+
+```bash
+# Test gateway endpoint
+curl http://localhost:8080/api/demands
+
+# Check Consul UI for registered services
+# http://localhost:8500
+
+# Check Keycloak admin
+# http://localhost:9080
+```
+
+## Resources
+- `references/docker-compose-reference.md` - Docker Compose configuration reference
+- `references/k8s-troubleshooting.md` - Common Kubernetes troubleshooting commands
+
+## Examples
+
+### Example 1: Set Up Dev Environment
+User asks: "Set up the local development environment"
+Response approach:
+1. Run `jhipster docker-compose` to generate files
+2. Run `docker-compose up -d` to start infrastructure
+3. Verify Consul, Kafka, Keycloak are running
+4. Start each service with `./mvnw spring-boot:run`
+
+### Example 2: Deploy to Production
+User asks: "Deploy demand-service to K3s"
+Response approach:
+1. Build image: `./mvnw jib:build -Djib.to.image=registry.local/demand-service:1.0.0`
+2. Update K8s manifest with new image tag
+3. Apply: `kubectl apply -f k8s/demand-service/`
+4. Verify: `kubectl rollout status deployment/demand-service -n maestro`
+
+### Example 3: Service Won't Start
+User asks: "demand-service pod keeps crashing"
+Response approach:
+1. Check pod status: `kubectl describe pod <pod-name> -n maestro`
+2. Check logs: `kubectl logs <pod-name> -n maestro`
+3. Common causes: database not ready, Consul not reachable, missing env vars
+4. Fix and redeploy
+
+## Notes
+- Use Jib for Docker builds (no Docker daemon needed, faster)
+- Never use `latest` tag in production K8s manifests
+- Each service has its own database container in docker-compose
+- Use `docker-compose down -v` for a completely clean restart
+- Set resource limits in K8s manifests (memory, CPU)
+- Add readiness and liveness probes to all deployments

package/templates/bundle-jhipster-microservices/skills/jhipster-docker-k8s/references/docker-k8s-commands.md

@@ -0,0 +1,68 @@
+# Docker and Kubernetes Command Reference
+
+## Docker Compose (Dev)
+```bash
+# Start all services
+docker-compose -f docker-compose/docker-compose.yml up -d
+
+# Stop all services
+docker-compose down
+
+# View logs
+docker-compose logs -f <service-name>
+
+# Rebuild a single service
+docker-compose up -d --build <service-name>
+
+# View running containers
+docker-compose ps
+```
+
+## Image Building
+```bash
+# Jib (no Docker daemon needed)
+./mvnw -ntp verify -DskipTests jib:dockerBuild -Pprod
+
+# Jib push to registry
+./mvnw -ntp verify -DskipTests jib:build -Pprod -Djib.to.image=registry.local/service:tag
+
+# Docker build
+docker build -t service:tag .
+docker push registry.local/service:tag
+```
+
+## Kubernetes (Prod)
+```bash
+# Apply manifests
+kubectl apply -f k8s/
+
+# Check pods
+kubectl get pods -n maestro
+
+# View logs
+kubectl logs -f deployment/<service> -n maestro
+
+# Scale
+kubectl scale deployment <service> --replicas=3 -n maestro
+
+# Rollback
+kubectl rollout undo deployment/<service> -n maestro
+
+# Rollout status
+kubectl rollout status deployment/<service> -n maestro
+
+# Port forward for debugging
+kubectl port-forward svc/<service> 8080:8080 -n maestro
+
+# Execute command in pod
+kubectl exec -it <pod-name> -n maestro -- /bin/sh
+
+# View secrets
+kubectl get secrets -n maestro
+```
+
+## JHipster Generators
+```bash
+jhipster docker-compose   # Generate docker-compose files
+jhipster kubernetes        # Generate K8s manifests
+```

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

@@ -1,15 +1,30 @@
 ---
 name: jhipster-entities
-description: Criar e gerenciar entidades JHipster com JDL para microsserviços, incluindo relações cross-service e DTOs compartilhados. Use quando precisar criar entidades, definir modelo de dados, ou gerar código em microsserviços.
+description: Create and manage JHipster entities with JDL for microservices, including cross-service references and shared DTOs. Use when creating entities, defining data models, or managing cross-service relationships.
+version: 1.0.0
+author: Maestro
 ---
 
-# JHipster Entities — Microservices
+# JHipster Entities -- Microservices
 
-## Regra fundamental
+Create and manage JHipster entities in a microservices architecture where entities belong to specific services and cross-service relationships use IDs instead of foreign keys.
 
-Em microsserviços, **entidades pertencem a um único serviço**. Relacionamentos cross-service usam IDs, não foreign keys.
+## When to Use
+- When creating entities assigned to specific microservices
+- When defining cross-service relationships (by ID, not FK)
+- When generating code with `jhipster import-jdl` for microservices
+- When implementing Feign-based data fetching across services
 
-## JDL com microservice assignment
+## Available Operations
+1. Define entities with microservice assignment in JDL
+2. Handle cross-service references with ID fields
+3. Generate code per microservice
+4. Implement Feign-based data aggregation
+5. Create shared DTOs for inter-service communication
+
+## Multi-Step Workflow
+
+### Step 1: Define Entities with Microservice Assignment
 
 ```jdl
 /* demand-service entities */
@@ -23,7 +38,7 @@ entity Demand {
 entity Task {
     description String required maxlength(500)
     status TaskStatus required
-    agentId Long             // ID do agente (outro serviço), não FK
+    agentId Long             // ID from another service, not FK
     branchName String
 }
 
@@ -42,7 +57,7 @@ entity Agent {
 }
 
 entity AgentTeam {
-    demandId Long required   // ID da demand (outro serviço), não FK
+    demandId Long required   // ID from another service, not FK
 }
 
 relationship ManyToMany {
@@ -52,21 +67,27 @@ relationship ManyToMany {
 microservice Agent, AgentTeam with agentService
 ```
 
-## Comunicação cross-service
+### Step 2: Generate Code
+
+```bash
+# Generate all microservices from JDL
+jhipster import-jdl jhipster-jdl.jdl
+
+# Verify generated files per service
+ls demand-service/src/main/java/*/domain/
+ls agent-service/src/main/java/*/domain/
+```
 
-Quando `Task` referencia `Agent` (outro serviço):
+### Step 3: Implement Cross-Service Data Fetching
 
 ```java
-// NO demand-service — Task.java
+// In demand-service -- Task stores only agentId
 @Entity
 public class Task {
-    // ...
-    private Long agentId;  // Apenas o ID, não a entidade Agent
-
-    // Para obter dados do Agent, chamar agent-service via Feign
+    private Long agentId;  // Just the ID, not the Agent entity
 }
 
-// NO demand-service — DemandService
+// In demand-service -- fetch Agent data via Feign
 @Service
 public class DemandServiceImpl {
     private final AgentServiceClient agentClient;
@@ -79,9 +100,40 @@ public class DemandServiceImpl {
 }
 ```
 
-## Regras
+### Step 4: Build and Test
+
+```bash
+# Build each service
+cd demand-service && ./mvnw test
+cd agent-service && ./mvnw test
+
+# Run all services
+cd demand-service && ./mvnw spring-boot:run &
+cd agent-service && ./mvnw spring-boot:run &
+```
 
-- Entidade pertence a UM serviço
-- Cross-service: guardar apenas o ID, nunca FK real
-- Para exibir dados de outro serviço: Feign Client ou evento Kafka
-- Nunca compartilhar entities entre serviços (duplicar DTOs se necessário)
+## Resources
+- `references/cross-service-entities.md` - Cross-service entity patterns and rules
+
+## Examples
+### Example 1: Create Entities for a New Service
+User asks: "Create Product and Order entities for the order-service"
+Response approach:
+1. Define entities in JDL with `microservice Product, Order with orderService`
+2. Use ID references for entities in other services
+3. Run `jhipster import-jdl`
+4. Verify generated code
+
+### Example 2: Reference an Entity from Another Service
+User asks: "Task needs to show the Agent name but Agent is in another service"
+Response approach:
+1. Store `agentId Long` in Task entity (not FK)
+2. Create Feign client to agent-service
+3. Fetch Agent data when needed via Feign call
+4. Combine into a response DTO
+
+## Notes
+- Fundamental rule: entity belongs to ONE service
+- Cross-service: store only the ID, never a real FK
+- To display data from another service: Feign client or Kafka event
+- Never share entity classes between services (duplicate DTOs if needed)

package/templates/bundle-jhipster-microservices/skills/jhipster-entities/references/cross-service-entities.md

@@ -0,0 +1,36 @@
+# Cross-Service Entity Patterns
+
+## Rules
+1. Each entity belongs to exactly ONE microservice
+2. Cross-service references use plain ID fields (Long/UUID), not foreign keys
+3. Data from other services is fetched via Feign or received via Kafka events
+4. DTOs are duplicated between services, never shared as JARs
+
+## JDL Pattern
+```jdl
+entity Task {
+    agentId Long       // Reference to Agent in agent-service
+    branchName String
+}
+microservice Task with demandService
+
+entity Agent {
+    name String required
+}
+microservice Agent with agentService
+```
+
+## Data Fetching Pattern
+```java
+// Option 1: Feign (synchronous, real-time)
+AgentDTO agent = agentClient.getAgent(task.getAgentId());
+
+// Option 2: Local cache from Kafka events (eventual consistency)
+AgentSummary agent = localAgentCache.get(task.getAgentId());
+```
+
+## Anti-Patterns to Avoid
+- Sharing database between services
+- Using real foreign keys across service boundaries
+- Sharing entity JARs between services
+- Joining tables from different service databases

package/templates/bundle-jhipster-microservices/skills/jhipster-entities/references/jdl-types.md

@@ -0,0 +1,56 @@
+# JDL Types Reference
+
+## Field Types
+| JDL Type | Java | DB | Notes |
+|---|---|---|---|
+| String | String | varchar(255) | Default max 255 |
+| Integer | Integer | integer | 32-bit |
+| Long | Long | bigint | 64-bit |
+| Float | Float | float | Single precision |
+| Double | Double | double | Double precision |
+| BigDecimal | BigDecimal | decimal | Exact precision |
+| Boolean | Boolean | boolean | |
+| LocalDate | LocalDate | date | Date only |
+| Instant | Instant | timestamp | UTC timestamp |
+| ZonedDateTime | ZonedDateTime | timestamp | With timezone |
+| Duration | Duration | bigint | Duration in nanos |
+| UUID | UUID | uuid | Unique identifier |
+| Blob | byte[] | blob | Binary data |
+| AnyBlob | byte[] | blob | Any binary |
+| ImageBlob | byte[] | blob | Image with content type |
+| TextBlob | String | clob | Large text |
+
+## Validations
+| Validation | Applies to | Example |
+|---|---|---|
+| `required` | All | `name String required` |
+| `minlength(n)` | String | `name String minlength(3)` |
+| `maxlength(n)` | String | `name String maxlength(100)` |
+| `min(n)` | Numeric | `price BigDecimal min(0)` |
+| `max(n)` | Numeric | `quantity Integer max(1000)` |
+| `pattern(regex)` | String | `sku String pattern(/^[A-Z]{3}-[0-9]{4}$/)` |
+| `unique` | All | `email String unique` |
+
+## Relationship Types
+```jdl
+relationship OneToMany {
+    Owner{children} to Child{owner(displayField) required}
+}
+relationship ManyToMany {
+    A{bs} to B{as}
+}
+relationship OneToOne {
+    A{b} to B with jpaDerivedIdentifier
+}
+relationship ManyToOne {
+    Child{parent(name)} to Parent
+}
+```
+
+## Enum Definition
+```jdl
+enum Status {
+    ACTIVE("Active"),
+    INACTIVE("Inactive")
+}
+```