agent-mp 0.5.18 → 0.5.19

package/dist/core/engine.js

@@ -238,11 +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;
-    // Java packages that contain domain/entity classes even when filename alone doesn't signal it
-    const JAVA_DOMAIN_DIR_REGEX = /[\/\\](domain|entity|entities|model|models)[\/\\]/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;
@@ -278,7 +278,7 @@ async function walkForKeyFiles(root) {
             if (CTRL_REGEX.test(e.name) && result.controllers.length < 5) {
                 result.controllers.push(p);
             }
-            const isSchema = SCHEMA_REGEX.test(e.name) || JAVA_DOMAIN_DIR_REGEX.test(p);
+            const isSchema = SCHEMA_REGEX.test(e.name) || DOMAIN_DIR_REGEX.test(p);
             if (isSchema && result.schemas.length < 5) {
                 result.schemas.push(p);
             }
@@ -1193,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).
@@ -1283,19 +1285,20 @@ El engine YA leyo por vos los archivos clave de cada componente y te los pasa ar
 
 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 negocio
-- BIEN: modulos llamados "clients", "sales", "products", "auth", "orders" — eso es hablar de features
-- Para identificar los modulos reales, MIRÁ los CONTROLLER/ROUTER pre-leidos:
-  * Si el controller se llama ClientController.java → el modulo se llama "clients"
-  * Si se llama SaleController.java → modulo "sales"
-  * Si se llama AuthController.ts → modulo "auth"
-  * El nombre del modulo = lo que maneja ese controller, no su capa
-- "Archivos clave" en cada modulo DEBE listar los archivos FUENTE REALES que leiste (los .java, .ts, .py, etc.),
-  NO solo el manifest (pom.xml / package.json). Ejemplo correcto:
-  | Archivo | Rol |
-  | src/main/java/.../ClientController.java | Endpoints REST /clients |
-  | src/main/java/.../Client.java | Entidad JPA (tabla CLIENTS) |
-  | src/main/java/.../ClientRepository.java | Acceso a SQL Server |
+- 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.
 
@@ -1510,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');
@@ -1574,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.18",
+  "version": "0.5.19",
   "description": "Deterministic multi-agent CLI orchestrator — plan, code, review",
   "type": "module",
   "main": "./dist/index.js",