@ronaldjdevfs/forge 1.2.0 → 1.3.1

package/skills/forge/reference/idempotency.md

@@ -0,0 +1,283 @@
+# Idempotency — Operaciones Seguras para Retry
+
+En sistemas distribuidos, las operaciones fallan. Los clientes reintentan. Sin idempotencia, un reintento puede crear facturas duplicadas, cargar dos veces la misma tarjeta o enviar un email dos veces. La idempotencia garantiza que N intentos producen el mismo resultado que uno.
+
+---
+
+## Definición
+
+Una operación es **idempotente** si ejecutarla una o varias veces produce el mismo efecto secundario.
+
+```ts
+GET /orders/123       → idempotente (natural, no cambia estado)
+PUT /orders/123       → idempotente (el mismo body produce el mismo estado final)
+DELETE /orders/123    → idempotente (borrar algo ya borrado no cambia nada)
+POST /orders          → NO es idempotente (crea un recurso nuevo cada vez)
+PATCH /orders/123     → NO es idempotente por defecto (depende del delta)
+```
+
+Para hacer POST y PATCH idempotentes se necesita un **idempotency key**.
+
+---
+
+## Idempotency Keys en APIs
+
+El cliente envía una clave única en el header `Idempotency-Key`. El servidor:
+1. Si la clave es nueva: ejecuta la operación, guarda la respuesta, la retorna
+2. Si la clave ya existe: retorna la respuesta guardada sin ejecutar la operación
+
+### Implementación
+
+```ts
+// Platform middleware
+// platform/http/middleware/IdempotencyMiddleware.ts
+export class IdempotencyMiddleware {
+  constructor(
+    private readonly idempotencyRepo: IIdempotencyRepository,
+    private readonly clock: IClock,
+  ) {}
+
+  async handle(req: Request, res: Response, next: NextFunction): Promise<void> {
+    // Solo para métodos mutantes
+    if (!["POST", "PATCH", "PUT"].includes(req.method)) return next();
+
+    const key = req.headers["idempotency-key"] as string;
+    if (!key) {
+      // POST sin key es válido pero no tiene protección de idempotencia
+      // Para operaciones críticas (pagos), debería ser obligatorio
+      return next();
+    }
+
+    // Validar formato UUID
+    if (!this.isValidUUID(key)) {
+      return res.status(400).json({
+        error: "Invalid idempotency key format. Must be a UUID v4.",
+      });
+    }
+
+    const existing = await this.idempotencyRepo.find(key);
+    if (existing) {
+      // Clave ya usada → devolver respuesta en caché
+      // Si la clave expiró, rechazar con 422
+      if (existing.isExpired(this.clock)) {
+        return res.status(422).json({
+          error: "Idempotency key expired. Use a new key.",
+        });
+      }
+      return res.status(existing.statusCode).json(existing.responseBody);
+    }
+
+    // Registrar clave antes de ejecutar (protege contra duplicados simultáneos)
+    await this.idempotencyRepo.save(IdempotencyEntry.pending(key, req));
+
+    // Ejecutar y guardar respuesta
+    res.on("finish", async () => {
+      await this.idempotencyRepo.save(
+        IdempotencyEntry.completed(key, res.statusCode, res.body),
+      );
+    });
+
+    next();
+  }
+}
+```
+
+### Repositorio de idempotencia
+
+```ts
+// infra/redis/IdempotencyRepository.ts
+export class RedisIdempotencyRepository implements IIdempotencyRepository {
+  private readonly TTL_SECONDS = 60 * 60 * 24; // 24 horas
+
+  constructor(private readonly redis: Redis) {}
+
+  async find(key: string): Promise<IdempotencyEntry | null> {
+    const data = await this.redis.get(`idempotency:${key}`);
+    if (!data) return null;
+    return IdempotencyEntry.fromJSON(data);
+  }
+
+  async save(entry: IdempotencyEntry): Promise<void> {
+    await this.redis.set(
+      `idempotency:${entry.key}`,
+      entry.toJSON(),
+      "EX",
+      this.TTL_SECONDS,
+    );
+  }
+}
+```
+
+### Contract en shared/
+
+```ts
+// shared/contracts/http/IIdempotencyRepository.ts
+export interface IIdempotencyRepository {
+  find(key: string): Promise<IdempotencyEntry | null>;
+  save(entry: IdempotencyEntry): Promise<void>;
+}
+```
+
+### Reglas del Idempotency Key
+
+1. **Generado por el cliente** (nunca por el servidor): el cliente necesita poder reintentar sin haber recibido respuesta
+2. **Formato UUID v4**: único, no secuencial, sin colisiones
+3. **TTL**: 24 horas típicamente. Si el cliente reintenta después del TTL, la clave expiró y debe generar una nueva
+4. **Único por recurso/operación**: un mismo key no debe reusarse para operaciones distintas
+5. **Protección de concurrencia**: dos requests simultáneos con el mismo key deben producir exactamente una ejecución (lock optimista en Redis)
+
+---
+
+## Idempotencia en Eventos
+
+Los consumidores de eventos deben deduplicar por event ID para garantizar exactly-once processing.
+
+```ts
+// base consumer pattern
+export abstract class IdempotentEventConsumer<T extends DomainEvent> {
+  constructor(
+    protected readonly processedEvents: IProcessedEventRepository,
+  ) {}
+
+  async handle(event: T): Promise<void> {
+    // 1. Deduplicación
+    const alreadyProcessed = await this.processedEvents.exists(event.eventId);
+    if (alreadyProcessed) return;
+
+    // 2. Ejecutar lógica de negocio
+    await this.processEvent(event);
+
+    // 3. Marcar como procesado (idealmente en la misma transacción)
+    await this.processedEvents.markProcessed(event.eventId);
+  }
+
+  protected abstract processEvent(event: T): Promise<void>;
+}
+```
+
+```ts
+// Implementación concreta
+export class OrderPlacedHandler extends IdempotentEventConsumer<OrderPlacedEvent> {
+  constructor(
+    processedEvents: IProcessedEventRepository,
+    private readonly inventoryService: IInventoryService,
+  ) {
+    super(processedEvents);
+  }
+
+  protected async processEvent(event: OrderPlacedEvent): Promise<void> {
+    await this.inventoryService.reserveStock(event.orderId, event.items);
+  }
+}
+```
+
+### Tabla de eventos procesados
+
+```sql
+CREATE TABLE IF NOT EXISTS public.processed_events (
+  event_id      VARCHAR(255) PRIMARY KEY,
+  consumer_name VARCHAR(255) NOT NULL,
+  processed_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Cleanup periódico: eventos procesados > 7 días
+CREATE INDEX idx_processed_events_cleanup ON public.processed_events (processed_at);
+```
+
+---
+
+## Idempotencia Natural por Operación
+
+| Operación HTTP | Idempotencia natural | Cómo hacerla idempotente |
+|---|---|---|
+| **GET** | ✅ Sí | Nada. Es idempotente por definición. |
+| **PUT** | ✅ Sí | Mismo body → mismo estado. |
+| **DELETE** | ✅ Sí | Borrar algo ya borrado no cambia estado. |
+| **POST** | ❌ No | Idempotency-Key header. |
+| **PATCH** | ❌ No | Idempotency-Key header + operaciones basadas en estado (ej. "set status = X" es idempotente, "increment count" no lo es). |
+
+### Operaciones condicionalmente idempotentes
+
+```ts
+// ❌ NO idempotente: el resultado cambia cada vez
+PATCH /orders/123 { "action": "addItem", "productId": "abc" }
+
+// ✅ Idempotente: el resultado es el mismo estado final
+PUT /orders/123 { "items": ["abc", "def"] }
+
+// ✅ Condicionalmente idempotente con idempotency key
+POST /orders/123/items
+Idempotency-Key: uuid-abc-123
+Body: { "productId": "abc", "quantity": 1 }
+```
+
+---
+
+## Implementación en el Modelo de Forge
+
+### Estructura
+
+```
+src/platform/
+  http/
+    middleware/
+      IdempotencyMiddleware.ts    ← middleware que intercepta requests
+    contracts/
+      IIdempotencyRepository.ts   ← interfaz en shared/
+
+src/infra/
+  redis/
+    IdempotencyRepository.ts      ← implementación con Redis
+
+src/features/<name>/
+  adapters/
+    in/
+      events/
+        <Name>Handler.ts          ← consumer con deduplicación
+    out/
+      persistence/
+        ProcessedEventRepository.ts ← tabla processed_events
+```
+
+### Reglas de ubicación
+
+| Componente | Capa | Razón |
+|---|---|---|
+| Middleware HTTP | platform/ | Es infraestructura transversal |
+| Interfaz IIdempotencyRepository | shared/contracts/ | Contrato puro sin implementación |
+| Implementación Redis | infra/ | Implementación concreta |
+| IdempotencyKey generación | Cliente (frontend/CLI) | El cliente necesita la clave antes del request |
+| Deduplicación en consumidores | feature/adapters/in/events/ | Específico del feature |
+
+---
+
+## Anti-patrones
+
+| Anti-patrón | Problema | Solución |
+|---|---|---|
+| **Idempotency sin expiración** | Las claves se acumulan infinitamente. | TTL obligatorio (24h típico). Configurable por operación. |
+| **Claves generadas por el servidor** | El servidor genera la key y la devuelve. Si la respuesta se pierde, el cliente no puede reintentar. | El cliente genera la key (UUID v4). El servidor solo la valida. |
+| **Idempotencia en GET** | GET debe ser idempotente por definición. Si no lo es, el problema es otro (efectos secundarios en GET). | No añadir idempotency keys a GET. Mover efectos secundarios a POST/PUT. |
+| **Mutex como idempotencia** | Bloquear el recurso en vez de deduplicar la operación. | Idempotencia no es locking. La clave permite deduplicar sin bloquear. |
+| **Idempotency key corta** | Claves predecibles (incrementales, timestamp). Un cliente puede adivinar claves de otros. | UUID v4 obligatorio. No secuencial. No predecible. |
+| **No verificar método** | El middleware aplica a GET también, añadiendo latencia innecesaria. | Solo POST, PATCH, PUT. GET pasa sin verificar. |
+
+---
+
+## Conexión con Forge
+
+| Comando | Acción |
+|---|---|
+| `forge cast` | Incluir idempotency middleware + repo Redis en features críticas |
+| `forge quench` | Regla detect: feature con POST sin idempotency key |
+| `forge inspect` | Reporta endpoints sin protección de idempotencia |
+| `forge api` | Verifica que los contratos OpenAPI incluyen idempotency-key header |
+| `forge temper` | Endurece DI del middleware de idempotencia |
+
+## Ver también
+
+- `reference/transactional-outbox.md` — deduplicación en relayer
+- `reference/api-design.md` — idempotency-key header en APIs
+- `reference/events.md` — handlers idempotentes
+- `reference/sagas.md` — retry seguro en sagas

package/skills/forge/reference/inscribe.md

@@ -127,3 +127,8 @@ Genera y mantiene el archivo `ARCHITECTURE.md` del proyecto.
 - Se actualiza automáticamente después de cada comando
 - No editar manualmente los campos auto-detectados
 - Forge preserva cualquier sección adicional que el usuario agregue
+
+## Ver también
+
+- `reference/adr.md` — Architecture Decision Records como insumo para ARCHITECTURE.md
+- `reference/principles.md` — principios arquitectónicos documentados en ARCHITECTURE.md

package/skills/forge/reference/inspect.md

@@ -55,4 +55,10 @@ Inspecciona la conformidad arquitectónica del proyecto.
 node .opencode/skills/forge/scripts/inspect.mjs
 node .opencode/skills/forge/scripts/inspect.mjs --json
 node .opencode/skills/forge/scripts/detect.mjs --severity ERROR
+
+## Ver también
+
+- `reference/evolutionary-architecture.md` — fitness functions como complemento al inspect
+- `reference/assay.md` — interpretación cualitativa multi-persona del reporte de inspect
+- `reference/principles.md` — principios contra los que inspect evalúa el proyecto
 ```

package/skills/forge/reference/modular-monolith.md

@@ -0,0 +1,252 @@
+# Modular Monolith
+
+No todo proyecto necesita microservicios. El modular monolith es el punto óptimo para la mayoría de los equipos: la modularidad de features de Forge con la simplicidad operativa de un solo deploy.
+
+---
+
+## Espectro Monolith → Modular → Microservices
+
+```
+Monolith clásico          Modular Monolith              Microservicios
+┌──────────────────┐    ┌──────────────────┐    ┌──┐ ┌──┐ ┌──┐ ┌──┐
+│ Todo en una capa │    │ ┌─┐ ┌─┐ ┌─┐ ┌─┐│    │F1│ │F2│ │F3│ │F4│
+│ Sin boundaries   │    │ │F1│ │F2│ │F3│ │F4││    └──┘ └──┘ └──┘ └──┘
+│ BD compartida    │    │ └─┘ └─┘ └─┘ └─┘│    BD separadas
+│ Sin features     │    │ Platform/Shared/Infra      │    APIs síncronas
+└──────────────────┘    └──────────────────┘    │    Eventos asíncronos
+                                                    │    Deploy independiente
+                                                    └───────────────────────────
+```
+
+| Aspecto | Monolith clásico | Modular Monolith | Microservicios |
+|---|---|---|---|
+| **Boundaries** | No existen | Features con R8-R9 | Servicios independientes |
+| **Comunicación** | Llamadas directas | Inyección de interfaces + eventos | HTTP/gRPC + eventos |
+| **Deploy** | Todo junto | Todo junto | Independiente |
+| **BD** | Compartida | Schemas separados por feature | BD independiente |
+| **Equipo** | 1 equipo | 1-2 equipos | 3+ equipos |
+| **Forge** | No aplica | Modelo nativo | Modelo nativo + split |
+| **Escala** | < 20 features | < 40 features | Sin límite |
+
+El modular monolith NO es un monolith clásico. La diferencia son los **boundaries explícitos**: cada feature respeta R8 (no imports directos) y R9 (no ciclos), igual que en microservicios, pero todo corre en el mismo proceso.
+
+---
+
+## Marco de Decisión
+
+### Cuándo mantener Modular Monolith
+
+| Condición | Señal |
+|---|---|
+| Equipo pequeño (< 8 personas) | Un solo equipo puede mantener todas las features |
+| Dominio cohesionado | Los bounded contexts están estrechamente relacionados |
+| Latencia crítica | El overhead de red de microservicios es inaceptable |
+| Fase inicial | El dominio no está lo suficientemente entendido para partir |
+| Baja carga operativa | Sin equipo de infraestructura dedicado |
+| Deploy semanal/mensual | La velocidad de deploy no es el cuello de botella |
+
+### Cuándo considerar partir a microservicios
+
+| Señal | Síntoma |
+|---|---|
+| **Team scaling** | Dos equipos distintos modifican la misma feature frecuentemente |
+| **Deployment bottleneck** | Un cambio en una feature requiere validar todo el monolith |
+| **Boundaries maduros** | Los bounded contexts están estables y bien definidos |
+| **Failure isolation** | Una feature con alta criticidad (ej. pagos) arrastra a las demás en fallos |
+| **Diferentes características** | Una feature necesita escalar distinto (ej. Search vs Catalog) |
+| **Stack divergence** | Una feature se beneficiaría de un stack tecnológico distinto |
+
+### Contra-señales (no partir)
+
+| Falsa señal | Realidad |
+|---|---|
+| "Es lo moderno" | Microservicios son una decisión de negocio, no técnica |
+| "Escalabilidad" | El cuello de botella suele ser BD, no el monolith |
+| "Equipos autónomos" | Sin boundaries bien definidos, los microservicios serán un distributed monolith |
+| "Rendimiento" | El overhead de red puede empeorar la latencia |
+| "Está de moda" | Moda tecnológica no justifica la complejidad operativa |
+
+---
+
+## Arquitectura Interna del Modular Monolith
+
+### Comunicación entre features
+
+En el modular monolith, la comunicación entre features sigue exactamente las mismas reglas que en microservicios:
+
+```ts
+// ✅ Permitido: inyección de interfaz desde shared
+// src/features/orders/application/use-cases/PlaceOrderUseCase.ts
+import { IInventoryService } from "src/shared/contracts/catalog";
+import { IUnitOfWork } from "src/shared/contracts/data";
+
+// ❌ Prohibido: import directo a otra feature (R8)
+import { StockEntity } from "src/features/inventory/domain/StockEntity";
+
+// ❌ Prohibido: import directo a infra de otra feature (R1 + R8)
+import { prisma } from "src/features/inventory/adapters/out/persistence/prisma";
+```
+
+### Shared Kernel
+
+```ts
+// src/shared/contracts/catalog/IInventoryService.ts
+export interface IInventoryService {
+  reserveStock(orderId: string, items: LineItem[]): Promise<ReservationResult>;
+  releaseStock(reservationId: string): Promise<void>;
+}
+
+// Los DTOs de los contratos viven junto a la interfaz
+export type ReservationResult = {
+  success: boolean;
+  reservationId?: string;
+  insufficientItems: { sku: string; available: number }[];
+};
+```
+
+La implementación se inyecta en tiempo de construcción:
+
+```ts
+// src/features/inventory/adapters/out/shared/InventoryService.ts
+export class InventoryServiceImpl implements IInventoryService {
+  constructor(private readonly stockRepo: IStockRepository) {}
+  // implementación real que la feature Inventory expone al Shared Kernel
+}
+```
+
+### Base de datos
+
+En el modular monolith, cada feature tiene su propio schema dentro de la misma BD:
+
+```sql
+-- Schema por feature, misma base de datos
+CREATE SCHEMA IF NOT EXISTS orders;
+CREATE SCHEMA IF NOT EXISTS catalog;
+CREATE SCHEMA IF NOT EXISTS inventory;
+
+CREATE TABLE orders.orders ( … );
+CREATE TABLE catalog.products ( … );
+CREATE TABLE inventory.stock ( … );
+
+-- No existen foreign keys entre schemas de distintas features
+-- La integridad referencial se maneja en la aplicación, no en la BD
+```
+
+En Prisma esto se configura con `schema` por modelo:
+
+```prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+  schemas  = ["orders", "catalog", "inventory"]
+}
+
+model Order {
+  id        String @id @default(uuid())
+  // ...
+  @@schema("orders")
+}
+
+model Product {
+  id        String @id @default(uuid())
+  // ...
+  @@schema("catalog")
+}
+```
+
+### Eventos dentro del monolith
+
+Dentro del modular monolith, los eventos pueden ser sincrónicos (in-process event bus) o asíncronos (message broker):
+
+```ts
+// Sincrónico: EventBus in-process, sin serialización
+// platform/events/EventBus.ts
+export interface IEventBus {
+  publish(event: DomainEvent): Promise<void>;
+  subscribe<T extends DomainEvent>(eventType: string, handler: (event: T) => Promise<void>): void;
+}
+
+// Uso en feature
+// orders/application/use-cases/PlaceOrderUseCase.ts
+await this.eventBus.publish(new OrderPlacedEvent(order));
+// inventory/adapters/in/events/OrderPlacedHandler.ts
+eventBus.subscribe("OrderPlaced", async (event) => {
+  await this.stockService.reserveStock(event.orderId, event.items);
+});
+```
+
+**Regla: dentro del monolith, puedes elegir síncrono o asíncrono.** Pero si planeas partir a microservicios en el futuro, usa asíncrono desde el día 1 (message broker). La migración será solo cambiar la URL del broker.
+
+---
+
+## Integración con Forge
+
+| Elemento | Modular Monolith | Microservicios |
+|---|---|---|
+| **Reglas R1-R9** | Se aplican igual | Se aplican igual |
+| **Contratos en shared/** | Interfaces + DTOs | Mismos contratos (packages publicados) |
+| **Eventos** | In-process o broker | Broker siempre |
+| **Platform** | Monolítica, compartida | Por servicio o shared library |
+| **Infra** | Schemas separados en misma BD | BD independientes |
+| **Deploy** | Un solo artefacto | N artefactos |
+| **forge cast** | Crea feature en el monolith | Crea feature + esqueleto de servicio |
+| **forge inspect** | Auditoría normal | Auditoría + health check distribuido |
+| **forge relocate** | Extraer feature del monolith | Dividir servicio o fusionar |
+
+### Transición guiada: Modular Monolith → Microservicios
+
+```
+Fase 1: Asegurar boundaries
+  - Verificar que R8 y R9 se cumplen
+  - shared/contracts/ debe contener todas las interfaces entre features
+  - Schemas separados por feature
+
+Fase 2: Extraer eventos
+  - Migrar de event bus in-process a broker (RabbitMQ, Kafka)
+  - Verificar que los handlers de eventos son idempotentes
+
+Fase 3: Extraer feature como servicio
+  1. forge relocate extrae la feature a un nuevo repo
+  2. La feature origen ahora inyecta un cliente HTTP/gRPC en vez de la impl directa
+  3. El contrato en shared/ se convierte en API contract
+  4. Los eventos viajan por el broker existente
+
+Fase 4: Iterar
+  - Repetir Fase 3 para cada feature que se beneficie de partir
+  - Dejar las demás en el monolith
+```
+
+---
+
+## Anti-patrones
+
+| Anti-patrón | Problema | Solución |
+|---|---|---|
+| **Distributed Monolith** | Microservicios que se llaman sincrónicamente en cadena. Si un servicio falla, todos fallan. | Usar eventos asíncronos entre servicios. Si la latencia lo exige sincrónico, reconsiderar si deberían ser un solo servicio. |
+| **Shared Database (microservices)** | Microservicios que comparten BD. Los boundaries son ficticios. | Migrar a schemas separados o BD independientes. Empezar con schemas si el split es futuro. |
+| **Nano-services** | Microservicio por entidad. Cada servicio es un CRUD sin lógica. | Fusionar en features por dominio de negocio. El overhead de operar N servicios pequeños es mayor que el beneficio. |
+| **Premature splitting** | Partir antes de entender los bounded contexts. | Esperar a que los contexts estén estables. El monolith modular permite partir sin reescribir. |
+| **Monolith con carpetas** | Solo hay separación por carpetas, no por boundaries. Cualquier código importa cualquier otro. | Implementar R8 y R9. Si duele, significa que los boundaries están mal diseñados o no existen. |
+
+---
+
+## Conexión con Forge
+
+| Comando | Acción |
+|---|---|
+| `forge cast` | Crea feature en el monolith modular con boundaries correctos |
+| `forge inspect` | Verifica que los boundaries entre features son saludables |
+| `forge relocate` | Extrae una feature del monolith a un servicio independiente |
+| `forge reforge` | Rediseña boundaries mal definidos dentro del monolith |
+| `forge graph` | Visualiza dependencias entre features; identifica candidatos a partir |
+
+## Ver también
+
+- `reference/bounded-contexts.md` — contexts como módulos del monolith
+- `reference/anti-corruption-layer.md` — ACL entre módulos
+- `reference/sagas.md` — coordinación entre módulos
+- `reference/events.md` — comunicación asíncrona entre módulos

package/skills/forge/reference/observability.md

@@ -64,3 +64,8 @@ export interface IHealthCheck {
 - Tracing distribuido con baggage contextual
 - Health checks sin autenticación (solo para orquestadores)
 - Alertas basadas en métricas, no en logs
+
+## Ver también
+
+- `reference/security-patterns.md` — audit logging como práctica de seguridad
+- `reference/testing-patterns.md` — tests de instrumentación y health checks

package/skills/forge/reference/quench.md

@@ -71,4 +71,9 @@ node .opencode/skills/forge/scripts/detect.mjs --severity ERROR
 
 # Solo un tipo específico
 node .opencode/skills/forge/scripts/detect.mjs --type layers
+
+## Ver también
+
+- `reference/evolutionary-architecture.md` — fitness functions como validación continua
+- `reference/hooks.md` — integración de quench en pre-commit hook
 ```

package/skills/forge/reference/relocate.md

@@ -49,3 +49,9 @@ El backup se almacena en `.forge/backups/<target>--<timestamp>/` y preserva la e
 | Feature | `src/application/use-cases/<name>/` | `src/features/<name>/` |
 | Shared | `src/utils/`, `src/helpers/`, `src/lib/` | `src/shared/<name>/` |
 | Infra | `src/database/`, `src/providers/` | `src/infra/<name>/` |
+
+## Ver también
+
+- `reference/anti-corruption-layer.md` — aislamiento de legacy durante migración
+- `reference/modular-monolith.md` — decisión de estructura al migrar features
+- `reference/reforge.md` — refactor post-migración