agent-mp 0.5.21 → 0.5.22

package/dist/core/engine.js

@@ -1334,204 +1334,254 @@ ESTRUCTURA DE LOS 3 NIVELES
 ================================================================
 
 ────────────────────────────────────────────────────────────────
-NIVEL 0 — architecture.md (raiz de .agent/context/)
-Indice global. Objetivo: 50-150 lineas. Concreto.
 ────────────────────────────────────────────────────────────────
-Secciones obligatorias:
+NIVEL 0 — architecture.md  (raiz de .agent/context/)
+Objetivo: 80-150 lineas. Panorama global real, no generico.
+────────────────────────────────────────────────────────────────
 
-# ${this.config.project} — Arquitectura Global (NIVEL 0)
+# [Nombre del proyecto] — Arquitectura Global (NIVEL 0)
 
-> Indice de servicios y relaciones. Lectura escalonada:
+> Lectura escalonada:
 >   NIVEL 0: este archivo
 >   NIVEL 1: .agent/context/[componente]/architecture.md
 >   NIVEL 2: .agent/context/[componente]/modules/[modulo].md
 
 ## 1. Overview funcional
-2-4 lineas en lenguaje simple: que es el sistema, para quien sirve, que problema resuelve.
+2-4 lineas. Que es el sistema, para quien sirve, que problema resuelve.
+Si hay multiples componentes con roles distintos, nombrarlos y contrastarlos en el overview:
+ej. "X es la API de ingesta (escritura, batch), Y es la API de gestion (CRUD, portal Nexus)."
 
 ## 2. Componentes del proyecto
-| Componente | Tipo | Stack + version | Puerto | Proposito (negocio) | Entry point |
-|------------|------|-----------------|--------|---------------------|-------------|
-(una fila por componente, con datos REALES)
+| Componente | Stack (version exacta) | Puerto | Rol principal | Consumers tipicos |
+|---|---|---|---|---|
+(datos REALES del manifest. "Consumers tipicos" = quien llama a este componente: frontend, proceso batch, sistema externo)
 
 ## 3. Relaciones entre componentes
-| Origen | Destino | Tipo (HTTP / Import / DB / Queue / CORS) | Proposito |
-|--------|---------|------------------------------------------|-----------|
-(una fila por cada relacion confirmada)
+| Origen | Destino | Tipo | Proposito |
+|---|---|---|---|
+(incluir URLs/hosts reales si aparecen en .env o config: ej. "http://57.151.96.13:8000/v1/validate")
 
 ## 4. Diagrama de arquitectura
-\`\`\`
-[Frontend Web] ──HTTP──> [API Auth :8081]
-       │                        │
-       │                        v
-       └──HTTP──> [API Core :8080] ──> [MongoDB]
+Usar box-drawing (┌─┐│└┘┬┴├┤) y flechas (→ ──> ▼ ▲). Mostrar puertos REALES.
+Incluir endpoints clave inline en los componentes cuando se conocen.
+\`\`\`text
+┌─────────────────────┐         ┌──────────────────────┐
+│ componente-a :8083  │         │ componente-b :8084    │
+│ POST /api/sales     │         │ GET /api/nexus/combos │
+│ POST /api/stock     │────────>│ PUT /api/nexus/...    │
+└──────────┬──────────┘         └──────────────────────┘
+           │                               │
+           ▼                               ▼
+    ┌──────────────┐              ┌──────────────┐
+    │  SQL Server  │              │  Auth Service│
+    │  :31434      │              │  :8000       │
+    └──────────────┘              └──────────────┘
 \`\`\`
 
-## 5. Flujos end-to-end principales (3-5)
-Mappings funcional → tecnico, paso a paso. Ejemplo:
-- **"Un usuario crea un pedido"**: WebApp → POST /orders (API Core) → valida JWT contra API Auth → guarda en MongoDB → devuelve 201 con el pedido.
+## 5. Flujos end-to-end principales
+Concretos, con componentes, endpoints y acciones reales. 2-5 flujos.
+- **"Nombre del flujo":** Actor → POST /endpoint (componente-a) → valida JWT con auth-service → escribe en SQL Server → responde 201.
 
-## 6. Prerequisitos para levantar el proyecto
-Versiones REALES leidas de los manifests (no rangos genericos).
+## 6. Prerequisitos para levantar
+Solo lo que es real: acceso de red a hosts externos, herramientas requeridas. Sin generalidades.
 
-## 7. Comandos globales de desarrollo
+## 7. Comandos de desarrollo
 | Comando | Descripcion | Directorio |
-
-## 8. Decisiones de arquitectura globales (opcional, solo si hay)
+|---|---|---|
+(comandos reales del Makefile, run.sh, package.json scripts, mvnw, etc.)
 
 ────────────────────────────────────────────────────────────────
 NIVEL 1 — [componente]/architecture.md
-Detalle del componente. Objetivo: 80-200 lineas. Crear UNO POR CADA componente NO trivial.
+Objetivo: 120-250 lineas. Un archivo por cada componente no trivial.
 ────────────────────────────────────────────────────────────────
-Secciones obligatorias:
 
 # [componente] — Arquitectura (NIVEL 1)
 
 ## Que hace
-2-3 lineas en lenguaje simple, sin tecnicismos.
+Parrafo 1: describe el rol del componente en lenguaje de negocio + quien lo consume.
+Parrafo 2 (si hay componentes hermanos): contrasta con ellos. ej. "A diferencia de X que solo escribe en bulk, esta API expone CRUD con paginacion y filtros para el portal."
 
 ## Casos de uso principales
-3-6 bullets en formato negocio:
-- "Permite al usuario X..."
-- "El sistema usa este servicio para Y..."
+Tabla con: Caso de uso | Actor (quien lo dispara) | Descripcion + endpoint si se conoce.
+| Caso de uso | Actor | Descripcion |
+|---|---|---|
+| Ingesta de ventas | Proceso batch BAT | POST /api/sales — upsert bulk de ventas finales |
+| Consulta de productos | Portal Nexus | GET /api/products?eanCode=XXX |
 
 ## Stack tecnico
 | Item | Valor |
-|------|-------|
-| Lenguaje | TypeScript 5.3 |
-| Framework | NestJS 11.0.1 |
-| ORM | Mongoose 9.3.3 |
-| Auth | Passport JWT |
-(datos reales del manifest)
+|---|---|
+| Lenguaje | Java 21 (Temurin LTS) |
+| Framework | Spring Boot 3.5.6 |
+| ORM | Spring Data JPA + Hibernate |
+| Seguridad | Spring Security 6 + JJWT |
+(versiones REALES del manifest. Si hay librerias clave como POI, MapStruct, HikariCP: incluirlas)
 
 ## Puerto y URLs
-- **Puerto:** 8085 (de PORT en .env)
-- **Swagger / docs:** http://localhost:8085/api/docs (si aplica)
-- **Health check:** GET /health (si existe)
-
-## Estructura interna (arbol real)
-Listar DIRECTORIOS clave + los archivos que leiste (los CONTROLLER/ROUTER y SCHEMA/MODEL del prefetch).
+| Recurso | URL |
+|---|---|
+| API base | http://localhost:8084 |
+| Swagger / docs | http://localhost:8084/swagger-ui/index.html |
+| Perfil activo | development (application-development.properties) |
+
+## Estructura de capas / paquetes
+Arbol con los archivos y directorios REALES que leiste. Usar → para anotar inline que hace cada clase o directorio.
+\`\`\`text
+paquete.raiz/
+├── controller/        → endpoints REST, delegan a service, responden ApiResponse<T>
+│   ├── ClientController     → CRUD /api/clients
+│   ├── SaleController       → POST /api/sales, /api/sales/interim-sales
+│   └── ExportController     → GET /api/export/combos (genera .xlsx)
+├── service/           → interfaces de logica de negocio
+│   └── impl/          → implementaciones (@Transactional aqui)
+├── repository/        → Spring Data JPA Repositories
+├── domain/            → Entidades JPA (@Entity)
+│   ├── Client, InterimClient  → clientes finales y en staging
+│   ├── Sale, InterimSale      → ventas finales y en staging
+│   └── compositekeys/         → @IdClass para PKs compuestas
+├── dto/               → contratos de API (Request/Response DTOs)
+├── mapper/            → MapStruct: Entity ↔ DTO
+├── security/          → filtros JWT, validacion, handler 401
+└── configuration/     → CORS, Swagger, SecurityConfig
 \`\`\`
-src/
-├── main.ts                      # entry point, configura CORS y swagger
-├── auth/
-│   ├── auth.controller.ts       # endpoints /auth/login, /auth/refresh
-│   └── auth.service.ts          # logica de validacion JWT
-├── leads/
-│   ├── leads.controller.ts      # endpoints /leads
-│   └── lead.schema.ts           # modelo Lead { name, email, status }
-└── ...
+(Adaptar a la estructura real del proyecto: puede ser src/, app/, pkg/, etc.)
+
+## Endpoints reales
+SOLO los que se leyeron en los CONTROLLER/ROUTER files. Incluir columna Auth si se conoce.
+| Metodo | Ruta | Auth | Funcion |
+|---|---|---|---|
+| GET | /api/clients | JWT | Lista clientes (paginado, filtrable) |
+| POST | /api/sales | JWT | Upsert bulk de ventas finales |
+| GET | /api/export/combos | JWT/Azure | Descarga Excel con combos |
+(querystring params relevantes en la ruta, ej. ?eanCode= , ?page=&size= )
+
+## Formato de respuesta (si hay wrapper estandar)
+Si el codigo muestra un wrapper comun para todas las respuestas, documentarlo:
+\`\`\`json
+{
+  "status": 200,
+  "message": "Operacion exitosa",
+  "data": [...],
+  "pagination": { "page": 1, "size": 15, "totalElements": 120, "totalPages": 8 }
+}
 \`\`\`
-Para Java, usar el arbol de packages: src/main/java/.../controller/, .../domain/, .../service/, etc.
-Si no se leyo el codigo fuente, mencionar solo los directorios visibles en la estructura de archivos.
+Si no hay wrapper, omitir esta seccion.
 
 ## Modulos internos
-IMPORTANTE: nombrar cada modulo por su FEATURE (clients, sales, products), no por su capa (web, data, service).
-Los modulos surgen de los controllers que se leyeron: un controller → un modulo.
-| Modulo | Proposito (negocio) | Doc tecnica |
-|--------|---------------------|-------------|
-| auth | Login y validacion de tokens | modules/auth.md |
-| leads | Listado y consulta de negocios | modules/leads.md |
-
-## Endpoints principales
-| Metodo | Ruta | Modulo | Que hace (lenguaje simple) |
-|--------|------|--------|----------------------------|
-| GET | /leads | leads | Lista negocios filtrables |
-| GET | /leads/:id | leads | Detalle de un negocio |
-(SOLO endpoints reales extraidos de los controllers — metodo HTTP, ruta, y descripcion en 1 linea)
-
-## Variables de entorno
-| Variable | Default | Proposito |
-|----------|---------|-----------|
-| PORT | 8085 | Puerto del servicio |
-| MONGODB_URI | mongodb://... | Conexion principal |
-
-## Integraciones con otros servicios / sistemas
-| Servicio externo | Tipo (HTTP/DB/Queue) | Proposito |
+| Modulo | Proposito | Doc tecnica |
+|---|---|---|
+| seguridad | Autenticacion JWT/Azure, roles, filtro HTTP | modules/security.md |
+| acceso-datos | JPA, Specifications, pool, entidades | modules/data-access.md |
+| api-web | Controladores, DTOs, validacion, exportacion | modules/web-api.md |
+(Agrupar por responsabilidad tecnica real, no inventar modulos)
+
+## Variables de configuracion clave
+| Propiedad / Variable | Valor actual | Proposito |
+|---|---|---|
+| server.port | 8084 | Puerto de la API |
+| spring.datasource.url | jdbc:sqlserver://... | Conexion SQL Server |
+| auth.url | http://57.151.96.13:8000/v1/validate | Servicio externo de validacion JWT |
+(Valores REALES del archivo de config/env leido. Si no se leyo el archivo, omitir la tabla)
 
 ## Como levantar
-- **Instalar deps:** \`npm install\`
-- **Servicios necesarios:** MongoDB corriendo, security-api accesible
-- **Comando para iniciar:** \`npm run start:dev\`
-
-## Comandos disponibles
-| Comando | Que hace |
+Comando principal primero. Luego paso a paso si existe.
+\`\`\`bash
+./run.sh        # compila y levanta todo en uno (si existe)
+\`\`\`
+O paso a paso:
+\`\`\`bash
+source ./scripts/env.sh
+npm install && npm run dev
+\`\`\`
 
-## Decisiones tecnicas relevantes
-(solo si hay decisiones notables; si no, omitir esta seccion)
+## Testing (si hay tests en el proyecto)
+Frameworks, comando para correr, cobertura minima si se menciona en el manifest o config.
+\`\`\`bash
+npm test               # todos los tests
+npm test -- --watch    # modo watch
+\`\`\`
 
 ────────────────────────────────────────────────────────────────
 NIVEL 2 — [componente]/modules/[modulo].md
-Detalle de un modulo interno. Objetivo: 40-120 lineas. Crear UNO POR cada modulo significativo.
+Objetivo: 50-120 lineas. Un archivo por modulo significativo.
 ────────────────────────────────────────────────────────────────
-Secciones obligatorias:
 
-# Modulo: [nombre] — [componente]
+# Modulo: [Nombre] — [componente]
 
 ## Funcion (lenguaje simple)
-1-2 lineas: "Permite al usuario gestionar X" / "El sistema usa este modulo para Y".
+1-2 lineas: "Protege todos los endpoints /api/**. Cada request debe llevar un token JWT valido."
 
 ## Funcion (tecnica)
-1-2 lineas: como esta implementado a alto nivel.
-
-## Flujos / casos de uso (1-3)
-Escenarios paso a paso. Ejemplo:
-- **Crear un pedido:** Cliente → POST /orders → middleware valida JWT → service.create() → guarda en DB → responde 201
-
-## Endpoints / interfaces publicas (si aplica)
-| Metodo | Ruta | Body | Respuesta |
-|--------|------|------|-----------|
-
-## Modelos / schemas relevantes
-\`\`\`typescript
-// shape REAL extraido del archivo de schema/model
-{
-  _id: ObjectId,
-  name: string,
-  createdAt: Date,
-  ...
-}
+1-2 lineas: como esta implementado. ej. "Filtro OncePerRequestFilter que extrae el JWT del header Authorization, lo valida contra el servicio externo auth.url, y si es valido establece el SecurityContext."
+
+## Flujo principal (diagrama ASCII)
+Para modulos de seguridad, acceso a datos, o cualquiera con logica de decision/secuencia:
+mostrar el flujo con ASCII art y nombres REALES de clases/metodos.
+\`\`\`text
+HTTP Request
+    │
+    ▼
+AuthFilter (OncePerRequestFilter)
+    │
+    ├── X-User-Source == "Azure"?
+    │       ▼ SI
+    │   AzureHeaderValidator → construye usuario virtual desde headers
+    │
+    └── NO
+        ▼
+    JwtValidator → POST http://auth-service/validate → carga usuario de BD
+    │
+    ▼
+SecurityContextHolder.setAuthentication(...)
+    │
+    ▼
+@PreAuthorize("hasAnyAuthority('ROLE_A','ROLE_B')") en el controller
 \`\`\`
 
-## Reglas de negocio
-- Validaciones: ...
-- Condiciones especiales: ...
-- Excepciones: ...
+## Entidades / modelos relevantes (si aplica)
+Para modulos de acceso a datos: tabla de entidades con su proposito y notas.
+| Entidad | Proposito | Notas |
+|---|---|---|
+| Client | Clientes finales | Clave compuesta: ClientId |
+| InterimClient | Clientes en staging | Tabla intermedia antes de procesar |
+
+## Reglas del modulo
+- Rutas protegidas: /api/** → autenticacion obligatoria
+- Rutas publicas: OPTIONS /**, /swagger-ui/**, /*
+- Sin sesion: STATELESS — sin cookies
+- ddl-auto=validate → el schema nunca se auto-modifica
 
 ## Archivos clave
-OBLIGATORIO: listar los archivos FUENTE reales que encontraste en los pre-fetched data.
-NO poner solo el manifest. Si no hay fuentes leidas para este modulo, omitir la seccion.
-| Archivo (ruta relativa al componente) | Rol |
-|---------------------------------------|-----|
-| src/main/java/.../ClientController.java | Expone endpoints REST /clients |
-| src/main/java/.../Client.java | Entidad JPA mapeada a tabla CLIENTS |
-| src/main/java/.../ClientRepository.java | Acceso a datos via JPA |
-| src/clients/clients.controller.ts | Endpoints /clients (Node.js) |
-| src/clients/clients.service.ts | Logica de negocio (Node.js) |
+Rutas RELATIVAS al directorio raiz del componente (no rutas absolutas, no solo el manifest).
+| Archivo | Rol |
+|---|---|
+| security/AuthFilter.java | Filtro principal — intercepta y valida cada request |
+| security/JwtValidator.java | Extrae username del JWT, verifica firma y expiracion |
+| configuration/SecurityConfig.java | Define SecurityFilterChain, rutas publicas/protegidas |
+| application-development.properties | auth.url, security.token.secret, security.token.expiration |
 
 ## Dependencias
-- **Internas (mismo componente):** auth, common
-- **Externas:** mongoose, class-validator
-- **Cross-component:** llama a security-api via HTTP para validar JWT
+- Librerias clave con version si se conoce: io.jsonwebtoken:jjwt:0.9.1, spring-boot-starter-security
+- Cross-component si corresponde: "llama a http://auth-service:8000/v1/validate para validar tokens"
 
 ================================================================
 CALIBRACION DE DETALLE
 ================================================================
-- NIVEL 0: 50-150 lineas (no menos, no mas)
-- NIVEL 1: 80-200 lineas por componente
-- NIVEL 2: 40-120 lineas por modulo
-- Si te queda corto → leiste pocos archivos, no agregues relleno — simplemente genera con lo que hay
-- Si te queda largo → estas repitiendo o agregando relleno, recorta
+- NIVEL 0: 80-150 lineas
+- NIVEL 1: 120-250 lineas por componente
+- NIVEL 2: 50-120 lineas por modulo
+- Si te queda corto → incluir mas endpoints reales, mas clases en el arbol, mas config values
+- Si te queda largo → estas repitiendo entre niveles o agregando relleno; recorta
 
 ================================================================
 QUE NO HACER
 ================================================================
 - NO usar "Inferido", "Probablemente", "(asumido)", "(quizas)", "parece"
 - NO repetir lo mismo entre niveles sin agregar valor (cada nivel zoomea mas)
-- NO dejar tablas vacias ni con placeholders tipo "..."
-- NO mezclar lenguaje tecnico puro: SIEMPRE empezar funcional, despues tecnico
-- NO documentar componentes triviales (scripts, docs, configs sueltas) con su propia carpeta — mencionalos en NIVEL 0 y listo
-- NO inventar endpoints, env vars, puertos o schemas que no leiste
+- NO dejar tablas vacias ni con placeholders tipo "..." o "ver manifest"
+- NO escribir overview que podria aplicar a cualquier proyecto (tiene que ser especifico de ESTE proyecto)
+- NO documentar componentes triviales (scripts sueltos, configs simples) con carpeta propia — mencionalos en NIVEL 0 y listo
+- NO inventar endpoints, env vars, puertos, hosts, clases o schemas que no leiste en los archivos reales
 
 ================================================================
 FORMATO DE SALIDA — OBLIGATORIO

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mp",
-  "version": "0.5.21",
+  "version": "0.5.22",
   "description": "Deterministic multi-agent CLI orchestrator — plan, code, review",
   "type": "module",
   "main": "./dist/index.js",