agent-mp 0.5.11 → 0.5.12

package/dist/core/engine.js

@@ -1021,125 +1021,271 @@ DIRECTORIO_TRABAJO: ${this.projectDir}
 PROYECTO: ${this.config.project}
 STACK: ${this.config.stack}
 
-ESTRUCTURA DE ARCHIVOS DEL PROYECTO (excluyendo .agent, node_modules, .git, dist, __pycache__, .venv, target, build):
+ESTRUCTURA DE ARCHIVOS (excluye .agent, node_modules, .git, dist, __pycache__, .venv, target, build):
 ${fsSnapshot}
 
-${existingMainArch ? `=== DOCUMENTACION EXISTENTE: architecture.md (principal) ===\n${existingMainArch.slice(0, 2000)}\n` : ''}
-${existingComponentDocs ? `=== DOCUMENTACION EXISTENTE por componente ===\n${existingComponentDocs.slice(0, 3000)}\n` : ''}
+${existingMainArch ? `=== DOC EXISTENTE: architecture.md (principal) ===\n${existingMainArch.slice(0, 2000)}\n` : ''}
+${existingComponentDocs ? `=== DOC EXISTENTE por componente ===\n${existingComponentDocs.slice(0, 3000)}\n` : ''}
 
-INSTRUCCIONES:
-Analiza la estructura de archivos y genera documentación ESCALONADA en DOS NIVELES:
+================================================================
+OBJETIVO
+================================================================
+Generar documentacion ESCALONADA en 3 niveles, util TANTO para personas funcionales (PM, negocio) como tecnicas (devs).
+Detallada pero NO excesiva. Concreta, con datos REALES leidos de los archivos. Cero especulaciones.
 
-NIVEL 1: architecture.md (raiz de .agent/context/)
-  - Lista TODOS los directorios al nivel del proyecto
-  - Indica si son independientes o conectados entre si (ej: front consume back, dos APIs se consumen entre si)
-  - Prerequisitos generales para levantar el proyecto
-  - Comandos globales de desarrollo
+================================================================
+REGLA DE ORO — PROHIBIDO INVENTAR
+================================================================
+NO uses jamas: "Inferido", "Probablemente", "Posiblemente", "Asumido", "(supuesto)", "(quizas)", "parece ser".
+Si no podes verificar un dato leyendo un archivo concreto → OMITELO. Es mejor una doc corta y veraz que una larga llena de suposiciones.
+Cada puerto, version, endpoint, env var, schema o ruta que aparezca en la doc DEBE haber sido leido de un archivo real.
 
-NIVEL 2: Para CADA directorio que sea un servicio/API/app/funcionalidad:
-  - Crea subcarpeta: [nombre-del-directorio]/architecture.md → explica como se estructura internamente
-  - Crea subcarpeta: [nombre-del-directorio]/modules/[modulo].md → detalle de cada modulo interno
-  - Si un directorio es trivial (solo scripts, docs, configs), NO crees subcarpeta, solo mencionarlo en el architecture.md principal
+================================================================
+WORKFLOW QUE TENES QUE EJECUTAR (usa tus tools de read_file/grep_search/list_directory)
+================================================================
+1. Lista DIRECTORIO_TRABAJO. Identifica los componentes (apps/services/libs). Descarta lo trivial (solo configs/docs/scripts).
+2. Para CADA componente no trivial, LEE COMO MINIMO:
+   a. Manifest del proyecto: package.json | requirements.txt | pyproject.toml | pom.xml | build.gradle | Cargo.toml | go.mod
+      → de ahi sacas: nombre, version, framework, dependencias clave con sus versiones, scripts/tasks, entry point
+   b. Entry point real: src/main.ts | index.js | app.py | Application.java | cmd/main.go (segun stack)
+      → de ahi sacas: puerto, middlewares, modulos cargados, configuracion inicial
+   c. Archivo de variables de entorno: .env | .env.example | application.yml | config.* | settings.py
+      → de ahi sacas: variables reales con su proposito
+   d. Al menos 2-3 controladores/routers/handlers principales
+      → de ahi extraes endpoints REALES (metodo, ruta, parametros)
+   e. Al menos 2-3 modelos/schemas/entities principales
+      → de ahi extraes el shape de datos
+   f. README.md del componente si existe
+3. Mapea RELACIONES REALES entre componentes (no asumas):
+   - Buscando URLs/hosts de otros servicios en .env
+   - Buscando imports cross-component
+   - Buscando cadenas de conexion a BBDD/colas/cache
+4. Recien con esa informacion concreta, genera los archivos de documentacion.
 
-FORMATO EXACTO de los archivos a devolver (separados por marcadores):
+================================================================
+LENGUAJE DUAL (regla critica)
+================================================================
+Cada seccion abre con UNA linea en lenguaje simple (que entienda un PM/negocio), DESPUES viene el detalle tecnico.
+- MAL: "El microservicio orquesta la persistencia mediante un repositorio."
+- BIEN: "Guarda la informacion del usuario en la base. Internamente usa un repositorio que abstrae la conexion a MongoDB."
 
-=== architecture.md ===
-# ${this.config.project} — Architecture Overview
+================================================================
+ESTRUCTURA DE LOS 3 NIVELES
+================================================================
+
+────────────────────────────────────────────────────────────────
+NIVEL 0 — architecture.md (raiz de .agent/context/)
+Indice global. Objetivo: 50-150 lineas. Concreto.
+────────────────────────────────────────────────────────────────
+Secciones obligatorias:
 
-Descripcion general del proyecto.
+# ${this.config.project} — Arquitectura Global (NIVEL 0)
 
-## Componentes del Proyecto
+> Indice de servicios y relaciones. Lectura escalonada:
+>   NIVEL 0: este archivo
+>   NIVEL 1: .agent/context/[componente]/architecture.md
+>   NIVEL 2: .agent/context/[componente]/modules/[modulo].md
 
-| Componente | Tipo | Stack | Proposito | Entry Point |
-|------------|------|-------|-----------|-------------|
-| datamart-data-access-api | API Backend | NestJS | Acceso a datos | src/main.ts |
-| nexus-core-api | API Backend | NestJS | Core business logic | src/main.ts |
+## 1. Overview funcional
+2-4 lineas en lenguaje simple: que es el sistema, para quien sirve, que problema resuelve.
 
-## Como se Relacionan los Componentes
+## 2. Componentes del proyecto
+| Componente | Tipo | Stack + version | Puerto | Proposito (negocio) | Entry point |
+|------------|------|-----------------|--------|---------------------|-------------|
+(una fila por componente, con datos REALES)
 
-Explica las conexiones entre componentes:
-- Si un front consume un back, explicar como
-- Si dos APIs se consumen entre sí (fetch, HTTP), explicar el flujo
-- Si son independientes, indicar que cada uno funciona por su cuenta
+## 3. Relaciones entre componentes
+| Origen | Destino | Tipo (HTTP / Import / DB / Queue / CORS) | Proposito |
+|--------|---------|------------------------------------------|-----------|
+(una fila por cada relacion confirmada)
 
-### Diagrama de Flujo (texto)
+## 4. Diagrama de arquitectura
 \`\`\`
-[Frontend] --fetch--> [API 1] --HTTP--> [API 2]
-[API 1] --> [Database]
+[Frontend Web] ──HTTP──> [API Auth :8081]
+       │                        │
+       │                        v
+       └──HTTP──> [API Core :8080] ──> [MongoDB]
 \`\`\`
 
-## Prerequisitos Generales
-- Node.js x.x, Python x.x, Docker, etc.
-- Bases de datos, servicios externos
+## 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.
 
-## Comandos de Desarrollo Globales
+## 6. Prerequisitos para levantar el proyecto
+Versiones REALES leidas de los manifests (no rangos genericos).
+
+## 7. Comandos globales de desarrollo
 | Comando | Descripcion | Directorio |
-|---------|-------------|------------|
-| ... | ... | ... |
 
-=== [nombre]/architecture.md ===
-# [nombre] — Arquitectura Interna
+## 8. Decisiones de arquitectura globales (opcional, solo si hay)
+
+────────────────────────────────────────────────────────────────
+NIVEL 1 — [componente]/architecture.md
+Detalle del componente. Objetivo: 80-200 lineas. Crear UNO POR CADA componente NO trivial.
+────────────────────────────────────────────────────────────────
+Secciones obligatorias:
 
-Descripcion de este componente y su rol en el proyecto.
+# [componente] — Arquitectura (NIVEL 1)
 
-## Estructura Interna
+## Que hace
+2-3 lineas en lenguaje simple, sin tecnicismos.
+
+## Casos de uso principales
+3-6 bullets en formato negocio:
+- "Permite al usuario X..."
+- "El sistema usa este servicio para Y..."
+
+## 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)
+
+## 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)
 \`\`\`
 src/
-  ├── main.ts          # entry point
-  ├── config/          # configuracion
-  ├── controllers/     # endpoints
-  └── services/        # logica de negocio
+├── main.ts            # entry point, configura CORS y swagger
+├── auth/              # autenticacion JWT
+├── leads/             # gestion de leads
+└── ...
 \`\`\`
 
-## Modulos Internos
-| Modulo | Archivo | Descripcion |
-|--------|---------|-------------|
-| config | modules/config.md | Configuracion |
-| controller | modules/controller.md | Endpoints |
+## Modulos internos
+| 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)
 
-## Como Levantar
-- **Instalar deps:** comando
-- **Servicios necesarios:** BD, redis, etc.
-- **Variables de entorno:** listarlas con su proposito
-- **Comando para iniciar:** \`...\`
+## Variables de entorno
+| Variable | Default | Proposito |
+|----------|---------|-----------|
+| PORT | 8085 | Puerto del servicio |
+| MONGODB_URI | mongodb://... | Conexion principal |
 
-## Comandos Disponibles
+## Integraciones con otros servicios / sistemas
+| Servicio externo | Tipo (HTTP/DB/Queue) | Proposito |
+
+## 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 |
-|---------|----------|
-| ... | ... |
 
-## Comunicacion con Otros Componentes
-- A que APIs llama o que APIs lo llaman
-- Protocolo (fetch, HTTP, gRPC, etc.)
+## Decisiones tecnicas relevantes
+(solo si hay decisiones notables; si no, omitir esta seccion)
+
+────────────────────────────────────────────────────────────────
+NIVEL 2 — [componente]/modules/[modulo].md
+Detalle de un modulo interno. Objetivo: 40-120 lineas. Crear UNO POR cada modulo significativo.
+────────────────────────────────────────────────────────────────
+Secciones obligatorias:
+
+# Modulo: [nombre] — [componente]
+
+## Funcion (lenguaje simple)
+1-2 lineas: "Permite al usuario gestionar X" / "El sistema usa este modulo para Y".
 
-=== [nombre]/modules/[modulo].md ===
-# [nombre-del-modulo]
+## Funcion (tecnica)
+1-2 lineas: como esta implementado a alto nivel.
 
-## Funcion
-Que hace este modulo especifico.
+## 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,
+  ...
+}
+\`\`\`
 
-## Archivo Principal
-- **Ruta:** path relativo
-- **Funciones/Clases principales**
+## Reglas de negocio
+- Validaciones: ...
+- Condiciones especiales: ...
+- Excepciones: ...
 
-## Endpoints / Interfaces Publicas
-Si es un controller/router:
-- \`GET /ruta\` — descripcion
-- \`POST /ruta\` — descripcion
+## Archivos clave
+| Archivo | Rol |
+|---------|-----|
+| src/leads/leads.controller.ts | Endpoints /leads |
+| src/leads/leads.service.ts | Logica de negocio |
 
 ## Dependencias
-- **Internas:** modulos del mismo componente
-- **Externas:** librerias de terceros
-
-REGLAS:
-- Devuelve UNICAMENTE los archivos separados por === path/file.md ===
-- USA NOMBRES CORTOS: NO uses rutas absolutas
-- El archivo principal SIEMPRE es === architecture.md ===
-- Para componentes: === nombre-del-componente/architecture.md ===
-- Para modulos internos: === nombre-del-componente/modules/nombre-modulo.md ===
-- Para componentes triviales (scripts, docs): solo mencionarlos en architecture.md principal
-- Documenta TODOS los directorios al nivel de DIRECTORIO_TRABAJO (excluyendo .agent)
-- Si hay documentacion existente, actualizala con los cambios detectados`;
+- **Internas (mismo componente):** auth, common
+- **Externas:** mongoose, class-validator
+- **Cross-component:** llama a security-api via HTTP para validar JWT
+
+================================================================
+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, lee mas
+- Si te queda largo → estas repitiendo 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
+
+================================================================
+FORMATO DE SALIDA — OBLIGATORIO
+================================================================
+Devolve UNICAMENTE bloques de archivos separados por marcadores ===. Nada de explicaciones extra fuera de los bloques.
+
+=== architecture.md ===
+[contenido completo del NIVEL 0]
+
+=== nombre-componente-1/architecture.md ===
+[contenido completo del NIVEL 1 del componente 1]
+
+=== nombre-componente-1/modules/auth.md ===
+[contenido completo del NIVEL 2 del modulo auth]
+
+=== nombre-componente-1/modules/leads.md ===
+[contenido completo del NIVEL 2 del modulo leads]
+
+=== nombre-componente-2/architecture.md ===
+...
+
+REGLAS DE PATHS:
+- El archivo principal SIEMPRE es: === architecture.md ===
+- Por componente: === [nombre-componente]/architecture.md ===
+- Por modulo interno: === [nombre-componente]/modules/[nombre-modulo].md ===
+- USA SIEMPRE rutas RELATIVAS, jamas absolutas
+- Documenta TODOS los componentes no triviales del DIRECTORIO_TRABAJO
+- Si existe documentacion previa, ACTUALIZALA preservando lo que sigue siendo valido y agregando lo nuevo`;
         const res = await this.runWithFallback('explorer', prompt, 'Exploracion');
         const text = extractCliText(res);
         // Parse sections separated by === path/file.md === markers
@@ -1230,16 +1376,47 @@ PROYECTO: ${this.config.project}
 ${existingArch ? `DOCUMENTACION EXISTENTE:\n${existingArch.slice(0, 3000)}\n` : 'Sin documentacion previa.\n'}
 CONTEXTO: ${context.slice(0, 2000)}
 
-INSTRUCCIONES:
-1. Lista el directorio raiz e identifica todos los servicios/apps.
-2. Para cada uno: lee package.json/requirements.txt, explora src/, identifica entry point, rutas/endpoints, puerto.
-3. Identifica dependencias entre servicios.
-4. Crea/actualiza ${archPath} con tabla resumen y detalle por servicio.
-5. Crea/actualiza ${contextDir}/<servicio>/architecture.md para cada servicio.
-
-REGLAS:
-- Escribe UNICAMENTE los archivos indicados: ${archPath} y ${contextDir}/<servicio>/architecture.md
-- NO crees archivos adicionales ni con otros nombres en ningun directorio`);
+OBJETIVO
+Generar documentacion ESCALONADA en 3 niveles (global / componente / modulo), util para perfiles funcionales y tecnicos. Detallada pero concreta. Cero suposiciones.
+
+REGLA DE ORO — PROHIBIDO ESPECULAR
+NO uses "Inferido", "Probablemente", "Asumido", "(quizas)", "parece". Si no podes verificar un dato leyendo un archivo, OMITELO. Cada puerto, version, endpoint, env var y schema debe haber sido leido de un archivo real.
+
+WORKFLOW (usa tus tools)
+1. Lista DIRECTORIO_TRABAJO y detecta los componentes no triviales.
+2. Para cada componente, LEE como minimo:
+   - Manifest (package.json | requirements.txt | pom.xml | build.gradle | go.mod | Cargo.toml)
+   - Entry point (main.ts | index.js | app.py | Application.java | cmd/main.go)
+   - .env / .env.example / application.yml / settings.py
+   - 2-3 controladores/routers principales (para endpoints reales)
+   - 2-3 schemas/models principales (para shapes reales)
+3. Mapea relaciones reales (URLs en .env, imports cross-component, conexiones a DB/colas).
+
+LENGUAJE DUAL
+Cada seccion abre con UNA linea simple (que entienda un PM). Despues, el detalle tecnico.
+- MAL: "El microservicio orquesta la persistencia mediante un repositorio."
+- BIEN: "Guarda la informacion del usuario. Internamente usa un repositorio que abstrae MongoDB."
+
+NIVEL 0 — ${archPath} (50-150 lineas)
+Secciones: Overview funcional · Tabla de componentes (con stack+version, puerto, proposito, entry point) · Tabla de relaciones (origen, destino, tipo, proposito) · Diagrama ASCII · 3-5 flujos end-to-end (mapping funcional → tecnico) · Prerequisitos · Comandos globales.
+
+NIVEL 1 — ${contextDir}/<componente>/architecture.md (80-200 lineas, uno por componente)
+Secciones: Que hace (simple) · Casos de uso (3-6 bullets en formato negocio) · Stack tecnico (tabla con versiones reales) · Puerto y URLs · Estructura interna (arbol real) · Tabla de modulos · Tabla de endpoints reales · Tabla de variables de entorno · Integraciones · Como levantar · Comandos.
+
+NIVEL 2 — ${contextDir}/<componente>/modules/<modulo>.md (40-120 lineas, uno por modulo significativo)
+Secciones: Funcion (simple) · Funcion (tecnica) · Flujos / casos de uso paso a paso · Endpoints / interfaces · Schemas reales en codigo · Reglas de negocio · Archivos clave · Dependencias internas/externas/cross-component.
+
+CALIBRACION
+- NIVEL 0: 50-150 lineas. NIVEL 1: 80-200 por componente. NIVEL 2: 40-120 por modulo.
+- Si te queda corto, leiste pocos archivos. Si te queda largo, recorta el relleno.
+- Componentes triviales (solo scripts/docs): mencionalos en NIVEL 0 y NO les crees subcarpeta.
+
+REGLAS DE ESCRITURA
+- Solo podes escribir archivos dentro de ${contextDir}/
+- NO crees archivos sueltos en la raiz de ${contextDir}/ (excepto architecture.md)
+- Por componente usa: ${contextDir}/<componente>/architecture.md
+- Por modulo usa: ${contextDir}/<componente>/modules/<modulo>.md
+- Si existe documentacion previa, ACTUALIZALA preservando lo valido`);
         let result;
         const sp = this._startSpinner(`agent-explorer  ${role.model}`);
         try {

package/package.json

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