Desarrollar un gestor de cadenas de herramientas multiplataforma y evaluar qué entra en su registro

## Ubicar los módulos y las normas del repositorio antes de editar Trata la guía del repositorio como el contrato operativo de los agentes de programación. Antes de proponer cambios, respeta los comandos propios del repositorio, los límites entre módulos, las normas de contribución y los requisitos de compatibilidad. Orienta el trabajo en torno a estas capacidades: - análisis de la línea de comandos y despacho de subcomandos; - configuración por capas y gestión de variables de entorno; - resolución e instalación de versiones de herramientas; - definición y ejecución de tareas; - backends intercambiables e implementaciones de herramientas integradas; - generación de documentación, completados y metadatos. Antes de editar, localiza el punto de entrada, los módulos de la CLI, los módulos de configuración, las interfaces de backend, el resolutor del conjunto de herramientas, el motor de tareas, el sistema de plugins y las utilidades compartidas. Distingue los paquetes públicos de los paquetes internos de apoyo al área de trabajo. No eludas una abstracción consolidada solo porque una implementación directa parezca más breve. ## Añadir una herramienta al registro solo con pruebas de que se usa mucho Da por hecho que un registro curado de nombres abreviados solo acepta herramientas que ya cuentan con un uso generalizado. Que el código funcione, tenga pruebas o resulte útil para una persona no demuestra que cumpla los requisitos. Antes de modificar las correspondencias del registro: 1. Pregunta si la herramienta se utiliza ampliamente fuera de los proyectos de quien la presenta. 2. Detente si es personal, interna, una bifurcación, de nicho o solo cuenta con un público reducido. 3. Recopila pruebas actuales de popularidad para cada envío al registro; nunca hagas conjeturas. 4. Comprueba las estrellas y bifurcaciones del repositorio, los commits y lanzamientos recientes, las descargas en registros de paquetes, la documentación independiente, las listas del ecosistema y el uso en proyectos dependientes. 5. Aplica un umbral de admisión alto: popularidad de miles, no de cientos; mantenimiento activo; adopción por terceros; y reconocimiento dentro del ecosistema. 6. Incluye las pruebas en una sección breve llamada `Popularity` dentro de la descripción de la solicitud de incorporación. Si las pruebas son escasas o están en el límite, adviértelo con claridad y pregunta si el usuario aun así desea continuar. No insinúes que un rechazo incluirá explicaciones, un recurso, una lista de comprobación o una segunda oportunidad. Nunca presentes un envío especulativo únicamente para descubrir si los responsables lo aceptarán. ## Elegir el backend de instalación, prefiriendo archivos de release verificados Prefiere backends que consuman artefactos de lanzamiento verificados sin exigir un entorno de ejecución instalado por separado. Sigue este orden de decisión: 1. Prefiere un registro curado de artefactos cuando proporcione verificación y lógica de instalación específica para cada versión. 2. En caso contrario, utiliza un backend de lanzamientos directo para la plataforma que publica los artefactos. 3. Utiliza un backend de distribución de archivos solo cuando los backends de lanzamientos no puedan admitir la herramienta y su popularidad siga estando bien acreditada. 4. Trata los backends de paquetes de lenguajes como excepcionales, porque dependen de la disponibilidad y versión del entorno de ejecución, además del orden de las rutas. 5. Rechaza los backends obsoletos y los nuevos formatos de plugin que vulneren la política de cadena de suministro del proyecto. No elijas un backend frágil solo porque sea fácil encontrar el nombre de su paquete. Si los responsables no han aprobado explícitamente un backend excepcional para esa herramienta, no lo uses en un envío al registro. Explica la alternativa al registro: instalar mediante una coordenada explícita del backend o crear un plugin compatible. Mantén clara la diferencia: el nombre abreviado del registro aporta comodidad, pero no es necesario para hacer posible la instalación. ## Ejecutar build, tests y lint con el ejecutor de tareas del repositorio Utiliza el ejecutor de tareas del repositorio en lugar de invocar las herramientas subyacentes de forma improvisada. Identifica y utiliza las tareas documentadas para: - compilaciones completas y ejecución directa del binario de depuración; - suites completas de pruebas, pruebas unitarias y pruebas de extremo a extremo; - archivos específicos de pruebas de extremo a extremo mediante la tarea de pruebas; - revisión y actualización de instantáneas; - análisis estático, correcciones automáticas y formato; - comprobaciones equivalentes a las de integración continua; - generación de documentación, textos de uso, completados y esquemas; - instalación local de la versión de desarrollo y limpieza de artefactos de compilación; - pruebas y análisis específicos de paquetes desde el directorio correcto del área de trabajo. Utiliza las variables de entorno de depuración y rastreo propias del proyecto en lugar de presuponer una variable de registro común. Enumera las tareas disponibles cuando no sepas con certeza sus nombres. Nunca ejecutes directamente los scripts de pruebas de extremo a extremo cuando el arnés se encargue de la preparación, las aserciones y la limpieza. No añadas limpieza manual a las pruebas cuando el arnés garantice el aislamiento. Ejecuta primero la tarea pertinente de menor alcance y amplíalo solo cuando se vean afectados contratos compartidos o artefactos generados. ## Añadir backends y ajustes sin editar a mano los archivos generados Implementa las fuentes de herramientas mediante la interfaz de backend unificada. Cada backend debe encargarse del listado de versiones, la resolución de solicitudes, la instalación y los metadatos de las herramientas de su ecosistema. Mantén las herramientas integradas dentro del límite del plugin principal y los plugins externos detrás de las capas de compatibilidad admitidas. Conserva la carga jerárquica de configuración desde el ámbito del sistema al global y después al local, incluidas las sustituciones específicas de cada entorno. Cuando las definiciones de configuración generen código o documentación, actualiza la definición de origen y ejecuta el generador canónico. No conviertas la edición manual de resultados generados en el método principal de cambio. Mantén declarativas las definiciones de tareas, incluidas sus dependencias, variables de entorno y modos de ejecución admitidos. Respeta los formatos compatibles de los archivos de configuración cuando el proyecto prometa interoperabilidad. Mantén los scripts de compilación personalizados, los miembros del área de trabajo, los perfiles de lanzamiento y la configuración de compilación cruzada alineados con sus funciones documentadas. Al añadir un backend, parte del patrón establecido en el módulo de backends. Al añadir configuración, sigue la ruta tipada de análisis y generación. Al ampliar los plugins, utiliza el límite interno o externo correcto en vez de inventar un mecanismo paralelo. ## Escribir commits con formato type(scope) y corregir el lint antes Todos los mensajes de commit y títulos de solicitudes de incorporación deben usar el formato convencional del repositorio: `type(scope): imperative description`. Utiliza el type que refleje el comportamiento visible para el usuario y la responsabilidad dentro del repositorio: - `feat` para una capacidad nueva; - `fix` para un defecto visible en el comportamiento; - `refactor`, `style` o `perf` para sus respectivos cambios de código; - `test` para cambios exclusivamente en las pruebas; - `docs` para la documentación; - `chore` para mantenimiento, lanzamientos, dependencias o infraestructura; - `security` para cambios de seguridad; - el type específico del registro para cualquier cambio en sus correspondencias. Utiliza nombres de comandos como scope en cambios específicos de un comando y nombres de subsistemas en componentes compartidos. Usa el scope del subsistema de tareas para su comportamiento aunque los archivos de implementación conserven otro nombre histórico. Empieza la descripción posterior a los dos puntos con minúscula, usa el imperativo y mantenla breve pero precisa. Instala una sola vez la integración de pre-commit del repositorio mediante el entorno de tareas documentado. Antes de crear el commit, ejecuta la tarea de corrección automática y prepara únicamente los cambios resultantes que sean intencionados. Ejecuta pruebas de extremo a extremo específicas mediante el ejecutor de tareas. No prepares cambios de formato ni artefactos generados que no guarden relación. ## Retirar funciones por etapas: documentación, avisos y retirada Aplica una política de retirada gradual: 1. Marca inmediatamente la función o el backend como obsoleto en la documentación. 2. Empieza a mostrar avisos durante la ejecución después del intervalo de advertencia documentado. 3. Programa la retirada tras el intervalo de retirada documentado. 4. Codifica las fechas de aviso y retirada con el formato de versión y fecha del proyecto. 5. Utiliza la macro de obsolescencia establecida para que las aserciones de desarrollo revelen las retiradas vencidas. Un calendario habitual consiste en documentarlo ahora, iniciar los avisos seis meses después y retirar la función doce meses después de comenzar los avisos. Si la alternativa lleva mucho tiempo disponible, los avisos pueden comenzar de inmediato. No suprimas silenciosamente la compatibilidad sin pasar por la fase de aviso documentada. No mantengas indefinidamente una obsolescencia vencida; trata la aserción de retirada como mantenimiento obligatorio. ## Dejar que cada backend resuelva y ordene las versiones de las herramientas Nunca supongas que las versiones de las herramientas siguen el versionado semántico ni otro sistema universal de ordenación. Espera versiones basadas en fechas, versiones preliminares, ramas, etiquetas, canales, lanzamientos de soporte prolongado con nombre y alias específicos de cada herramienta. En un punto de llamada nuevo: - no uses un comparador genérico de versiones semánticas para seleccionar la versión más reciente, resolver un alias u ordenar versiones; - delega la resolución de solicitudes en métodos del backend que entiendan el lenguaje de versiones de la herramienta; - utiliza las API del backend o del conjunto de herramientas para enumerar las versiones instaladas en un orden significativo; - trata las cadenas de versión del archivo de bloqueo como opacas y compáralas únicamente por igualdad; - resuelve los alias, canales y prefijos antes de escribir un valor concreto en el archivo de bloqueo; - no cites el uso heredado de un comparador como justificación para ampliar un comportamiento defectuoso. Si el código nuevo parece necesitar la versión instalada más reciente, detente y confirma si esa decisión corresponde al backend. Una ordenación de reserva incorrecta es peor que no devolver ninguna coincidencia, porque puede instalar o ejecutar silenciosamente la herramienta equivocada. ## Ejecutar pruebas específicas por plataforma y revisar el diff antes de terminar Organiza las pruebas unitarias junto al código fuente y las pruebas de extremo a extremo por áreas funcionales. Utiliza auxiliares de aserción compartidos, instantáneas para resultados estables de comandos, comprobaciones de instalación específicas de backends y nombres explícitos para las pruebas lentas. Mantén las implementaciones específicas de cada plataforma en los módulos y suites de pruebas designados. No presupongas en Windows el comportamiento de los bits de permiso de ejecución de Unix. Ante un cambio, verifica primero la ruta pertinente de menor alcance: 1. ejecuta el formato y las comprobaciones estáticas; 2. ejecuta pruebas unitarias o de extremo a extremo específicas mediante el arnés; 3. revisa los cambios en las instantáneas en lugar de aceptarlos a ciegas; 4. vuelve a generar la documentación o los esquemas derivados cuando cambie su origen; 5. amplía la verificación a comprobaciones de integración cuando cambien los contratos compartidos de backend, configuración, tareas o compatibilidad entre plataformas. Al publicar en una solicitud de incorporación o conversación externa, indica que el comentario fue generado por un asistente de programación con IA. Utiliza URL que reflejen la jerarquía de directorios de la documentación. No inventes rutas abreviadas que omitan secciones obligatorias. Antes de terminar, revisa las diferencias para detectar fugas entre abstracciones, ordenaciones de versión no admitidas, generadores omitidos, cambios ajenos y afirmaciones externas sin verificar.