agent-mp 0.5.17 → 0.5.19

package/dist/core/engine.js

@@ -238,9 +238,11 @@ async function walkForKeyFiles(root) {
         'server.ts', 'server.js', 'server.py',
         'application.ts', 'application.js', 'application.py',
     ]);
-    const ENTRY_REGEX = /Application\.(java|kt)$/;
+    const ENTRY_REGEX = /Application\.[a-z]+$/i; // *Application.java, *Application.kt, etc.
     const CTRL_REGEX = /(controller|router|routes|handler|endpoint|resource)/i;
     const SCHEMA_REGEX = /(schema|\.entity|\.model|\.dto|models?\.|entities?\.)/i;
+    // Directories that conventionally hold data/domain classes (language-agnostic)
+    const DOMAIN_DIR_REGEX = /[\/\\](domain|entity|entities|model|models|dto|dtos|schema|schemas)[\/\\]/i;
     async function walk(dir, depth) {
         if (depth > 6)
             return;
@@ -276,7 +278,8 @@ async function walkForKeyFiles(root) {
             if (CTRL_REGEX.test(e.name) && result.controllers.length < 5) {
                 result.controllers.push(p);
             }
-            if (SCHEMA_REGEX.test(e.name) && result.schemas.length < 5) {
+            const isSchema = SCHEMA_REGEX.test(e.name) || DOMAIN_DIR_REGEX.test(p);
+            if (isSchema && result.schemas.length < 5) {
                 result.schemas.push(p);
             }
         }
@@ -1155,7 +1158,7 @@ INSTRUCCIONES:
                     compSection.push(`### ENTRY POINT: ${rel}\n\`\`\`\n${content}\n\`\`\``);
                 }
             }
-            const ctrls = found.controllers.slice(0, 3);
+            const ctrls = found.controllers.slice(0, 5);
             for (const ctrl of ctrls) {
                 const content = await readFileSafe(ctrl, MAX_CTRL);
                 if (content) {
@@ -1163,7 +1166,7 @@ INSTRUCCIONES:
                     compSection.push(`### CONTROLLER/ROUTER: ${rel}\n\`\`\`\n${content}\n\`\`\``);
                 }
             }
-            const schemas = found.schemas.slice(0, 3);
+            const schemas = found.schemas.slice(0, 4);
             for (const sch of schemas) {
                 const content = await readFileSafe(sch, MAX_SCHEMA);
                 if (content) {
@@ -1190,7 +1193,9 @@ INSTRUCCIONES:
         // Ensure .agent/ structure exists
         const agentDir = path.join(this.projectDir, '.agent');
         const contextDir = path.join(agentDir, 'context');
+        const docsDir = path.join(agentDir, 'docs');
         await fs.mkdir(contextDir, { recursive: true });
+        await fs.mkdir(docsDir, { recursive: true });
         await fs.mkdir(path.join(agentDir, 'rules'), { recursive: true });
         // NOTE: cleanup of stray files moved to AFTER successful parse, to avoid
         // wiping previous docs when the explorer fails (e.g. tool-call hallucination).
@@ -1273,11 +1278,28 @@ El engine YA leyo por vos los archivos clave de cada componente y te los pasa ar
    - Del MANIFEST: nombre, version, framework, dependencias clave con sus versiones, scripts, entry point
    - Del ENTRY POINT: puerto real, middlewares, modulos cargados
    - De los CONFIG/ENV: variables reales y su proposito
-   - De los CONTROLLER/ROUTER: endpoints REALES (metodo, ruta, parametros)
-   - De los SCHEMA/MODEL: shape real de los datos
+   - De los CONTROLLER/ROUTER: endpoints REALES (metodo, ruta, parametros, anotaciones como @GetMapping/@PostMapping/router.get)
+   - De los SCHEMA/MODEL/DOMAIN: shape real de los datos (campos, tipos, anotaciones @Column/@Entity)
 3. Identificar relaciones REALES entre componentes (URLs/hosts de otros servicios en .env, imports cross-component, conexiones a BBDD).
 4. Generar la documentacion en los 3 niveles, en formato markdown, dentro de los bloques === ... ===.
 
+REGLA CRITICA PARA MODULOS (NIVEL 2):
+- Los modulos SON LAS FEATURES DEL NEGOCIO, NO las capas tecnicas.
+- MAL: modulos llamados "web-api", "security", "data-access" — eso es hablar de capas, no de features
+- BIEN: modulos llamados "clients", "sales", "products", "auth", "orders" — eso es hablar de features reales
+- Para identificar los modulos, MIRA los CONTROLLER/ROUTER pre-leidos: el nombre del modulo = lo que maneja ese controller
+  * ClientController o clients.controller → modulo "clients"
+  * SaleController o sale.routes → modulo "sales"
+  * AuthController o auth.handler → modulo "auth"
+- "Archivos clave" en cada modulo DEBE listar los archivos FUENTE REALES que leiste, NO solo el manifest.
+  Ejemplo correcto:
+  | Archivo (ruta relativa al componente) | Rol |
+  | controller/ClientController.java | Endpoints REST /clients |
+  | domain/Client.java | Entidad mapeada a tabla CLIENTS |
+  | repository/ClientRepository.java | Acceso a base de datos |
+  | src/clients/clients.controller.ts | Endpoints /clients |
+  | src/clients/client.schema.ts | Modelo de datos Client |
+
 NO inventes datos. Si un componente no tiene una de esas piezas en los archivos leidos, simplemente omiti esa seccion en su documentacion.
 
 ================================================================
@@ -1368,15 +1390,24 @@ Secciones obligatorias:
 - **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).
 \`\`\`
 src/
-├── main.ts            # entry point, configura CORS y swagger
-├── auth/              # autenticacion JWT
-├── leads/             # gestion de leads
+├── 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 }
 └── ...
 \`\`\`
+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.
 
 ## 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 |
@@ -1387,7 +1418,7 @@ src/
 |--------|------|--------|----------------------------|
 | GET | /leads | leads | Lista negocios filtrables |
 | GET | /leads/:id | leads | Detalle de un negocio |
-(SOLO endpoints reales extraidos de los controllers)
+(SOLO endpoints reales extraidos de los controllers — metodo HTTP, ruta, y descripcion en 1 linea)
 
 ## Variables de entorno
 | Variable | Default | Proposito |
@@ -1448,10 +1479,15 @@ Escenarios paso a paso. Ejemplo:
 - Excepciones: ...
 
 ## Archivos clave
-| Archivo | Rol |
-|---------|-----|
-| src/leads/leads.controller.ts | Endpoints /leads |
-| src/leads/leads.service.ts | Logica de negocio |
+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) |
 
 ## Dependencias
 - **Internas (mismo componente):** auth, common
@@ -1464,7 +1500,7 @@ 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 corto → leiste pocos archivos, no agregues relleno — simplemente genera con lo que hay
 - Si te queda largo → estas repitiendo o agregando relleno, recorta
 
 ================================================================
@@ -1477,40 +1513,109 @@ QUE NO HACER
 - 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
 
+================================================================
+DIRECTORIO .agent/docs/ — FLUJOS POR FUNCIONALIDAD (orientado a desarrolladores)
+================================================================
+Ademas de los archivos de context/, generar docs de flujos. Objetivo: un dev que llega al proyecto puede buscar "como funciona el login" o "donde esta el endpoint de clientes" y encontrar exactamente que archivos tocar, en que orden, y por que.
+
+Generar UN archivo por cada flujo funcional principal que puedas identificar de los CONTROLLER/ROUTER leidos.
+Si no hay controllers, inferir los flujos desde el MANIFEST y el ENTRY POINT.
+
+INDICE OBLIGATORIO:
+=== .agent/docs/README.md ===
+# Flujos del proyecto — Indice
+
+| Flujo | Descripcion | Componente(s) |
+|-------|-------------|---------------|
+| [nombre-flujo](nombre-flujo.md) | 1 linea que explica que hace | componente-a, componente-b |
+...
+
+POR CADA FLUJO:
+=== .agent/docs/[nombre-flujo].md ===
+Nombre del archivo: kebab-case del nombre del flujo (auth.md, crear-cliente.md, consulta-ventas.md)
+
+Estructura de cada archivo de flujo:
+
+# Flujo: [Nombre legible]
+
+## Qué hace
+1 linea en lenguaje de negocio: "Permite al usuario X hacer Y"
+
+## Componentes involucrados
+- [componente-a]: rol en este flujo
+- [componente-b]: rol en este flujo
+
+## Traza técnica paso a paso
+Numberar cada paso. Incluir archivo y funcion/clase cuando fue leido.
+1. Cliente/Frontend → METODO /ruta/endpoint (archivo: ruta/al/Controller)
+2. Middleware/Guard/Filter valida/transforma (archivo: ruta/al/Filter o Config)
+3. Service/UseCase ejecuta la logica (archivo: ruta/al/Service)
+4. Repository/DAO consulta o escribe en DB (archivo: ruta/al/Repository → tabla o coleccion)
+5. Respuesta: codigo HTTP + shape de respuesta
+
+## Archivos involucrados y por qué
+Esta tabla es lo mas importante para un dev nuevo: tiene que saber QUE archivo y POR QUE esta en el flujo.
+| Archivo (ruta relativa al componente) | Por que esta en este flujo |
+|---------------------------------------|---------------------------|
+| ruta/Controller | Recibe el request y delega |
+| ruta/Service | Contiene la logica de negocio |
+| ruta/Repository | Lee o escribe en la base de datos |
+| ruta/Entity o Schema | Define la forma del dato |
+| ruta/Config o Filter | Aplica seguridad / transformacion |
+
+## Variables / configuracion relevante
+Solo las que afectan directamente este flujo (env vars, properties, feature flags).
+
+## Como probar este flujo
+- Endpoint: METODO /ruta
+- Body o params de ejemplo
+- Respuesta exitosa: codigo + campos
+- Errores comunes: codigo + cuando ocurre
+
+================================================================
+CALIBRACION DE DETALLE — docs/
+================================================================
+- README.md: una fila por flujo, no mas
+- Por flujo: 30-80 lineas. Concreto. Si un paso no fue leido, omitirlo.
+- NO inventar nombres de archivos. Si no se leyo un Service para este flujo, no lo pongas.
+- Generar entre 2 y 8 flujos segun la cantidad de controllers/features encontrados.
+
 ================================================================
 FORMATO DE SALIDA — OBLIGATORIO
 ================================================================
 Devolve UNICAMENTE bloques de archivos separados por marcadores ===. Nada de explicaciones extra fuera de los bloques.
 
 IMPORTANTE: TODAS las rutas son RELATIVAS al directorio del proyecto.
-Los archivos se escriben SIEMPRE dentro de .agent/context/
 
-Ejemplos de marcadores:
+Ejemplos de marcadores validos:
   === .agent/context/architecture.md ===
   === .agent/context/datamart-data-access-api/architecture.md ===
   === .agent/context/datamart-data-access-api/modules/auth.md ===
-  === .agent/context/nexus-core-api/architecture.md ===
-  === .agent/context/nexus-core-api/modules/users.md ===
+  === .agent/docs/README.md ===
+  === .agent/docs/auth.md ===
+  === .agent/docs/consulta-ventas.md ===
 
 === .agent/context/architecture.md ===
-[contenido completo del NIVEL 0]
+[contenido NIVEL 0]
 
-=== .agent/context/nombre-componente-1/architecture.md ===
-[contenido completo del NIVEL 1 del componente 1]
+=== .agent/context/nombre-componente/architecture.md ===
+[contenido NIVEL 1]
 
-=== .agent/context/nombre-componente-1/modules/auth.md ===
-[contenido completo del NIVEL 2 del modulo auth]
+=== .agent/context/nombre-componente/modules/auth.md ===
+[contenido NIVEL 2]
 
-=== .agent/context/nombre-componente-1/modules/leads.md ===
-[contenido completo del NIVEL 2 del modulo leads]
+=== .agent/docs/README.md ===
+[indice de flujos]
 
-=== .agent/context/nombre-componente-2/architecture.md ===
-...
+=== .agent/docs/auth.md ===
+[flujo de autenticacion]
 
 REGLAS DE PATHS:
-- El archivo principal SIEMPRE es: === .agent/context/architecture.md ===
+- Arquitectura global: === .agent/context/architecture.md ===
 - Por componente: === .agent/context/[nombre-componente]/architecture.md ===
 - Por modulo interno: === .agent/context/[nombre-componente]/modules/[nombre-modulo].md ===
+- Indice de flujos: === .agent/docs/README.md ===
+- Por flujo: === .agent/docs/[nombre-flujo].md ===
 - 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');
@@ -1541,24 +1646,36 @@ REGLAS DE PATHS:
             content = content.replace(/^```markdown\s*/i, '').replace(/^```\s*$/gm, '').trim();
             if (!content)
                 continue;
-            // Normalize: strip any .agent/context/ prefix from the marker
-            let relPath = fileName.replace(/^\.agent\/context\//i, '').replace(/^\/+/, '');
+            // Detect routing: .agent/docs/ → docsDir, .agent/context/ → contextDir
+            const isDocsFile = /^\.agent[\/\\]docs[\/\\]/i.test(fileName);
             let targetPath = null;
-            if (relPath === 'architecture.md' || relPath === 'ARCHITECTURE.md') {
-                targetPath = mainArchPath;
+            if (isDocsFile) {
+                // .agent/docs/README.md → docsDir/README.md
+                // .agent/docs/auth.md  → docsDir/auth.md
+                const docsRel = fileName.replace(/^\.agent[\/\\]docs[\/\\]/i, '').replace(/^\/+/, '');
+                if (docsRel && docsRel.endsWith('.md')) {
+                    targetPath = path.join(docsDir, ...docsRel.split(/[\/\\]/).filter(Boolean));
+                }
             }
             else {
-                const pathParts = relPath.split(/[\/\\]/).filter(Boolean);
-                if (pathParts.length >= 3 && pathParts[pathParts.length - 2] === 'modules') {
-                    targetPath = path.join(contextDir, pathParts[pathParts.length - 3], 'modules', pathParts[pathParts.length - 1]);
+                // .agent/context/ files (existing behaviour)
+                const relPath = fileName.replace(/^\.agent\/context\//i, '').replace(/^\/+/, '');
+                if (relPath === 'architecture.md' || relPath === 'ARCHITECTURE.md') {
+                    targetPath = mainArchPath;
                 }
-                else if (pathParts.length >= 2) {
-                    targetPath = path.join(contextDir, pathParts[pathParts.length - 2], pathParts[pathParts.length - 1]);
+                else {
+                    const pathParts = relPath.split(/[\/\\]/).filter(Boolean);
+                    if (pathParts.length >= 3 && pathParts[pathParts.length - 2] === 'modules') {
+                        targetPath = path.join(contextDir, pathParts[pathParts.length - 3], 'modules', pathParts[pathParts.length - 1]);
+                    }
+                    else if (pathParts.length >= 2) {
+                        targetPath = path.join(contextDir, pathParts[pathParts.length - 2], pathParts[pathParts.length - 1]);
+                    }
                 }
             }
             if (!targetPath)
                 continue;
-            pendingWrites.push({ targetPath, content, label: relPath });
+            pendingWrites.push({ targetPath, content, label: fileName.trim() });
         }
         if (pendingWrites.length === 0) {
             log.error('Explorer devolvio texto pero ningun bloque === *.md === fue parseable.');

package/package.json

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