Añadir una herramienta CLI a un descargador multiplataforma y comprobar cada binario

## Comprobar que la herramienta ofrece binarios estáticos y fijar las plataformas Usa este flujo de trabajo para añadir una herramienta de línea de comandos que se distribuya como un binario estático directamente ejecutable. Dirige los paquetes del sistema, la extracción de imágenes de contenedor, los complementos de clúster y las aplicaciones gestionadas por un entorno de ejecución a sus propias rutas de instalación. Confirma que la herramienta propuesta tenga activos de versión precompilados antes de modificar el código. Rechaza los paquetes que requieran un intérprete, un gestor de paquetes, un script de instalación o una dependencia de ejecución no declarada. Comprueba que la contribución modifique una sola herramienta, salvo que el proyecto permita explícitamente un lote más amplio. Exige cualquier aprobación de diseño o de incidencia específica del proyecto antes de la implementación cuando exista esa condición. Crea una rama específica siguiendo la convención de nombres del repositorio. Identifica el comando del instalador, el nombre público de la herramienta y su propietario y repositorio de origen. Enumera todas las combinaciones de plataformas que se espera que admita el instalador. Usa estos destinos de referencia, salvo que el proyecto defina otra matriz: - Linux en x86-64. - Linux en ARM64. - macOS en x86-64. - macOS en ARM64. - Windows en x86-64. No declares compatibilidad con 32 bits con x86 ni con ARMv6, salvo que el instalador los incluya explícitamente. Registra las combinaciones no disponibles en vez de sustituirlas silenciosamente por el artefacto de otra plataforma. ## Buscar los nombres exactos de los archivos publicados para cada sistema y arquitectura antes de programar Inspecciona la versión estable más reciente del proyecto de origen antes de escribir una plantilla de descarga. Da preferencia a una solicitud que solo obtenga la redirección del punto de acceso de la versión más reciente del proyecto de origen, para que el encabezado de ubicación revele la etiqueta de versión. No sigas la redirección cuando la propia etiqueta sea el resultado requerido. Inspecciona la lista completa de activos u otra página de versión autorizada correspondiente a esa etiqueta exacta. Evita consumir API con límites de solicitudes cuando haya metadatos públicos de versión equivalentes. Enumera todos los nombres de archivo, formatos de archivo comprimido, sistemas operativos y arquitecturas publicados. Conserva exactamente el vocabulario del proyecto de origen, incluidas distinciones como amd64 frente a x86_64 y arm64 frente a aarch64. Para cada destino previsto, registra: - Si existe un activo. - El nombre exacto del archivo del activo. - El tipo de archivo comprimido, si lo hay. - El nombre del binario dentro del archivo comprimido, si es diferente. - Cualquier variante de libc o de la cadena de herramientas que cambie la compatibilidad. Da preferencia a una variante estática portátil, como musl, cuando el proyecto la admita y la elección sea adecuada. Considera válidos los nombres de archivo de Rust que contengan términos como unknown cuando coincidan con la versión del proyecto de origen. Usa la matriz recopilada como fuente de verdad para las plantillas, las pruebas y las evidencias de la solicitud de incorporación. ## Asignar a cada plataforma su URL de descarga real, sin sustitutos Añade la herramienta mediante la estructura de definiciones establecida por el instalador y sigue un ejemplo cercano que funcione. Proporciona los campos de identidad obligatorios: nombre de la herramienta, propietario de origen, repositorio y descripción concisa. Usa una plantilla de nombre de archivo binario para los binarios simples cuyo activo de versión sea el propio ejecutable. Usa una plantilla de URL completa cuando la ubicación del activo requiera una lógica de ruta personalizada. Asigna cada sistema operativo y arquitectura admitidos a su nombre de archivo real en el proyecto de origen. Mantén separadas las constantes de arquitectura del instalador y el vocabulario de nombres de archivo del proyecto de origen. Usa una detección explícita de Windows que coincida con la representación del sistema operativo del entorno de ejecución. Los formatos de archivo comprimido admitidos deben coincidir con las capacidades de descompresión del instalador. Entre los formatos aceptados habitualmente se incluyen tar.gz, tgz, zip, bz2 y tar.xz. Cuando una combinación de plataforma no esté disponible, su URL generada debe fallar de forma clara, por ejemplo, con una respuesta de recurso no encontrado. Nunca debe recurrir a un artefacto de Linux, de otra arquitectura o de otra herramienta. Mantén explícitas las transformaciones de la etiqueta de versión, especialmente cuando se usen tanto una etiqueta con prefijo como una versión numérica. Usa las variables de plantilla existentes para el sistema operativo, la arquitectura, el nombre, la versión, el propietario y el repositorio. No fijes una versión actual en la definición de producción cuando el instalador admita la sustitución de versiones. Revisa la URL final de cada fila de la matriz antes de confiar en las pruebas. ## Separar el nombre del archivo comprimido del nombre del binario interno Trata el nombre del activo de versión y el nombre del ejecutable dentro de un archivo comprimido como datos distintos. Si un archivo comprimido contiene un ejecutable con un sufijo de plataforma, define ambos: - Una plantilla de URL que nombre el archivo comprimido descargable, incluida su extensión. - Una plantilla de binario que nombre el ejecutable extraído sin la extensión del archivo comprimido. No coloques únicamente en la plantilla de binario el nombre de un archivo comprimido con su extensión. Muchos descompresores usan la plantilla de binario para localizar el archivo extraído. Una extensión de archivo comprimido en ese campo puede activar el recurso alternativo del nombre genérico de la herramienta. Ese recurso alternativo falla cuando el archivo comprimido contiene un nombre de binario específico de la plataforma. Para un ejecutable simple y sin comprimir, normalmente basta con una plantilla de binario. Confirma la distinción inspeccionando el archivo comprimido en vez de deducirla por su nombre. Comprueba si el archivo comprimido añade un prefijo de directorio al ejecutable. Comprueba si los ejecutables de Windows requieren el sufijo exe tanto en el mapeo como en la extracción. Mantén el tratamiento de sumas de comprobación, firmas y permisos de ejecución coherente con el instalador existente. Si la extracción informa de que falta un archivo, compara estos tres nombres: - El activo descargado. - El miembro extraído del archivo comprimido. - El nombre solicitado por el instalador. Corrige el mapeo en el límite de la definición en vez de añadir un recurso alternativo amplio. ## Probar la URL de descarga de cada plataforma con una versión fija Añade una prueba unitaria específica junto a las pruebas existentes del descargador. Usa una versión fija del proyecto de origen; nunca pruebes la generación de URL con latest. Crea un caso para cada combinación publicada y admitida de sistema operativo y arquitectura. Verifica la URL esperada completa, incluidos el propietario, el repositorio, la etiqueta, el nombre de archivo, los separadores y la extensión del archivo comprimido. Incluye los alias de arquitectura específicos de cada plataforma exactamente como los publica el proyecto de origen. Prueba las transformaciones especiales de versión y los sufijos de Windows cuando estén presentes. Para las combinaciones no disponibles, prueba el comportamiento de fallo previsto del instalador cuando el marco admita esos casos. Mantén la prueba independiente de los metadatos de versión mutables. Usa la misma matriz de activos recopilada antes de la implementación. Ejecuta primero las pruebas específicas del paquete. Después ejecuta el objetivo de pruebas más amplio que exija el proyecto, cuando corresponda. Una prueba de URL superada solo demuestra la construcción de la cadena; no demuestra que el archivo descargado sea el binario correcto. ## Descargar el binario de cada plataforma y comprobar formato y arquitectura Compila el instalador antes de la verificación multiplataforma. Descarga primero el artefacto de la plataforma actual sin indicadores de anulación. Inspecciona el archivo resultante para detectar páginas de error HTML, datos comprimidos confundidos con ejecutables y archivos vacíos. Ejecuta para la herramienta el script de verificación de la matriz de plataformas del repositorio. Verifica todas las combinaciones admitidas, no solo la de la máquina que ejecuta la prueba. Usa una herramienta de identificación de archivos o un analizador de binarios equivalente para confirmar el formato y la arquitectura. Las evidencias previstas suelen incluir: - Linux x86-64 como ejecutable ELF de 64 bits para x86-64. - Linux ARM64 como ejecutable ELF de 64 bits para AArch64. - macOS x86-64 como ejecutable Mach-O de 64 bits para x86-64. - macOS ARM64 como ejecutable Mach-O de 64 bits para ARM64. - Windows x86-64 como ejecutable de consola PE32+ para x86-64. Una respuesta HTTP satisfactoria es insuficiente porque una plantilla puede descargar la plataforma equivocada. Una descompresión satisfactoria también es insuficiente porque el ejecutable interno puede estar destinado a la arquitectura equivocada. Captura la salida completa de la matriz sin eliminar los fallos ni las advertencias. Si un destino no está disponible en el proyecto de origen, verifica que el instalador falle para ese destino en vez de entregar un binario incompatible. Resuelve todas las discrepancias antes de la documentación o la aprobación. ## Regenerar el catálogo de CLI y anotar los resultados en la pull request Sigue el proceso documentado del repositorio para regenerar su catálogo de CLI. Genera el catálogo desde el instalador en vez de inventar manualmente una fila. Usa un archivo temporal del espacio de trabajo solo cuando sea necesario para sustituir el contenido de forma segura. Conserva exactamente los marcadores inicial y final del catálogo. Sustituye únicamente el contenido de la tabla generada y el recuento de herramientas asociado entre esos marcadores. No elimines el texto circundante ni las entradas no relacionadas. Confirma que la herramienta nueva aparezca una sola vez con la descripción esperada. Elimina el archivo de generación temporal después de la actualización. Prepara una descripción de la solicitud de incorporación que indique: - Las combinaciones de plataformas disponibles y no disponibles. - La etiqueta de versión autorizada y el patrón de nombres usados. - La salida completa de la verificación de plataformas, incluidos los formatos binarios. - La salida obligatoria de las pruebas de extremo a extremo o de mayor alcance, cuando corresponda. Asegúrate de que cada commit incluya la firma exigida por el repositorio. Mantén las evidencias reproducibles indicando los comandos y la versión fija. No ocultes en un resumen una plataforma ausente, una descarga fallida ni una discrepancia de arquitectura. ## Revisar el cambio y rastrear fallos de descarga o extracción Revisa por separado la elegibilidad, el mapeo, las pruebas, la documentación y las evidencias. Confirma que la herramienta sea un binario estático y que el cambio se limite al alcance aprobado. Comprueba los campos de identidad obligatorios y asegúrate de que exista al menos un mapeo de descarga válido. Compara cada rama de la plantilla con la matriz de activos autorizada. Verifica que las combinaciones no admitidas no puedan recibir el binario de otra plataforma. Confirma que las pruebas unitarias usen una versión fija y cubran todos los destinos admitidos. Exige evidencias del formato binario para cada destino declarado antes de la aprobación. Confirma que la documentación generada incluya la herramienta y conserve sus marcadores de límite. Investiga las discrepancias de URL comparando el nombre de archivo exacto del proyecto de origen y la transformación de la etiqueta. Investiga las arquitecturas incorrectas siguiendo de forma independiente las ramas del sistema operativo y de la arquitectura. Investiga los fallos de extracción comparando el nombre del archivo comprimido, sus miembros y el nombre del binario interno configurado. Investiga los fallos de ejecución volviendo a comprobar si el proyecto realmente publica un binario estático autónomo. No intentes sortear la ausencia de un activo del proyecto de origen con un sustituto incompatible. Documenta en la solicitud de incorporación las carencias legítimas del proyecto de origen. Aprueba solo cuando coincidan el código, las pruebas, los artefactos descargados, la documentación y las evidencias comunicadas.