Adicionar uma ferramenta CLI a um downloader multiplataforma e verificar cada binário

## Confirmar que a ferramenta oferece binários estáticos e definir as plataformas Use este fluxo de trabalho para adicionar uma ferramenta de linha de comando distribuída como um binário estático diretamente executável. Encaminhe pacotes do sistema, extração de imagens de contêiner, complementos de cluster e aplicações gerenciadas pelo ambiente de execução para seus próprios caminhos de instalação. Confirme que a ferramenta proposta tenha arquivos de versão pré-compilados antes de alterar o código. Rejeite pacotes que exijam um interpretador, gerenciador de pacotes, script de instalação ou dependência de execução não declarada. Verifique se a contribuição altera apenas uma ferramenta, a menos que o projeto permita explicitamente um lote mais amplo. Exija, antes da implementação, qualquer aprovação de projeto técnico ou de solicitação exigida especificamente pelo projeto, quando essa etapa de aprovação existir. Crie uma ramificação bem delimitada conforme a convenção de nomenclatura do repositório. Identifique o comando do instalador, o nome público da ferramenta e o proprietário e o repositório do projeto de origem. Liste todas as combinações de plataformas que o instalador deverá oferecer. Use estes destinos básicos, a menos que o projeto defina outra matriz: - Linux em x86-64. - Linux em ARM64. - macOS em x86-64. - macOS em ARM64. - Windows em x86-64. Não declare suporte de 32 bits para x86 ou ARMv6, a menos que o instalador os inclua explicitamente. Registre as combinações indisponíveis em vez de substituí-las silenciosamente pelo artefato de outra plataforma. ## Levantar os nomes exatos dos arquivos publicados para cada sistema e arquitetura antes de programar Inspecione a versão estável mais recente do projeto de origem antes de escrever um modelo de download. Prefira uma solicitação que obtenha somente o redirecionamento do endpoint da versão mais recente do projeto de origem, para que o cabeçalho Location revele a tag da versão. Não siga o redirecionamento quando a própria tag for o resultado necessário. Inspecione a lista completa de arquivos ou outra página oficial da versão correspondente exatamente a essa tag. Evite consumir APIs com limite de requisições quando houver metadados públicos equivalentes da versão. Enumere todos os nomes de arquivo, formatos de arquivo compactado, sistemas operacionais e arquiteturas publicados. Preserve exatamente o vocabulário do projeto de origem, inclusive distinções como amd64 em contraste com x86_64 e arm64 em contraste com aarch64. Para cada destino esperado, registre: - Se existe um arquivo da versão. - O nome exato desse arquivo. - O tipo de arquivo compactado, se houver. - O nome do binário dentro do arquivo compactado, se for diferente. - Qualquer variante de libc ou da cadeia de ferramentas que altere a compatibilidade. Prefira uma variante estática portátil, como musl, quando o projeto a oferecer e a escolha for adequada. Considere válidos os nomes de arquivo de Rust que contenham termos como unknown quando corresponderem à versão do projeto de origem. Use a matriz coletada como fonte oficial para os modelos, os testes e as evidências da solicitação de integração. ## Mapear cada plataforma para sua URL de download real, sem substitutos Adicione a ferramenta por meio da estrutura de definição estabelecida pelo instalador e siga um exemplo próximo que funcione. Forneça os campos de identidade obrigatórios: nome da ferramenta, proprietário do projeto de origem, repositório e descrição concisa. Use um modelo de nome de arquivo binário para binários simples cujo arquivo da versão seja o próprio executável. Use um modelo de URL completo quando a localização do arquivo exigir uma lógica de caminho personalizada. Mapeie cada sistema operacional e arquitetura oferecidos para o nome real do arquivo no projeto de origem. Mantenha as constantes de arquitetura do instalador separadas do vocabulário de nomes de arquivo do projeto de origem. Use uma detecção explícita do Windows que corresponda à representação do sistema operacional no ambiente de execução. Os formatos de arquivo compactado oferecidos devem corresponder aos recursos de descompactação do instalador. Os formatos normalmente aceitos incluem tar.gz, tgz, zip, bz2 e tar.xz. Quando uma combinação de plataforma estiver indisponível, a URL gerada deverá falhar claramente, por exemplo, com uma resposta de recurso não encontrado. Ela nunca deverá recorrer a um artefato do Linux, a outra arquitetura ou a outra ferramenta. Mantenha explícitas as transformações da tag da versão, sobretudo quando forem usadas tanto uma tag com prefixo quanto uma versão numérica. Use as variáveis de modelo existentes para sistema operacional, arquitetura, nome, versão, proprietário e repositório. Não fixe uma versão atual na definição de produção quando o instalador oferecer substituição de versão. Revise a URL final de cada linha da matriz antes de confiar nos testes. ## Separar o nome do arquivo compactado do nome do binário interno Trate o nome do arquivo da versão e o nome do executável dentro de um arquivo compactado como fatos distintos. Se um arquivo compactado contiver um executável com sufixo de plataforma, defina ambos: - Um modelo de URL que nomeie o arquivo compactado para download, incluindo sua extensão. - Um modelo de binário que nomeie o executável extraído sem a extensão do arquivo compactado. Não coloque apenas um nome de arquivo compactado com sua extensão no modelo de binário. Muitos descompactadores usam o modelo de binário para localizar o arquivo extraído. Uma extensão de arquivo compactado nesse campo pode acionar o uso alternativo do nome genérico da ferramenta. Esse mecanismo alternativo falha quando o arquivo compactado contém um nome de binário específico da plataforma. Para um executável simples e não compactado, normalmente basta apenas um modelo de binário. Confirme a distinção inspecionando o arquivo compactado em vez de deduzi-la pelo nome. Verifique se o arquivo compactado adiciona um prefixo de diretório ao executável. Verifique se os executáveis do Windows exigem o sufixo exe tanto no mapeamento quanto na extração. Mantenha o tratamento de somas de verificação, assinaturas e permissões de execução coerente com o instalador existente. Se a extração informar que um arquivo está ausente, compare estes três nomes: - O arquivo baixado. - O membro extraído do arquivo compactado. - O nome solicitado pelo instalador. Corrija o mapeamento no limite da definição em vez de adicionar um mecanismo alternativo amplo. ## Testar a URL de download de cada plataforma com uma versão fixa Adicione um teste unitário bem delimitado junto aos testes existentes do programa de download. Use uma versão fixada do projeto de origem; nunca teste a geração de URL com latest. Crie um caso para cada combinação publicada e oferecida de sistema operacional e arquitetura. Verifique a URL esperada completa, incluindo proprietário, repositório, tag, nome de arquivo, separadores e extensão do arquivo compactado. Inclua os nomes alternativos de arquitetura específicos de cada plataforma exatamente como o projeto de origem os publica. Teste transformações especiais de versão e sufixos do Windows quando existirem. Para combinações indisponíveis, teste o comportamento de falha previsto do instalador quando a estrutura de software oferecer esses casos. Mantenha o teste independente de metadados mutáveis da versão. Use a mesma matriz de arquivos coletada antes da implementação. Execute primeiro os testes específicos do pacote. Em seguida, execute o objetivo de testes mais amplo exigido pelo projeto, quando aplicável. Um teste de URL aprovado comprova apenas a construção da cadeia de caracteres; ele não comprova que o arquivo baixado seja o binário correto. ## Baixar o binário de cada plataforma e verificar formato e arquitetura Compile o instalador antes da verificação entre plataformas. Primeiro, baixe o artefato da plataforma atual sem opções de substituição. Inspecione o arquivo resultante para detectar páginas de erro HTML, dados compactados confundidos com executáveis e arquivos vazios. Execute o script de verificação da matriz de plataformas do repositório para a ferramenta. Verifique todas as combinações oferecidas, não apenas a da máquina que executa o teste. Use uma ferramenta de identificação de arquivos ou um analisador de binários equivalente para confirmar o formato e a arquitetura. As evidências esperadas normalmente incluem: - Linux x86-64 como um executável ELF de 64 bits para x86-64. - Linux ARM64 como um executável ELF de 64 bits para AArch64. - macOS x86-64 como um executável Mach-O de 64 bits para x86-64. - macOS ARM64 como um executável Mach-O de 64 bits para ARM64. - Windows x86-64 como um executável de console PE32+ para x86-64. Uma resposta HTTP bem-sucedida é insuficiente, pois um modelo pode baixar a plataforma errada. Uma descompactação bem-sucedida também é insuficiente, pois o executável interno pode se destinar à arquitetura errada. Capture a saída completa da matriz sem remover falhas ou avisos. Se um destino estiver indisponível no projeto de origem, verifique se o instalador falha para esse destino em vez de fornecer um binário incompatível. Resolva todas as divergências antes da documentação ou da aprovação. ## Regenerar o catálogo de CLI e registrar os resultados no pull request Siga o processo documentado do repositório para gerar novamente seu catálogo de CLI. Gere o catálogo a partir do instalador em vez de inventar manualmente uma linha. Use um arquivo temporário do espaço de trabalho somente quando necessário para uma substituição segura. Preserve exatamente os marcadores inicial e final do catálogo. Substitua apenas o conteúdo da tabela gerada e a contagem de ferramentas associada entre esses marcadores. Não remova o texto ao redor nem entradas não relacionadas. Confirme que a nova ferramenta apareça uma única vez com a descrição esperada. Exclua o arquivo temporário de geração depois da atualização. Prepare uma descrição da solicitação de integração que informe: - As combinações de plataformas disponíveis e indisponíveis. - A tag oficial da versão e o padrão de nomenclatura usados. - A saída completa da verificação de plataformas, incluindo os formatos binários. - A saída obrigatória dos testes de ponta a ponta ou mais amplos, quando aplicável. Garanta que cada commit contenha a assinatura exigida pelo repositório. Mantenha as evidências reproduzíveis, informando os comandos e a versão fixada. Não omita em um resumo uma plataforma ausente, um download com falha ou uma divergência de arquitetura. ## Revisar a mudança e rastrear falhas de download ou extração Revise a elegibilidade, o mapeamento, os testes, a documentação e as evidências como etapas de aprovação separadas. Confirme que a ferramenta seja um binário estático e que a alteração se limite ao escopo aprovado. Verifique os campos de identidade obrigatórios e garanta que exista pelo menos um mapeamento de download válido. Compare cada ramificação do modelo com a matriz oficial de arquivos. Verifique se combinações não oferecidas não podem receber o binário de outra plataforma. Confirme que os testes unitários usem uma versão fixada e cubram todos os destinos oferecidos. Exija evidências do formato binário para cada destino declarado antes da aprovação. Confirme que a documentação gerada inclua a ferramenta e preserve seus marcadores de limite. Investigue divergências de URL comparando o nome exato do arquivo no projeto de origem com a transformação da tag. Investigue arquiteturas incorretas rastreando separadamente as ramificações de sistema operacional e arquitetura. Investigue falhas de extração comparando o nome do arquivo compactado, seus membros e o nome configurado do binário interno. Investigue falhas de execução reconsiderando se o projeto realmente distribui um binário estático autossuficiente. Não contorne a ausência de um arquivo no projeto de origem com um substituto incompatível. Documente lacunas legítimas do projeto de origem na solicitação de integração. Aprove somente quando o código, os testes, os artefatos baixados, a documentação e as evidências informadas estiverem de acordo.