mcp-state-machine-test-framework 1.2.1 → 1.2.3

package/README.md

@@ -49,13 +49,12 @@ If you are an AI agent helping with this project, follow these rules:
 5. **Workflow**: Use `inspect_framework` to understand the current state before proposing changes.
 
 ## 🚀 Mission Bootstrap (Copy & Paste to any AI Agent)
-> **⚠️ CRITICAL SCHEMA WARNING**: This framework **DOES NOT** use `nodes[]` or `edges[]` arrays. It uses a `nodos` object map. **ALWAYS** use the `upsert_node` tool.
->
 > **YOUR ONLY MISSION**: 
 > 1. Run `npx -y -p mcp-state-machine-test-framework mcp-sms-init` to setup EVERYTHING.
-> 2. Read `.mcp_agent_rules` to understand the workflow.
+> 2. Use `design_wizard` (action: 'start') to design nodes step-by-step.
+> 3. **STRICT RULE**: Never edit JSON files manually.
 > 
-> "Run `npx -y -p mcp-state-machine-test-framework mcp-sms-init`. This will setup the project, folders, templates and `mcp_config.json` automatically. Then read `.mcp_agent_rules` and start mapping using ONLY the provided MCP tools."
+> "Run `npx -y -p mcp-state-machine-test-framework mcp-sms-init`. Then start a design session using `design_wizard` (action: 'start'). Follow the wizard steps to create nodes and transitions."
 
 ---
 *Developed with ❤️ for maximum automation efficiency.*

package/index.js

@@ -78,10 +78,10 @@ export class MaquinaDeEstados {
     async loadExternalData(dataPath) {
         const fullPath = path.isAbsolute(dataPath) ? dataPath : path.join(__dirname, dataPath);
         if (!fsSync.existsSync(fullPath)) return null;
-        
+
         const content = await fs.readFile(fullPath, "utf-8");
         if (fullPath.endsWith(".json")) return JSON.parse(content);
-        
+
         if (fullPath.endsWith(".csv")) {
             const lines = content.split("\n").map(l => l.trim()).filter(l => l.length > 0);
             if (lines.length < 2) return [];
@@ -104,7 +104,7 @@ export class MaquinaDeEstados {
     async ejecutarSuite(suiteName) {
         const suite = this.suites.get(suiteName);
         if (!suite) throw new Error(`Suite '${suiteName}' no encontrada.`);
-        
+
         if (suite.state_map) {
             process.stderr.write(`\n📍 [V12.3] Pre-flight Integrity Check for: ${suite.state_map}\n`);
             // Simplified validation: Ensure the file exists and has the required structure
@@ -129,8 +129,8 @@ export class MaquinaDeEstados {
             if (typeof text !== "string") return text;
             // Enmascarar tokens de seguridad y JWTs
             return text.replace(/("securityToken"\s*:\s*")[^"]+(")/g, '$1********$2')
-                       .replace(/("token"\s*:\s*")[^"]+(")/g, '$1********$2')
-                       .replace(/eyJhbGciOi[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.?[A-Za-z0-9-_.+/=]*/g, '********[JWT_MASKED]********');
+                .replace(/("token"\s*:\s*")[^"]+(")/g, '$1********$2')
+                .replace(/eyJhbGciOi[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.?[A-Za-z0-9-_.+/=]*/g, '********[JWT_MASKED]********');
         };
 
         const runActions = async (actions, targetRes, data) => {
@@ -145,7 +145,7 @@ export class MaquinaDeEstados {
                     const executeAction = async (act) => {
                         const subRes = (act === action) ? actionRes : { action: act, status: "passed" };
                         if (act !== action) targetRes.push(subRes);
-                        
+
                         let finalAction = act;
                         try {
                             if (act.startsWith("transicion:")) {
@@ -153,7 +153,7 @@ export class MaquinaDeEstados {
                                 const mapPath = path.join(__dirname, 'maps', suite.state_map);
                                 const mapData = JSON.parse(await fs.readFile(mapPath, 'utf8'));
                                 const nodes = mapData.nodos || mapData;
-                                
+
                                 let foundAction = null;
                                 for (const node of Object.values(nodes)) {
                                     if (node.transiciones && node.transiciones[transName]) {
@@ -187,18 +187,18 @@ export class MaquinaDeEstados {
 
                                 const { client } = await this.getMcpClient(serverName);
                                 lastResult = await client.callTool({ name: toolName, arguments: toolArgs }, undefined, { timeout: 600000 });
-                                
+
                                 if (lastResult.isError && toolName !== "close_session") {
                                     throw new Error(lastResult.content?.[0]?.text || "Error desconocido en herramienta MCP");
                                 }
-                                
+
                                 if (lastResult.content) {
-                                     for (const item of lastResult.content) {
-                                         if (item.text) {
-                                             subRes.output = (subRes.output || "") + "\n" + maskSecrets(item.text);
-                                         }
-                                     }
-                                 }
+                                    for (const item of lastResult.content) {
+                                        if (item.text) {
+                                            subRes.output = (subRes.output || "") + "\n" + maskSecrets(item.text);
+                                        }
+                                    }
+                                }
 
                                 if (lastResult.content) {
                                     let base64 = "";
@@ -233,19 +233,19 @@ export class MaquinaDeEstados {
             for (const caseName of suite.tests) {
                 const testCase = this.casosPrueba.get(caseName);
                 if (!testCase) continue;
-                
+
                 let dataRows = [null];
                 if (testCase.data) {
                     if (Array.isArray(testCase.data)) dataRows = testCase.data;
                     else if (typeof testCase.data === "string") dataRows = await this.loadExternalData(testCase.data) || [null];
                 }
-                
+
                 for (let i = 0; i < dataRows.length; i++) {
                     const row = dataRows[i];
-                    const suffix = row ? ` [Iteration ${i+1}]` : "";
+                    const suffix = row ? ` [Iteration ${i + 1}]` : "";
                     const caseRes = { name: testCase.name + suffix, steps: [], status: "passed", hooks: { beforeCase: [], afterCase: [] } };
                     results.cases.push(caseRes);
-                    
+
                     try {
                         await runActions(suite.beforeCase, caseRes.hooks.beforeCase, row);
                         for (const step of testCase.steps) {
@@ -326,20 +326,20 @@ export class MaquinaDeEstados {
 
 const maquina = new MaquinaDeEstados();
 const server = new McpServer({ name: "demo-state-machine", version: "11.1.0" });
-server.tool("execute_suite", "Ejecución de Suite Completa", { 
-    name: z.string().describe("Nombre de la suite a ejecutar (ej: 'Suite_Login'). Buscará el archivo en /suites.") 
+server.tool("execute_suite", "Ejecución de Suite Completa", {
+    name: z.string().describe("Nombre de la suite a ejecutar (ej: 'Suite_Login'). Buscará el archivo en /suites.")
 }, async ({ name }) => {
     await maquina.cargar();
     const dir = await maquina.ejecutarSuite(name);
     return { content: [{ type: "text", text: `Reporte: ${dir}` }] };
 });
 
-server.tool("upsert_node", "Añadir o actualizar un nodo en el mapa de estados.", { 
-    mapName: z.string().describe("Nombre del archivo del mapa (ej: 'home_map.json'). El servidor lo buscará en la carpeta /maps."), 
-    nodeName: z.string().describe("Identificador único del nodo (ej: 'LOGIN_PAGE', 'HOME')."), 
+server.tool("upsert_node", "Añadir o actualizar un nodo en el mapa de estados.", {
+    mapName: z.string().describe("Nombre del archivo del mapa (ej: 'home_map.json'). El servidor lo buscará en la carpeta /maps."),
+    nodeName: z.string().describe("Identificador único del nodo (ej: 'LOGIN_PAGE', 'HOME')."),
     nodeData: z.object({
         transiciones: z.any().optional().describe("Objeto que define las salidas del nodo. Ej: { 'IR_A_LOGIN': { 'destino': 'LOGIN_PAGE', 'accion': 'mcp:wdio-mcp/click_element ...' } }")
-    }).passthrough().describe("Datos completos del nodo, incluyendo transiciones y metadatos.") 
+    }).passthrough().describe("Datos completos del nodo, incluyendo transiciones y metadatos.")
 }, async ({ mapName, nodeName, nodeData }) => {
     const mapPath = path.join(__dirname, 'maps', mapName);
     let map = { nodos: {} };
@@ -347,8 +347,8 @@ server.tool("upsert_node", "Añadir o actualizar un nodo en el mapa de estados."
         const content = await fs.readFile(mapPath, 'utf8');
         map = JSON.parse(content);
         if (!map.nodos) map = { nodos: map };
-    } catch (e) {}
-    
+    } catch (e) { }
+
     map.nodos[nodeName] = nodeData;
     await fs.mkdir(path.dirname(mapPath), { recursive: true });
     await fs.writeFile(mapPath, JSON.stringify(map, null, 2));
@@ -372,8 +372,8 @@ server.tool("upsert_node", "Añadir o actualizar un nodo en el mapa de estados."
     return { content: [{ type: "text", text: `Nodo '${nodeName}' actualizado. Diagrama visual regenerado en maps/${mapName.replace('.json', '.md')}` }] };
 });
 
-server.tool("inspect_framework", "Inspeccionar integridad y listar entidades del framework", { 
-    filter: z.optional(z.string()) 
+server.tool("inspect_framework", "Inspeccionar integridad y listar entidades del framework", {
+    filter: z.optional(z.string())
 }, async () => {
     const entities = { maps: [], test_cases: [], suites: [], health: [] };
     const getFiles = async (dir) => {
@@ -402,15 +402,46 @@ server.tool("inspect_framework", "Inspeccionar integridad y listar entidades del
 
     if (entities.health.length === 0) entities.health.push("✅ Estructura íntegra. Todos los vínculos son correctos.");
 
+    // Validación de integridad de Grafos (Nodos Huérfanos)
+    for (const mapFile of entities.maps) {
+        try {
+            const mapData = JSON.parse(await fs.readFile(path.join(__dirname, 'maps', mapFile), 'utf8'));
+            const nodos = mapData.nodos || mapData;
+            if (nodos && nodos["HOME"]) {
+                const reachable = new Set(["HOME"]);
+                const stack = ["HOME"];
+                while (stack.length > 0) {
+                    const current = stack.pop();
+                    const node = nodos[current];
+                    if (node && node.transiciones) {
+                        for (const t of Object.values(node.transiciones)) {
+                            if (t.destino && nodos[t.destino] && !reachable.has(t.destino)) {
+                                reachable.add(t.destino);
+                                stack.push(t.destino);
+                            }
+                        }
+                    }
+                }
+                const totalNodes = Object.keys(nodos);
+                const unreachable = totalNodes.filter(n => !reachable.has(n));
+                if (unreachable.length > 0) {
+                    entities.health.push(`⚠️ Mapa '${mapFile}': Nodos inalcanzables desde HOME: ${unreachable.join(', ')}`);
+                }
+            } else if (nodos && !nodos["HOME"]) {
+                entities.health.push(`⚠️ Mapa '${mapFile}': No tiene un nodo 'HOME' (inicio), no se puede validar el grafo.`);
+            }
+        } catch (e) { entities.health.push(`❌ Error validando grafo de '${mapFile}': ${e.message}`); }
+    }
+
     return { content: [{ type: "text", text: JSON.stringify(entities, null, 2) }] };
 });
 
-server.tool("save_test_case", "Crear o actualizar un caso de prueba.", { 
-    name: z.string().describe("Nombre identificador del test (ej: 'TC_Login_Exitoso')."), 
+server.tool("save_test_case", "Crear o actualizar un caso de prueba.", {
+    name: z.string().describe("Nombre identificador del test (ej: 'TC_Login_Exitoso')."),
     steps: z.array(z.object({
         name: z.string().optional().describe("Descripción amigable del paso (ej: 'Ingresar Usuario')."),
         action: z.string().optional().describe("Acción a realizar. Puede ser un nombre de transición del mapa o un comando mcp:wdio-mcp/...")
-    }).passthrough()).describe("Lista ordenada de pasos lógicos a ejecutar.") 
+    }).passthrough()).describe("Lista ordenada de pasos lógicos a ejecutar.")
 }, async ({ name, steps }) => {
     const fileName = name.endsWith('.json') ? name : `${name}.json`;
     const filePath = path.join(__dirname, 'test_cases', fileName);
@@ -420,8 +451,8 @@ server.tool("save_test_case", "Crear o actualizar un caso de prueba.", {
     return { content: [{ type: "text", text: `Caso de prueba '${name}' guardado correctamente.` }] };
 });
 
-server.tool("save_suite", "Crear o actualizar una suite de pruebas.", { 
-    name: z.string().describe("Nombre de la suite (ej: 'Suite_E2E_Sanity')."), 
+server.tool("save_suite", "Crear o actualizar una suite de pruebas.", {
+    name: z.string().describe("Nombre de la suite (ej: 'Suite_E2E_Sanity')."),
     state_map: z.string().describe("Archivo del mapa de estados a usar (ej: 'mob_perfecto_map.json')."),
     tests: z.array(z.string()).describe("Lista de nombres de casos de prueba a incluir en la suite."),
     beforeSuite: z.array(z.string()).optional().default([]).describe("Acciones globales antes de la suite (ej: iniciar sesión)."),
@@ -435,11 +466,71 @@ server.tool("save_suite", "Crear o actualizar una suite de pruebas.", {
     return { content: [{ type: "text", text: `Suite '${name}' guardada correctamente.` }] };
 });
 
-server.tool("init_project", "Inicializa el proyecto con carpetas y archivos de plantilla", { 
-    force: z.optional(z.boolean()).default(false) 
+server.tool("design_wizard", "Asistente paso a paso para diseñar la máquina de estados", {
+    action: z.enum(["start", "add_node", "add_transition", "save"]),
+    data: z.record(z.any()).optional().describe("Datos según la fase: { mapName }, { nodeName }, { label, destino, accion }")
+}, async ({ action, data }) => {
+    const contextPath = path.join(__dirname, 'data', '.design_context.json');
+    let context = { step: "IDLE", mapName: "", nodeName: "", transitions: {} };
+
+    try { context = JSON.parse(await fs.readFile(contextPath, 'utf8')); } catch (e) { }
+
+    if (action === "start") {
+        context = { step: "SELECT_NODE", mapName: data.mapName || "default_map.json", nodeName: "", transitions: {} };
+        await fs.writeFile(contextPath, JSON.stringify(context, null, 2));
+        return { content: [{ type: "text", text: `🧙‍♂️ Wizard Iniciado: Trabajando en '${context.mapName}'.\n\nPASO 1: ¿Qué nombre le damos al nodo? (Usa action: 'add_node')` }] };
+    }
+
+    if (action === "add_node" && context.step === "SELECT_NODE") {
+        context.nodeName = data.nodeName;
+        context.step = "ADD_TRANSITIONS";
+        await fs.writeFile(contextPath, JSON.stringify(context, null, 2));
+        return { content: [{ type: "text", text: `📍 Nodo '${context.nodeName}' identificado.\n\nPASO 2: Define una transición. (Usa action: 'add_transition' con { label, destino, accion }). Puedes llamar a esto varias veces.` }] };
+    }
+
+    if (action === "add_transition" && context.step === "ADD_TRANSITIONS") {
+        context.transitions[data.label] = { destino: data.destino, accion: data.accion };
+        await fs.writeFile(contextPath, JSON.stringify(context, null, 2));
+        return { content: [{ type: "text", text: `🔄 Transición '${data.label}' añadida.\n\n¿Quieres añadir otra o guardar? (Usa action: 'save' para finalizar)` }] };
+    }
+
+    if (action === "save" && context.step === "ADD_TRANSITIONS") {
+        const result = await server.callTool("upsert_node", {
+            mapName: context.mapName,
+            nodeName: context.nodeName,
+            nodeData: { transiciones: context.transitions }
+        });
+        await fs.unlink(contextPath); // Reset wizard
+        return result;
+    }
+
+    return { content: [{ type: "text", text: `❌ Acción no permitida en el estado actual (${context.step}).` }] };
+});
+
+server.tool("begin_design", "Iniciar una sesión de diseño guiado para una aplicación", {
+    appName: z.string().describe("Nombre de la aplicación a diseñar (ej: 'AdvantageShopping').")
+}, async ({ appName }) => {
+    const rules = `
+🎭 HAS ENTRADO EN MODO DISEÑO (SMS ARCHITECT) 🎭
+Estás diseñando la estructura para: ${appName}
+
+REGLAS CRÍTICAS DE SUPERVIVENCIA:
+1. ❌ PROHIBIDO editar archivos JSON manualmente.
+2. ❌ PROHIBIDO usar los campos 'nodes' o 'edges'. NO SOMOS UNA LIBRERÍA DE GRÁFICOS.
+3. ✅ USA EXCLUSIVAMENTE 'upsert_node' para crear o actualizar estados.
+4. ✅ ESTRUCTURA OBLIGATORIA: { "nodos": { "NOMBRE_NODO": { "transiciones": {} } } }
+5. 🔄 FLUJO: Primero propón el diseño en texto -> Pide confirmación -> Usa la herramienta.
+
+Dime qué pantalla o flujo quieres empezar a mapear para ${appName}.
+    `;
+    return { content: [{ type: "text", text: rules }] };
+});
+
+server.tool("init_project", "Inicializa el proyecto con carpetas y archivos de plantilla", {
+    force: z.optional(z.boolean()).default(false)
 }, async ({ force }) => {
     await ensureDirectories();
-    
+
     const templates = {
         'maps/template_map.json': {
             nodos: {
@@ -478,7 +569,7 @@ server.tool("init_project", "Inicializa el proyecto con carpetas y archivos de p
                 try {
                     await fs.access(fullPath);
                     continue; // Skip if exists
-                } catch (e) {}
+                } catch (e) { }
             }
             await fs.writeFile(fullPath, JSON.stringify(content, null, 2));
         } catch (e) {
@@ -486,7 +577,21 @@ server.tool("init_project", "Inicializa el proyecto con carpetas y archivos de p
         }
     }
 
-    return { content: [{ type: "text", text: "✅ Proyecto inicializado. Se han creado las carpetas y los archivos de plantilla (templates) para guiar al agente." }] };
+    return {
+        content: [{
+            type: "text",
+            text: "✅ Instalación completada con éxito.\n\nComo este es un proyecto nuevo, el siguiente paso es definir tu aplicación. Por favor, llama a la herramienta `begin_design` para empezar a mapear tus primeros estados."
+        }]
+    };
+});
+
+server.tool("framework_menu", "Panel de control para elegir entre Modo Diseño o Modo Ejecución", {}, async () => {
+    return {
+        content: [{
+            type: "text",
+            text: "🎮 **Framework Control Panel**\n\n¿Qué deseas hacer ahora?\n1. 🎨 **Modo Diseño**: Añadir o modificar nodos y mapas (Usa `begin_design`).\n2. 🚀 **Modo Ejecución**: Lanzar suites de pruebas existentes (Usa `execute_suite`).\n3. 🔍 **Auditoría**: Revisar la integridad del sistema (Usa `inspect_framework`)."
+        }]
+    };
 });
 
 async function ensureDirectories() {
@@ -501,10 +606,10 @@ async function ensureDirectories() {
     }
 }
 
-async function main() { 
+async function main() {
     await ensureDirectories();
-    await maquina.cargar(); 
-    const transport = new StdioServerTransport(); 
-    await server.connect(transport); 
+    await maquina.cargar();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
 }
 main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-state-machine-test-framework",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "High-fidelity State Machine MCP Server for autonomous E2E testing orchestration.",
   "main": "index.js",
   "type": "module",