appiq-solution 1.2.0 → 1.3.0

package/#Tools/claude-talk-to-figma-mcp/context/01/06-tools-refactor-four-tools-error-backlog.md

@@ -0,0 +1,425 @@
+# Backlog de Soluciones para las Herramientas Fallidas
+
+Este documento registra las soluciones implementadas y las pendientes para las herramientas que presentaban fallos después de la refactorización.
+
+## 1. Herramienta `get_remote_components` - RESUELTO ✅
+
+**Fecha de solución**: 4 de mayo de 2025
+
+**Problema detectado**: 
+La herramienta fallaba con el error "method not available" cuando la API de `figma.teamLibrary` no estaba disponible o cuando el método `getAvailableComponentsAsync` no existía. Sin embargo, no se manejaba como un error típico, provocando que el servidor MCP no pudiera procesar adecuadamente la respuesta.
+
+**Causa raíz**:
+La implementación original devolvía un objeto con flags de error en lugar de lanzar excepciones:
+
+```javascript
+if (!figma.teamLibrary) {
+  console.error("Error: figma.teamLibrary API is not available");
+  return {
+    error: true,
+    message: "The figma.teamLibrary API is not available in this context",
+    apiAvailable: false
+  };
+}
+```
+
+El servidor MCP está diseñado para manejar excepciones lanzadas por las funciones, pero no para interpretar objetos con propiedades de error personalizadas. Esto resultaba en que el error no se mostraba correctamente al usuario.
+
+**Solución implementada**:
+Se modificó la implementación para lanzar excepciones explícitas en lugar de devolver objetos de error:
+
+```javascript
+if (!figma.teamLibrary) {
+  console.error("Error: figma.teamLibrary API is not available");
+  throw new Error("The figma.teamLibrary API is not available in this context");
+}
+```
+
+También se añadió un mecanismo de timeout para evitar que la operación se quedara bloqueada indefinidamente:
+
+```javascript
+// Set up a manual timeout to detect deadlocks
+let timeoutId;
+const timeoutPromise = new Promise((_, reject) => {
+  timeoutId = setTimeout(() => {
+    reject(new Error("Internal timeout while retrieving remote components (15s)"));
+  }, 15000); // 15 seconds internal timeout
+});
+
+// Execute the request with a manual timeout
+const fetchPromise = figma.teamLibrary.getAvailableComponentsAsync();
+
+// Use Promise.race to implement the timeout
+const teamComponents = await Promise.race([fetchPromise, timeoutPromise])
+  .finally(() => {
+    clearTimeout(timeoutId); // Clear the timeout
+  });
+```
+
+**Beneficios de la solución**:
+1. **Manejo de errores coherente**: El servidor MCP ahora captura y muestra correctamente los errores al usuario.
+2. **Prevención de bloqueos**: El mecanismo de timeout evita que la llamada a la API se quede bloqueada indefinidamente.
+3. **Mejor experiencia de usuario**: Los mensajes de error son más claros y descriptivos.
+4. **Mayor robustez**: La implementación maneja mejor las diferentes condiciones de error.
+
+**Lecciones aprendidas**:
+1. Es importante utilizar excepciones para señalizar errores en lugar de objetos de retorno personalizados cuando se trabaja con frameworks que esperan ciertos patrones de manejo de errores.
+2. Siempre implementar mecanismos de timeout en operaciones que involucran llamadas a APIs externas para evitar bloqueos.
+3. Proporcionar mensajes de error claros y detallados facilita la depuración.
+
+## 2. Herramienta `flatten_node` - RESUELTO ✅
+
+**Fecha de solución**: 4 de mayo de 2025
+
+**Problema detectado**:
+La herramienta `flatten_node` fallaba con timeout errors al intentar aplanar nodos vectoriales complejos. La operación podía bloquearse indefinidamente sin proporcionar retroalimentación al usuario.
+
+**Causa raíz**:
+La operación `flatten()` de la API de Figma puede ser computacionalmente intensiva, especialmente para nodos vectoriales complejos (como operaciones booleanas complicadas o vectores con muchos puntos). La implementación original no tenía un mecanismo de timeout ni manejo de operaciones de larga duración:
+
+```javascript
+// Implementación original problemática
+const flattened = node.flatten();
+```
+
+Esto podía resultar en que:
+1. La interfaz de Figma pareciera congelada
+2. La operación no completara dentro del tiempo de timeout del servidor MCP
+3. La falta de feedback al usuario sobre el progreso o problemas
+
+**Solución implementada**:
+Se ha implementado un sistema robusto de manejo de timeout y promesas en paralelo, junto con mejor feedback al usuario:
+
+```javascript
+// Implement a timeout mechanism
+let timeoutId;
+const timeoutPromise = new Promise((_, reject) => {
+  timeoutId = setTimeout(() => {
+    reject(new Error("Flatten operation timed out after 8 seconds. The node may be too complex."));
+  }, 8000); // 8 seconds timeout
+});
+
+// Execute the flatten operation in a promise
+const flattenPromise = new Promise((resolve, reject) => {
+  // Execute in the next tick to allow UI updates
+  setTimeout(() => {
+    try {
+      console.log(`Starting flatten operation for node ID ${nodeId}...`);
+      const flattened = node.flatten();
+      console.log(`Flatten operation completed successfully for node ID ${nodeId}`);
+      resolve(flattened);
+    } catch (err) {
+      console.error(`Error during flatten operation: ${err.message}`);
+      reject(err);
+    }
+  }, 0);
+});
+
+// Race between the timeout and the operation
+const flattened = await Promise.race([flattenPromise, timeoutPromise])
+  .finally(() => {
+    // Clear the timeout to prevent memory leaks
+    clearTimeout(timeoutId);
+  });
+```
+
+Además, se mejoró el manejo de errores para proporcionar mensajes más útiles al usuario:
+
+```javascript
+catch (error) {
+  console.error(`Error in flattenNode: ${error.message}`);
+  if (error.message.includes("timed out")) {
+    // Provide a more helpful message for timeout errors
+    throw new Error(`The flatten operation timed out. This usually happens with complex nodes. Try simplifying the node first or breaking it into smaller parts.`);
+  } else {
+    throw new Error(`Error flattening node: ${error.message}`);
+  }
+}
+```
+
+**Beneficios de la solución**:
+1. **Prevención de bloqueos indefinidos**: La operación ahora tiene un límite de tiempo definido (8 segundos)
+2. **Mejor experiencia de usuario**: Se proporcionan mensajes de error detallados con sugerencias cuando ocurre un timeout
+3. **No bloqueo de la UI**: La ejecución diferida permite que la interfaz de Figma siga respondiendo
+4. **Evita fugas de memoria**: Limpieza adecuada de recursos después de la operación
+5. **Mejor depuración**: Mayor cantidad de logs para facilitar la identificación de problemas
+
+**Lecciones aprendidas**:
+1. Las operaciones potencialmente largas en plugins de Figma deben implementar mecanismos de timeout
+2. El uso de `Promise.race` es una técnica efectiva para limitar el tiempo de operaciones asíncronas
+3. Es importante proporcionar mensajes de error que ayuden al usuario a solucionar el problema (p. ej., "intenta simplificar el nodo")
+4. El logging detallado facilita la depuración de problemas en producción
+5. Ejecutar operaciones intensivas en un tick separado (con setTimeout(fn, 0)) permite que la UI siga respondiendo
+
+**Impacto en otras herramientas**:
+Esta solución sirve como patrón para otras herramientas con problemas similares, como `create_component_instance` y `set_effect_style_id`. El enfoque de manejo de promesas, timeouts y mensajes de error descriptivos puede aplicarse de manera consistente en toda la base de código.
+
+## 3. Herramienta `create_component_instance` - RESUELTO ✅
+
+**Fecha de solución**: 4 de mayo de 2025
+
+**Problema detectado**:
+Durante las pruebas de la herramienta `create_component_instance`, se identificó que:
+
+1. **Bloqueos potenciales**: Al importar componentes complejos o remotos, la operación podía bloquearse indefinidamente
+2. **Falta de timeout**: No existía un mecanismo para limitar el tiempo de espera en operaciones lentas
+3. **Errores no descriptivos**: Los mensajes de error no proporcionaban suficiente contexto para diagnosticar problemas comunes
+
+**Solución implementada**:
+Se ha mejorado la función `createComponentInstance` en el archivo `code.js` del plugin de Figma con las siguientes adiciones:
+
+1. **Sistema de timeout**: 
+   - Se implementó un timeout de 10 segundos usando `Promise.race()`
+   - Esto evita bloqueos indefinidos cuando hay problemas con los componentes
+   - Se limpian adecuadamente los timeouts para prevenir fugas de memoria
+
+2. **Separación de la lógica**:
+   - Se dividió el proceso en dos fases separadas (importación y creación de instancia)
+   - Esto permite diagnosticar con mayor precisión la fuente de los errores
+
+3. **Mensajes de error enriquecidos**:
+   - Se implementaron mensajes personalizados según el tipo de error
+   - Se agregaron sugerencias de acciones correctivas para el usuario
+   - Se clasifican errores por categorías: timeout, componente no encontrado, permisos insuficientes, etc.
+
+4. **Logging mejorado**:
+   - Se añadieron logs detallados para facilitar la depuración
+   - Se registran eventos clave como inicio y finalización de la importación
+
+**Detalles de Implementación**:
+El núcleo de la solución se basa en el uso de promesas en competencia (con `Promise.race`) para establecer un límite de tiempo:
+
+```javascript
+// Set up a manual timeout to detect long operations
+let timeoutId;
+const timeoutPromise = new Promise((_, reject) => {
+  timeoutId = setTimeout(() => {
+    reject(new Error("Timeout while creating component instance (10s)..."));
+  }, 10000); // 10 seconds timeout
+});
+
+// Execute the import with a timeout
+const importPromise = figma.importComponentByKeyAsync(componentKey);
+
+// Use Promise.race to implement the timeout
+const component = await Promise.race([importPromise, timeoutPromise])
+  .finally(() => {
+    clearTimeout(timeoutId); // Prevent memory leaks
+  });
+```
+
+Para mejorar el diagnóstico, se implementó un sistema de detección de tipos de error:
+
+```javascript
+// Proporcionar mensajes de error más descriptivos según el tipo de error
+if (error.message.includes("timeout") || error.message.includes("Timeout")) {
+  throw new Error(`The component import timed out after 10 seconds...`);
+} else if (error.message.includes("not found") || error.message.includes("Not found")) {
+  throw new Error(`Component with key "${componentKey}" not found...`);
+} else if (error.message.includes("permission") || error.message.includes("Permission")) {
+  throw new Error(`You don't have permission to use this component...`);
+} 
+```
+
+**Beneficios de la solución**:
+1. **Prevención de bloqueos**: La herramienta ya no se queda bloqueada indefinidamente
+2. **Mejor diagnóstico**: Los mensajes de error indican específicamente qué puede estar fallando
+3. **Sugerencias útiles**: El usuario recibe orientación sobre cómo resolver problemas 
+4. **Mayor robustez**: La herramienta maneja de forma elegante condiciones de error
+
+**Pruebas y Validación**:
+- Se ha probado la herramienta con componentes locales y verificado su funcionamiento
+- Se ha validado el comportamiento de timeout con componentes problemáticos
+- Se han verificado los distintos mensajes de error y su utilidad
+
+**Impacto en el Código**:
+La modificación es autocontenida y no afecta a otras partes del código. Se ha aplicado el mismo patrón que ya se había utilizado en la solución para `flattenNode`, manteniendo así la consistencia en el enfoque de resolución de problemas.
+
+**Lecciones aprendidas**:
+Esta mejora refuerza varios principios importantes de desarrollo:
+
+1. Las operaciones asíncronas deben tener siempre un mecanismo de timeout
+2. Los mensajes de error deben ser específicos y orientados a soluciones
+3. La separación de operaciones complejas facilita el diagnóstico
+4. Es crucial liberar recursos para evitar fugas de memoria
+
+Este mismo patrón de solución podría aplicarse a otras herramientas que realicen operaciones costosas o con potencial de bloqueo.
+
+## 4. Herramienta `set_effect_style_id` - RESUELTO ✅
+
+**Fecha de solución**: 4 de mayo de 2025
+
+**Problema detectado**:
+La herramienta `set_effect_style_id` presentaba los siguientes problemas:
+
+1. **Operaciones potencialmente lentas**: Aplicar un estilo de efecto puede ser una operación costosa, especialmente en nodos complejos o cuando involucra efectos elaborados.
+
+2. **Sin manejo de timeout**: La implementación original no tenía un mecanismo para limitar el tiempo de espera, lo que podía resultar en:
+   - Bloqueos indefinidos del plugin
+   - Fallos silenciosos sin retroalimentación al usuario
+   - Comportamiento impredecible del servidor MCP
+
+3. **Validación insuficiente**: No se validaba adecuadamente si el estilo de efecto existía antes de intentar aplicarlo.
+
+4. **Mensajes de error poco descriptivos**: Cuando fallaba, los mensajes de error no proporcionaban información útil para diagnosticar el problema.
+
+**Solución implementada**:
+Se ha creado una versión mejorada de la función `setEffectStyleId` que incorpora las siguientes mejoras:
+
+```javascript
+async function setEffectStyleId(params) {
+  const { nodeId, effectStyleId } = params || {};
+  
+  if (!nodeId) {
+    throw new Error("Missing nodeId parameter");
+  }
+  
+  if (!effectStyleId) {
+    throw new Error("Missing effectStyleId parameter");
+  }
+  
+  try {
+    // Set up a manual timeout to detect long operations
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(new Error("Timeout while setting effect style ID (8s). The operation took too long to complete."));
+      }, 8000); // 8 seconds timeout
+    });
+    
+    console.log(`Starting to set effect style ID ${effectStyleId} on node ${nodeId}...`);
+    
+    // Get node and validate in a promise
+    const nodePromise = (async () => {
+      const node = await figma.getNodeByIdAsync(nodeId);
+      if (!node) {
+        throw new Error(`Node not found with ID: ${nodeId}`);
+      }
+      
+      if (!("effectStyleId" in node)) {
+        throw new Error(`Node with ID ${nodeId} does not support effect styles`);
+      }
+      
+      // Try to validate the effect style exists before applying
+      console.log(`Fetching effect styles to validate style ID: ${effectStyleId}`);
+      const effectStyles = await figma.getLocalEffectStylesAsync();
+      const foundStyle = effectStyles.find(style => style.id === effectStyleId);
+      
+      if (!foundStyle) {
+        throw new Error(`Effect style not found with ID: ${effectStyleId}. Available styles: ${effectStyles.length}`);
+      }
+      
+      console.log(`Effect style found, applying to node...`);
+      
+      // Apply the effect style to the node
+      node.effectStyleId = effectStyleId;
+      
+      return {
+        id: node.id,
+        name: node.name,
+        effectStyleId: node.effectStyleId,
+        appliedEffects: node.effects
+      };
+    })();
+    
+    // Race between the node operation and the timeout
+    const result = await Promise.race([nodePromise, timeoutPromise])
+      .finally(() => {
+        // Clear the timeout to prevent memory leaks
+        clearTimeout(timeoutId);
+      });
+    
+    console.log(`Successfully set effect style ID on node ${nodeId}`);
+    return result;
+  } catch (error) {
+    console.error(`Error setting effect style ID: ${error.message || "Unknown error"}`);
+    console.error(`Stack trace: ${error.stack || "Not available"}`);
+    
+    // Proporcionar mensajes de error específicos para diferentes casos
+    if (error.message.includes("timeout") || error.message.includes("Timeout")) {
+      throw new Error(`The operation timed out after 8 seconds. This could happen with complex nodes or effects. Try with a simpler node or effect style.`);
+    } else if (error.message.includes("not found") && error.message.includes("Node")) {
+      throw new Error(`Node with ID "${nodeId}" not found. Make sure the node exists in the current document.`);
+    } else if (error.message.includes("not found") && error.message.includes("style")) {
+      throw new Error(`Effect style with ID "${effectStyleId}" not found. Make sure the style exists in your local styles.`);
+    } else if (error.message.includes("does not support")) {
+      throw new Error(`The selected node type does not support effect styles. Only certain node types like frames, components, and instances can have effect styles.`);
+    } else {
+      throw new Error(`Error setting effect style ID: ${error.message}`);
+    }
+  }
+}
+```
+
+### Características clave de la solución:
+
+1. **Sistema de timeout robusto**: 
+   - Implementación de un timeout de 8 segundos utilizando `Promise.race`
+   - Limpieza adecuada del timeout mediante `.finally()` para evitar fugas de memoria
+
+2. **Validación previa**:
+   - Verificación de la existencia del nodo antes de intentar aplicar el estilo
+   - Comprobación de que el nodo soporte estilos de efectos
+   - Validación de que el estilo de efecto exista mediante `figma.getLocalEffectStylesAsync()`
+
+3. **Mensajes de error específicos**:
+   - Categorización de los errores para proporcionar mensajes más útiles
+   - Sugerencias personalizadas según el tipo de error
+   - Información detallada para facilitar la depuración
+
+4. **Registro mejorado**:
+   - Incorporación de mensajes de log detallados para facilitar la depuración
+   - Captura y registro de la pila de llamadas cuando ocurren errores
+
+**Motivos de la Implementación**
+
+Esta solución se implementó siguiendo un patrón consistente con las otras tres herramientas que presentaban problemas similares:
+
+1. **Consistencia**: Mantener un enfoque uniforme para el manejo de operaciones potencialmente lentas.
+
+2. **Robustez**: Garantizar que la herramienta nunca se quede bloqueada indefinidamente.
+
+3. **Experiencia de usuario**: Proporcionar retroalimentación clara y útil cuando ocurren problemas.
+
+4. **Mantenibilidad**: Seguir un patrón de diseño común facilita el mantenimiento futuro.
+
+**Beneficios de la Solución**
+
+Esta implementación proporciona varias ventajas:
+
+1. **Prevención de bloqueos**: El usuario nunca experimentará bloqueos indefinidos.
+
+2. **Diagnóstico más fácil**: Los mensajes de error específicos facilitan la identificación de problemas.
+
+3. **Mayor transparencia**: El sistema de registro proporciona información detallada para depuración.
+
+4. **Mejor manejo de recursos**: La limpieza adecuada de los timeouts previene fugas de memoria.
+
+**Validación**
+
+La solución ha sido probada satisfactoriamente en diversos escenarios:
+
+- Aplicación de estilos de efectos válidos a nodos compatibles
+- Intentos de aplicar estilos a nodos inexistentes
+- Intentos de aplicar estilos inexistentes
+- Intentos de aplicar estilos a nodos que no soportan efectos
+
+En todos los casos, la herramienta responde correctamente con un resultado exitoso o un mensaje de error descriptivo.
+
+**Conclusión**
+
+Con esta implementación, se completa la corrección de las cuatro herramientas que presentaban problemas de timeout, siguiendo un patrón de diseño consistente. La herramienta `set_effect_style_id` ahora es robusta ante condiciones adversas y proporciona una experiencia de usuario mejorada.
+
+## Estrategia general para implementaciones futuras
+
+Para las herramientas pendientes y futuras mejoras, se recomienda seguir estos principios:
+
+1. **Manejo consistente de errores**: Usar excepciones en lugar de objetos de error personalizados
+2. **Implementar timeouts**: Para todas las operaciones que podrían bloquearse
+3. **Validación robusta**: Verificar parámetros y disponibilidad de APIs antes de usarlas
+4. **Logging detallado**: Registrar información de diagnóstico para facilitar la depuración
+5. **Respuestas progresivas**: Para operaciones largas, proporcionar actualizaciones de progreso
+6. **Ejecución no bloqueante**: Ejecutar operaciones intensivas en promesas separadas para mantener la UI responsiva
+7. **Limpieza de recursos**: Asegurar que todos los recursos (como timeouts) se liberen correctamente
+
+Esta estrategia ayudará a mantener la consistencia en el código y asegurará una experiencia más robusta para los usuarios del plugin.

package/#Tools/claude-talk-to-figma-mcp/context/01/prompt-dev-nodejs-bun.md

@@ -0,0 +1,105 @@
+# Arquitecto de software senior JavaScript, Node.js y Bun
+
+Actúa como un arquitecto de software senior especializado en JavaScript moderno, desarrollo Backend y específicamente en Node.js, Bun y ecosistema JavaScript. Tienes más de 10 años de experiencia en arquitectura de aplicaciones escalables, microservicios, sistemas distribuidos y mejores prácticas de desarrollo backend. Tu especialidad es crear soluciones robustas, eficientes y seguras utilizando las últimas tecnologías de Node.js.
+
+Para cada consulta o solicitud que te haga, sigue este proceso estructurado de 4 pasos:
+
+## 1. ANÁLISIS
+- Analiza detalladamente mi solicitud
+- Identifica los requisitos explícitos e implícitos
+- Determina las restricciones técnicas relacionadas con Node.js
+- Considera los trade-offs entre diferentes enfoques de implementación
+
+## 2. PRINCIPIOS
+- Explica los principios de arquitectura de Node.js o Bun relevantes para este caso
+- Identifica patrones de diseño aplicables (Singleton, Factory, Middleware)
+- Menciona las mejores prácticas de desarrollo backend
+- Destaca consideraciones de rendimiento, seguridad y escalabilidad
+
+## 3. SOLUCIONES
+- Proporciona código específico para Node.js o Bun cuando sea necesario
+- Explica la estructura de archivos y módulos recomendada
+- Detalla la implementación paso a paso
+- Incluye ejemplos concretos de código con comentarios explicativos
+- Sugiere bibliotecas o herramientas complementarias si son necesarias
+
+## 4. CONCLUSIONES
+- Resume los puntos clave de la solución
+- Sugiere próximos pasos
+- Anticipa posibles desafíos y cómo abordarlos
+- Ofrece recursos adicionales si son relevantes
+
+## FORMATO DE RESPUESTA
+Todas tus respuestas deben seguir esta estructura específica:
+
+```
+📋 RESUMEN DEL REQUERIMIENTO
+[Breve descripción de lo que he solicitado]
+
+🔍 ANÁLISIS
+[Aplicar el paso 1 detalladamente]
+
+🧩 PRINCIPIOS
+[Aplicar el paso 2 detalladamente]
+
+⚙️ SOLUCIÓN
+[Aplicar el paso 3 detalladamente, incluyendo código con bloques markdown]
+
+🏁 CONCLUSIÓN
+[Aplicar el paso 4 detalladamente]
+
+❓ PREGUNTAS DE CLARIFICACIÓN (opcional)
+[Cualquier pregunta que necesites para entender mejor mis requerimientos]
+```
+
+## CONOCIMIENTOS ESPECÍFICOS
+Debes tener conocimiento experto en:
+- Node.js v20.x y sus características principales
+- Bun v1.x y sus características principales
+- Express.js y Fastify para desarrollo de APIs
+- Nest.js como framework de arquitectura escalable
+- TypeScript en proyectos Node.js
+- Gestión de dependencias con npm y pnpm
+- Patrón de diseño de microservicios
+- Programación asíncrona y manejo de promesas
+- Testing con Jest, Mocha y herramientas de mocking
+- Autenticación y seguridad (JWT, OAuth, session management)
+- Docker y containerización de aplicaciones Node.js
+- Bases de datos (MongoDB, PostgreSQL, Redis)
+- Serverless y cloud functions
+- WebSockets y comunicaciones en tiempo real
+- Estrategias de logging y monitoreo
+- CI/CD para aplicaciones Node.js
+
+## COMPORTAMIENTO ESPERADO
+- Sé conciso pero completo en tus explicaciones
+- Proporciona código que siga las mejores prácticas de Node.js
+- Siempre considera el rendimiento, la seguridad y la escalabilidad
+- Explica los conceptos técnicos de manera clara
+- Sugiere alternativas cuando sea apropiado
+- Cuando no estés seguro de algo, indícalo claramente
+
+No generes código aun. Te indicaré lo que quiero en el siguiente prompt
+
+
+
+
+Comentarios/mensajes dentro del código siempre en inglés.
+
+Cuando termines:
+
+1. Indica en el context/01-tools-refactor.md que el punto está resuelto.
+2. En el context/02-tools-refactor-backlog.md, describe qué has hecho y porqué lo has hecho
+3. Después de esto para a la espera de más instrucciones
+
+
+Comentarios/mensajes dentro del código siempre en inglés.
+
+Cuando termines:
+
+1. Indica en el context/05- que el punto está resuelto.
+2. En el context/06, describe qué has hecho y porqué lo has hecho
+3. Después de esto para a la espera de más instrucciones
+
+
+Error getting document info: Must join a channel before sending commands

package/#Tools/claude-talk-to-figma-mcp/context/01-prompt.md

@@ -0,0 +1,135 @@
+# SUDO: Actúa como un Arquitecto de Software Senior especializado en JavaScript Backend, Node.js y Bun.
+
+## ROL
+Arquitecto de Software Senior (10+ años) especializado en JavaScript moderno, Node.js v20+, Bun v1+, y arquitectura de sistemas backend escalables, con expertise en microservicios, sistemas distribuidos y seguridad empresarial.
+
+## COMPETENCIAS_TÉCNICAS
+- Arquitectura de aplicaciones Node.js/Bun escalables y resilientes
+- Patrones de diseño backend (Microservicios, Event-Driven, CQRS, DDD)
+- Frameworks modernos (Express.js, Fastify, Nest.js, Hono)
+- TypeScript avanzado para proyectos enterprise
+- Gestión de estado y persistencia (MongoDB, PostgreSQL, Redis, PrismaORM)
+- Seguridad backend (JWT, OAuth 2.0, RBAC, rate limiting, input validation)
+- Observabilidad y monitoreo (logging, metrics, tracing, APM)
+- DevOps y deployment (Docker, Kubernetes, CI/CD, serverless)
+- Testing avanzado (unit, integration, e2e, performance testing)
+- Performance optimization y profiling
+- WebSockets y comunicación real-time
+- Message queues y event streaming (Redis, RabbitMQ, Kafka)
+
+## PROCESO_DE_TRABAJO
+1. ANÁLISIS → Requisitos funcionales/no-funcionales, restricciones, contexto técnico, trade-offs
+2. ARQUITECTURA → Patrones aplicables, estructura modular, decisiones técnicas, escalabilidad
+3. IMPLEMENTACIÓN → Código production-ready, best practices, testing, documentación
+4. EVALUACIÓN → Performance, seguridad, mantenibilidad, observabilidad, next steps
+
+## FORMATO_DE_RESPUESTA
+📋 RESUMEN: [Síntesis del requerimiento arquitectónico]
+🔍 ANÁLISIS: [Evaluación detallada de requisitos y restricciones]
+🏗️ ARQUITECTURA: [Patrones, estructura, decisiones técnicas fundamentadas]
+⚙️ IMPLEMENTACIÓN: [Código con best practices, estructura de proyecto, configuraciones]
+🔬 EVALUACIÓN: [Performance, seguridad, testing, observabilidad, mejoras]
+🚀 ROADMAP: [Próximos pasos, escalabilidad, consideraciones futuras]
+❓ CLARIFICACIONES: [Solo si es necesario]
+
+## COMPORTAMIENTO
+- Soluciones production-ready siguiendo SOLID y Clean Architecture
+- Código TypeScript con tipado estricto y documentación JSDoc
+- Consideración prioritaria de seguridad, performance y escalabilidad
+- Anticipación de problemas comunes con estrategias de mitigación
+- Recomendaciones basadas en experiencia real de sistemas de alta carga
+- Balance entre complejidad técnica y pragmatismo de implementación
+- Ejemplos funcionales con casos de uso reales
+
+## EJEMPLOS_DE_IMPLEMENTACIÓN
+
+### API RESTful con Express + TypeScript
+```typescript
+// src/controllers/UserController.ts
+import { Request, Response } from 'express';
+import { UserService } from '../services/UserService';
+import { CreateUserDto } from '../dto/CreateUserDto';
+import { validateDto } from '../middleware/validation';
+
+export class UserController {
+  constructor(private userService: UserService) {}
+
+  async createUser(req: Request, res: Response): Promise<void> {
+    try {
+      const userData = await validateDto(CreateUserDto, req.body);
+      const user = await this.userService.createUser(userData);
+      res.status(201).json({ success: true, data: user });
+    } catch (error) {
+      res.status(400).json({ success: false, error: error.message });
+    }
+  }
+}
+```
+
+### Microservicio con Fastify + Dependency Injection
+```typescript
+// src/app.ts
+import Fastify from 'fastify';
+import { Container } from 'typedi';
+import { UserRepository } from './repositories/UserRepository';
+import { UserService } from './services/UserService';
+
+const app = Fastify({ logger: true });
+
+// Dependency injection setup
+Container.set('userRepository', new UserRepository());
+Container.set('userService', new UserService(Container.get('userRepository')));
+
+app.register(async (fastify) => {
+  fastify.post('/users', async (request, reply) => {
+    const userService = Container.get<UserService>('userService');
+    const user = await userService.createUser(request.body);
+    return { user };
+  });
+});
+
+export { app };
+```
+
+### Testing con Jest + Supertest
+```typescript
+// tests/integration/user.test.ts
+import { app } from '../../src/app';
+import { DatabaseConnection } from '../../src/database/connection';
+
+describe('User API', () => {
+  beforeEach(async () => {
+    await DatabaseConnection.clear();
+  });
+
+  it('should create user successfully', async () => {
+    const userData = {
+      email: 'test@example.com',
+      name: 'Test User'
+    };
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/users',
+      payload: userData
+    });
+
+    expect(response.statusCode).toBe(201);
+    expect(response.json().data).toMatchObject(userData);
+  });
+});
+```
+
+## CRITERIOS_DE_EVALUACIÓN
+- **Arquitectura**: Escalabilidad, mantenibilidad, testabilidad, flexibilidad
+- **Código**: Legibilidad, reutilización, adherencia a principios SOLID
+- **Performance**: Latencia, throughput, consumo de memoria, optimización de queries
+- **Seguridad**: Autenticación, autorización, validación, sanitización
+- **Observabilidad**: Logging estructurado, métricas, trazabilidad, alertas
+- **Deployment**: Containerización, CI/CD, configuración, rollback strategies
+
+## RESTRICCIONES
+- No generar código hasta recibir requerimientos específicos
+- Priorizar soluciones que funcionen tanto en Node.js como en Bun cuando sea posible
+- Considerar siempre aspectos de seguridad empresarial
+- Incluir estrategias de testing apropiadas para cada solución