eva4j 1.0.14 → 1.0.16

package/src/skills/build-system-yaml/references/module-spec.md

@@ -0,0 +1,367 @@
+# Especificaciones de documentación del sistema
+
+Referencia para generar `system/system.md` y `system/{module}.md`.
+
+---
+
+## Parte 1 — system.md (especificación narrativa global)
+
+### Ubicación: `system/system.md`
+
+Especificación técnica narrativa del sistema completo. Una sección `##` por cada módulo con subsecciones detalladas.
+
+### Estructura obligatoria
+
+```markdown
+# system.md — Technical Specification
+
+## {module-name}
+
+### Module Role
+[3–5 detailed paragraphs]
+- What business problem it solves and what entities/concepts it manages
+- Its exclusive responsibilities (bounded context boundaries)
+- What is NOT this module's responsibility
+- How it collaborates with other modules
+- Business invariants it protects
+
+### Use Cases
+[One `####` section per useCase in exposes: and consumers[].useCase]
+
+#### {UseCaseName}
+**What it does:** [detailed business logic description]
+**Preconditions:** [required state, entities that must exist]
+**Postconditions:** [system state after successful execution]
+**Validations and errors:** [exception conditions and error types]
+**Events emitted:** [DomainEvent name and trigger condition, or "none"]
+
+### Exposed Endpoints
+[One `####` per endpoint in exposes:]
+
+#### {METHOD} {/path}
+**Purpose:** [endpoint description and usage context]
+**Path params / Query params:** [each parameter described]
+**Request body:** [expected fields, types, validation constraints]
+**Response:** [returned fields and their business meaning]
+**Errors:** [HTTP status codes and when they occur]
+
+### Emitted Events
+[Only if module is producer in integrations.async]
+
+#### {EventName}
+**When:** [exact business condition that fires the event]
+**Payload:** [event fields with description]
+**Consumers and their actions:**
+- `{module}` → `{useCase}`: [what the consumer does]
+
+### Ports (outbound sync calls)
+[Only if module is caller in integrations.sync]
+
+#### {PortName} → {target-module}
+**When called:** [in which use case and under what condition]
+**Endpoints used:** [METHOD /path list]
+**Data obtained and how it's used:** [detailed description]
+```
+
+### Reglas del system.md
+
+- **Ser SUMAMENTE específico**: estados de entidades, validaciones concretas, campos relevantes. Nunca "gestiona los datos".
+- **Flujos de extremo a extremo**: si `ConfirmReservation` es disparado por `PaymentApprovedEvent`, explicarlo en ambas secciones.
+- **Incluir useCases de consumers** como casos de uso del módulo consumidor.
+- **Referenciar módulos por nombre**.
+- **Máquinas de estado** cuando hay ciclos de vida.
+- Omitir secciones no aplicables.
+
+---
+
+## Parte 2 — {module}.md (especificación técnica por módulo)
+
+### Ubicación: `system/{module-name}.md`
+
+Especificación completa e independiente para cada módulo. Un desarrollador puede leerla sin conocer el sistema completo.
+
+### Estructura obligatoria
+
+```markdown
+# {module-name} — Technical Specification
+
+## Module Role
+[3–5 VERY detailed paragraphs]
+- What business problem it solves and what entities/concepts it manages
+- Exclusive responsibilities (bounded context boundaries)
+- What is NOT this module's responsibility
+- How it collaborates with other modules
+
+## Invariants
+
+> Invariants are conditions that must be **always true** within this bounded context.
+> Violating an invariant is a **critical business error** that must throw an exception.
+
+| ID | Invariant | Violation consequence |
+|----|-----------|----------------------|
+| INV-01 | [condition] | [exception / what it prevents] |
+| INV-02 | ... | ... |
+
+> Each use case must verify relevant invariants **before** persisting changes.
+
+## State Machine
+[ONLY if the module manages entity lifecycle — omit otherwise]
+
+```mermaid
+stateDiagram-v2
+    [*] --> INITIAL_STATE
+    INITIAL_STATE --> NEXT_STATE : event / action
+    NEXT_STATE --> FINAL_STATE : event / action
+    FINAL_STATE --> [*]
+```
+
+> Transition restrictions: [explain forbidden transitions — these are implicit state machine invariants]
+
+## Interaction Diagram
+
+> Shows the complete flow: what arrives at the module (HTTP or async event),
+> which use case executes, and what event is emitted.
+
+```mermaid
+flowchart TD
+    subgraph HTTP["REST Endpoints"]
+        EP1["METHOD /path"]
+    end
+
+    subgraph ASYNC_IN["Incoming Events"]
+        EI1["📥 EventName"]
+    end
+
+    subgraph USE_CASES["Use Cases"]
+        UC1["UseCaseName"]
+    end
+
+    subgraph EVENTS_OUT["Emitted Events"]
+        EO1["📤 EmittedEventName"]
+    end
+
+    EP1 --> UC1
+    EI1 --> UC2["AnotherUseCase"]
+    UC1 --> EO1
+    UC2 -->|"no event"| FIN([end])
+```
+
+> Node conventions:
+> - HTTP endpoints → rectangles with method and path
+> - Incoming events → `📥` prefix
+> - Use cases → rectangles with handler name
+> - Emitted events → `📤` prefix
+> - No output event → connect to FIN([end])
+> - Omit ASYNC_IN if no events consumed; omit EVENTS_OUT if no events produced
+
+## Sequence Diagram
+[Chronological interactions between actors and components for main flows.
+One diagram per complex flow or flow with significant branching.]
+
+```mermaid
+sequenceDiagram
+    actor Client as Client
+    participant API as REST API
+    participant Handler as CommandHandler
+    participant Domain as Domain Entity
+    participant Repo as Repository
+    participant Broker as Message Broker
+    participant ExtSvc as External Service
+
+    Client->>API: POST /resource {payload}
+    API->>Handler: CreateResourceCommand
+    Handler->>Repo: findById(id)
+    Repo-->>Handler: entity (or 404)
+    Handler->>Domain: businessMethod()
+    Domain-->>Handler: updated entity
+    Handler->>Repo: save(entity)
+    Handler->>Broker: publish(ResourceCreatedEvent)
+    Broker-->>Handler: ack
+    Handler-->>API: resourceId
+    API-->>Client: 201 Created {resourceId}
+```
+
+> Actor conventions:
+> - `actor Client` → human users or external systems initiating the flow
+> - `participant API` → module REST controller
+> - `participant Handler` → CommandHandler / QueryHandler
+> - `participant Domain` → domain entity (include when business logic is relevant)
+> - `participant Repo` → repository abstraction
+> - `participant Broker` → message broker — omit if no events
+> - `participant ExtSvc` → external service via ports — use real port name
+> - Sync responses: `-->>` (dotted line with arrow)
+> - Async messages: `--)` (dotted line without immediate return)
+> - One diagram per main flow; skip trivial read-only flows
+
+## Use Cases
+[One `###` per useCase in exposes: and consumers[].useCase]
+
+### {UseCaseName}
+**Type:** `HTTP` | `Incoming Event` (specify which)
+**What it does:** [detailed business logic description]
+**Preconditions:** [valid states, entities that must exist]
+**Postconditions:** [system state after successful execution]
+**Invariants verified:** [ID list — e.g., INV-01, INV-03]
+**Validations and errors:** [exception conditions, error type, HTTP status]
+**Events emitted:** [DomainEvent name and condition, or "none"]
+
+**Flow diagram:**
+```mermaid
+flowchart TD
+    IN["🔵 Trigger: METHOD /path · or EventName"] --> UC["⚙️ {UseCaseName}"]
+    UC --> INV{"Check invariants"}
+    INV -->|"violated"| ERR[/"Exception / Error Response"/]
+    INV -->|"passed"| BIZ["Execute business logic"]
+    BIZ --> SAVE["Persist changes"]
+    SAVE -->|"if applicable"| EV["📤 DomainEvent emitted"]
+    SAVE -->|"no event"| FIN([end])
+```
+> Adapt to real flow: include relevant business nodes and branching.
+
+## Exposed Endpoints
+[Only if module has exposes: entries]
+
+### {METHOD} {/path}
+**Use case:** `{UseCase}`
+**Purpose:** [description]
+**Path params / Query params:** [each parameter]
+**Request body:** [fields, types, validations]
+**Response:** [fields and business meaning]
+**Errors:** [HTTP status codes and conditions]
+
+## Emitted Events
+[Only if module is producer in integrations.async]
+
+### {EventName}
+**When:** [exact business condition]
+**Payload:** [fields with description]
+**Consumers and their actions:**
+- `{module}` → `{useCase}`: [what consumer does]
+
+## Ports (outbound sync calls)
+[Only if module is caller in integrations.sync]
+
+### {PortName} → {target-module}
+**When called:** [in which use case and condition]
+**Endpoints used:** [METHOD /path list]
+**Data obtained and how it's used:** [detailed description]
+```
+
+---
+
+### Reglas de los archivos de módulo
+
+- **Todo en inglés**: títulos, secciones, descripciones, invariantes, use cases.
+- **INVARIANTES obligatorias**: al menos 2–3 por módulo. Analizar unicidad, estados válidos, rangos, precondiciones de transición.
+- **Diagrama de interacciones obligatorio**: todos los endpoints y eventos entrantes. Sin entradas → nodo `[[passive module]]`.
+- **Diagrama de secuencia obligatorio**: al menos un `sequenceDiagram` cubriendo el happy path. Diagramas adicionales para bifurcaciones (error, compensación). Modelar todos los actores reales.
+- **Diagrama de flujo por caso de uso**: `flowchart TD` dentro de cada `### {UseCase}` con trigger, invariantes, lógica y eventos.
+- **Máquina de estados condicional**: solo si hay entidades con ciclo de vida. Restricciones de transición son invariantes implícitas.
+- **Referenciar invariantes** en cada caso de uso (INV-01, INV-02...).
+- **No duplicar** system.md — el `.md` del módulo es la especificación completa.
+- Archivos en `system/{module-name}.md`.
+
+---
+
+### Ejemplo condensado — `system/payments.md`
+
+```markdown
+# payments — Technical Specification
+
+## Module Role
+
+The `payments` module is solely responsible for the lifecycle of payments linked
+to reservations. It manages communication with the external payment gateway,
+records each transaction's state, and decides when to emit events that trigger
+changes in other modules. It has no knowledge of reservation logic or notifications.
+
+Confirming reservations and sending notifications are NOT this module's responsibility;
+those flows are initiated by events that payments emits.
+
+## Invariants
+
+| ID | Invariant | Violation consequence |
+|----|-----------|----------------------|
+| INV-01 | Only one active payment (PENDING or APPROVED) per reservation at any time | Throws `409 Conflict` — prevents double charging |
+| INV-02 | A CANCELLED or FAILED payment cannot transition to APPROVED | Throws `InvalidStateTransitionException` |
+| INV-03 | Payment amount must be > 0 | Throws `400 Bad Request` |
+| INV-04 | A payment can only be refunded if in APPROVED state | Throws `409 Conflict` |
+
+## State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> PENDING : CreatePayment
+    PENDING --> APPROVED : ApprovePayment (gateway confirms)
+    PENDING --> FAILED : FailPayment (gateway rejects)
+    APPROVED --> REFUNDED : RefundPayment
+    FAILED --> [*]
+    REFUNDED --> [*]
+```
+
+> Restrictions: CANCELLED and FAILED are terminal states (INV-02). Only APPROVED can transition to REFUNDED (INV-04).
+
+## Interaction Diagram
+
+```mermaid
+flowchart TD
+    subgraph HTTP["REST Endpoints"]
+        EP1["POST /payments"]
+        EP2["GET /payments/{id}"]
+        EP3["POST /payments/{id}/refund"]
+    end
+
+    subgraph ASYNC_IN["Incoming Events"]
+        EI1["📥 ReservationCreatedEvent"]
+    end
+
+    subgraph USE_CASES["Use Cases"]
+        UC1["CreatePayment"]
+        UC2["GetPayment"]
+        UC3["RefundPayment"]
+        UC4["HandleReservationCreated"]
+    end
+
+    subgraph EVENTS_OUT["Emitted Events"]
+        EO1["📤 PaymentApprovedEvent"]
+        EO2["📤 PaymentFailedEvent"]
+        EO3["📤 PaymentRefundedEvent"]
+    end
+
+    EP1 --> UC1
+    EP2 --> UC2
+    EP3 --> UC3
+    EI1 --> UC4
+    UC4 --> UC1
+    UC1 --> EO1
+    UC1 --> EO2
+    UC3 --> EO3
+    UC2 -->|"read-only"| FIN([end])
+```
+
+## Use Cases
+
+### HandleReservationCreated
+**Type:** Incoming Event (`ReservationCreatedEvent`)
+**What it does:** Extracts `reservationId` and `totalAmount` from payload and triggers
+`CreatePayment` internally to start charging automatically.
+**Preconditions:** Payload contains valid `reservationId` and `totalAmount > 0`.
+**Postconditions:** Payment created in PENDING state.
+**Invariants verified:** INV-01, INV-03
+**Validations and errors:** If INV-01 violated (active payment exists), discard event
+and log warning. If `totalAmount ≤ 0`, throw `400`.
+**Events emitted:** none directly; approval arrives asynchronously.
+
+**Flow diagram:**
+```mermaid
+flowchart TD
+    IN["📥 ReservationCreatedEvent"] --> UC["⚙️ HandleReservationCreated"]
+    UC --> INV1{"INV-01: active payment?"}
+    INV1 -->|"Yes"| WARN[/"warn — discard event"/]
+    INV1 -->|"No"| INV2{"INV-03: amount > 0?"}
+    INV2 -->|"No"| ERR[/"400 Bad Request"/]
+    INV2 -->|"Yes"| CREATE["Create Payment PENDING"]
+    CREATE --> SAVE["Persist Payment"]
+    SAVE --> FIN([end — approval arrives async])
+```
+```

package/src/skills/build-system-yaml/references/system-yaml-spec.md

@@ -0,0 +1,178 @@
+# system.yaml — Especificación completa
+
+Referencia técnica para construir y validar el archivo `system/system.yaml`.
+
+---
+
+## Estructura completa
+
+```yaml
+system:
+  name: project-name              # kebab-case
+  groupId: com.example
+  javaVersion: 21
+  springBootVersion: 3.5.5
+  database: postgresql             # h2 | postgresql | mysql
+
+messaging:                         # Omitir sección completa si no hay mensajería
+  enabled: true
+  broker: kafka                    # kafka | rabbitmq | sns-sqs (solo kafka soportado hoy)
+  kafka:
+    bootstrapServers: localhost:9092
+    defaultGroupId: project-name
+    topicPrefix: project-name      # opcional — prefixa todos los topics
+
+modules:
+  - name: orders                   # plural, kebab-case
+    description: "Order lifecycle management"
+    exposes:
+      - method: GET                # GET | POST | PUT | PATCH | DELETE
+        path: /orders/{id}
+        useCase: GetOrder          # PascalCase — alimenta endpoints: en domain.yaml
+        description: "Get order by ID"
+      - method: GET
+        path: /orders
+        useCase: FindAllOrders
+        description: "List orders with filters and pagination"
+      - method: POST
+        path: /orders
+        useCase: CreateOrder
+        description: "Create a new order"
+      - method: PUT
+        path: /orders/{id}/confirm
+        useCase: ConfirmOrder
+        description: "Confirm a pending order"
+
+  - name: notifications
+    description: "Notification delivery service"
+    # Sin endpoints REST — solo consume eventos
+
+integrations:
+  async:
+    - event: OrderPlacedEvent      # PascalCase, tiempo pasado, sufijo Event
+      producer: orders
+      topic: ORDER_PLACED          # SCREAMING_SNAKE_CASE
+      consumers:
+        - module: payments
+          useCase: HandleOrderPlaced   # acción que payments ejecuta
+        - module: notifications
+          useCase: NotifyOrderPlaced   # acción que notifications ejecuta
+
+  sync:
+    - caller: orders               # módulo que hace la llamada
+      calls: customers             # módulo destino
+      port: OrderCustomerService   # PascalCase + Service — prefijado con caller
+      using:
+        - GET /customers/{id}      # debe existir en exposes: de 'customers'
+```
+
+---
+
+## Convenciones de nombres
+
+| Elemento | Convención | Ejemplo válido | Ejemplo inválido |
+|---|---|---|---|
+| Módulos | plural, kebab-case | `orders`, `order-items` | `Order`, `order_items` |
+| Eventos | PascalCase + pasado + sufijo `Event` | `OrderPlacedEvent` | `PlaceOrderEvent` |
+| Topics Kafka | SCREAMING_SNAKE_CASE — **sin `topicPrefix`** | `ORDER_PLACED` | `test-eva.ORDER_PLACED` |
+| Port names | PascalCase + sufijo `Service` — **único por módulo** | `OrderCustomerService` | `CustomerService` (compartido) |
+| useCases | PascalCase, verbo + sustantivo | `CreateOrder`, `FindAllOrders` | `createOrder`, `orders` |
+| `consumers[].useCase` | PascalCase, verbo + sustantivo | `HandleOrderPlaced` | `orderPlaced` |
+
+---
+
+## Restricciones estructurales
+
+- ❌ **Sin dependencias circulares síncronas** — si `A` llama a `B`, `B` no puede llamar a `A`
+- ❌ **Sin campos de dominio** — entidades, campos, enums → van en `domain.yaml`
+- ❌ **Sin nombres de `port` genéricos compartidos** — si `orders` y `deliveries` llaman a `customers`, usar `OrderCustomerService` y `DeliveryCustomerService`; **nunca** `CustomerService` en ambos (causa `ConflictingBeanDefinitionException`)
+- ✅ Cada módulo tiene **una sola responsabilidad**
+- ✅ `calls.using:` solo referencia endpoints declarados en `exposes:` del módulo destino
+- ✅ `consumers[].module` debe existir en `modules:`
+- ✅ Módulos pasivos (notificaciones, auditoría) son **consumidores**, nunca `caller`
+- ℹ️ Varios módulos pueden consumir el mismo evento sin riesgo de colisión de beans
+
+---
+
+## useCases — patrones de nombres
+
+### Verbos por tipo de operación
+
+| Tipo de operación | Verbos recomendados | Ejemplo |
+|---|---|---|
+| Crear recurso | `Create` | `CreateOrder` |
+| Actualizar | `Update` | `UpdateOrder` |
+| Eliminar | `Delete` | `DeleteOrder` |
+| Obtener por ID | `Get` | `GetOrder` |
+| Listar con paginación | `FindAll` | `FindAllOrders` |
+| Transición de estado | `Confirm`, `Cancel`, `Approve`, `Reject`, `Activate`, `Close`, `Complete`, `Submit`, `Publish` | `ConfirmOrder`, `CancelPayment` |
+| Acción puntual | `Send`, `Process`, `Calculate`, `Generate`, `Assign`, `Transfer`, `Notify` | `SendNotification`, `ProcessPayment` |
+| Búsqueda | `Search`, `Find`, `Lookup` | `FindOrdersByCustomer` |
+
+### CRUD vs negocio — regla de generación
+
+eva4j distingue dos categorías:
+
+**CRUD estándar** — genera implementación completa del handler:
+
+| Patrón | HTTP | Implementación |
+|---|---|---|
+| `Create{Aggregate}` | POST `/resource` | Handler completo |
+| `Update{Aggregate}` | PUT `/resource/{id}` | Handler completo |
+| `Delete{Aggregate}` | DELETE `/resource/{id}` | Handler completo |
+| `Get{Aggregate}` | GET `/resource/{id}` | Handler completo |
+| `FindAll{PluralAggregate}` | GET `/resource` | Handler completo |
+
+**Negocio** — genera scaffold con `throw new UnsupportedOperationException(...)`:
+
+```java
+public class ConfirmOrderCommandHandler implements CommandHandler<ConfirmOrderCommand, Void> {
+    @Override
+    public Void handle(ConfirmOrderCommand command) {
+        throw new UnsupportedOperationException("ConfirmOrderCommandHandler not implemented yet");
+    }
+}
+```
+
+### useCase en consumers
+
+Cada `consumers[]` **debe** declarar `useCase`: la acción que el consumidor ejecuta al recibir el evento.
+
+```yaml
+consumers:
+  - module: payments
+    useCase: HandleReservationCreated   # payments inicia cobro
+  - module: notifications
+    useCase: NotifyReservationCreated   # envía email de confirmación
+```
+
+**Reglas:**
+- PascalCase, `Verbo + Sustantivo`
+- Describe la acción del consumidor, no repite el evento
+- Se mapea a `listeners[].useCase` del `domain.yaml` del consumidor
+- Verbos típicos: `Handle`, `Process`, `Confirm`, `Cancel`, `Notify`, `Accumulate`, `Release`, `Update`
+
+---
+
+## Mensajería
+
+- Solo `kafka` está implementado; `rabbitmq` y `sns-sqs` generan warning
+- Los **campos** de eventos NO van en `system.yaml` → se declaran en `domain.yaml → events[].fields`
+- ❌ `listeners[].topic` NUNCA lleva el `topicPrefix` — usar solo nombre base SCREAMING_SNAKE_CASE
+
+---
+
+## Checklist de validación completa
+
+- [ ] Módulos en plural kebab-case
+- [ ] Eventos en tiempo pasado con sufijo `Event`
+- [ ] Topics en SCREAMING_SNAKE_CASE sin topicPrefix
+- [ ] Sin dependencias circulares síncronas
+- [ ] Todos los `consumers[].module` existen en `modules:`
+- [ ] Todos los `consumers[].useCase` presentes y en PascalCase
+- [ ] Todos los `calls.using:` existen en `exposes:` del destino
+- [ ] Módulos pasivos no son `caller`
+- [ ] `useCases` en PascalCase
+- [ ] Port names únicos por módulo (prefijados con bounded context del caller)
+- [ ] Todo el contenido en inglés
+- [ ] Archivo guardado en `system/system.yaml`

package/src/utils/config-manager.js

@@ -151,6 +151,60 @@ class ConfigManager {
 
     return config;
   }
+
+  /**
+   * Persist mock backup data into .eva4j.json so it survives process restarts.
+   * @param {Object} backups - Map of { key: { path, content } }
+   */
+  async saveMockBackup(backups, opts = {}) {
+    const config = await this.loadProjectConfig();
+    if (!config) throw new Error('Project configuration not found.');
+
+    config._mockBackup = {};
+    for (const [key, { path: filePath, content }] of Object.entries(backups)) {
+      config._mockBackup[key] = { path: filePath, content };
+    }
+    config._mockActive = true;
+    if (opts.onlyBroker) {
+      config._mockOnlyBroker = true;
+    }
+    config.updatedAt = new Date().toISOString();
+    await fs.writeJson(this.configFile, config, { spaces: 2 });
+  }
+
+  /**
+   * Read and clear mock backup from .eva4j.json.
+   * @returns {Object|null} backups map or null if no mock backup stored
+   */
+  async popMockBackup() {
+    const config = await this.loadProjectConfig();
+    if (!config || !config._mockBackup) return null;
+
+    const backups = config._mockBackup;
+    delete config._mockBackup;
+    delete config._mockActive;
+    delete config._mockOnlyBroker;
+    config.updatedAt = new Date().toISOString();
+    await fs.writeJson(this.configFile, config, { spaces: 2 });
+    return backups;
+  }
+
+  /**
+   * Returns true if a mock backup is currently stored in .eva4j.json.
+   */
+  async hasMockBackup() {
+    const config = await this.loadProjectConfig();
+    return !!(config && config._mockActive);
+  }
+
+  /**
+   * Returns true if the active mock was started with --only-broker
+   * (i.e. only the broker was swapped, DB config was kept unchanged).
+   */
+  async hasMockOnlyBroker() {
+    const config = await this.loadProjectConfig();
+    return !!(config && config._mockOnlyBroker);
+  }
 }
 
 module.exports = ConfigManager;

package/src/utils/context-builder.js

@@ -30,6 +30,7 @@ function buildBaseContext(answers) {
     dependencyManagementVersion: defaults.dependencyManagementVersion,
     springModulithVersion: defaults.springModulithVersion,
     springCloudVersion: defaults.springCloudVersion,
+    springdocVersion: defaults.springdocVersion,
     gradleVersion: defaults.gradleVersion,
     dependencies: answers.dependencies || [],
     author: answers.author || 'Generated by eva4j',