Shangshui0302/some-NixOS-skills

Desenvolvimento de Pacotes Nix

LEI DE FERRO: NÃO ALTERE UMA EXPRESSÃO DE PACOTE ATÉ QUE AS INTERFACES ALVO DO NIXPKGS E AS EVIDÊNCIAS DE FONTE/RELEASE UPSTREAM SEJAM REGISTRADAS; UMA CONSTRUÇÃO SEM ESSA EVIDÊNCIA NÃO É UM RESULTADO DE EMPACOTAMENTO REPRODUTÍVEL.

Bandeiras vermelhas — retorne à etapa de evidência se alguma aparecer:

• Um builder foi selecionado a partir de um único arquivo marcador ou memória isolada.
• Um canal flutuante, resultado de registro ou URL "mais recente" é a única evidência de fonte.
• Um hash, wrapper, entrada de desktop ou dependência de tempo de execução foi adivinhado.
• nix develop é bem-sucedido, mas a derivação, o layout de saída ou o executável não foram construídos.
• Uma dry-build bem-sucedida é relatada como um teste de runtime implantado ou ativo.

Limite de escopo

Esta habilidade possui a expressão do pacote, suas entradas de construção, contrato de saída e integração de flake ou overlay voltada ao pacote. Trate os módulos NixOS/Home Manager como consumidores: inspecione sua interface de pacote e faça dry-build deles quando estiver no escopo, mas deixe a configuração do sistema e ativação para nixos-ecosystem.

Quando a solicitação visa o processo de manutenção upstream NixOS/nixpkgs—como classificar uma atualização ou quebra, adotar um pacote, verificar dependentes afetados, ou preparar um PR nixpkgs—use nixpkgs-maintainer. Se ambos estiverem envolvidos, esta habilidade fornece evidências de derivação e a habilidade de mantenedor possui o fluxo de trabalho upstream.

Lista de verificação de progresso

Copie esta lista de verificação nas notas de trabalho e marque-a conforme a tarefa avança:

• Passo 0: Carregar política do repositório e definir escopo ⚠️ OBRIGATÓRIO
  • Encontre AGENTS.md, regras de contribuição, arquivos sujos, consumidores do pacote e o comportamento observável solicitado.
  • Classifique a tarefa como adicionar, atualizar, reparar ou revisar.
  • Identifique se a expressão reside em um repositório de pacotes, arquivo independente, flake, overlay ou árvore nixpkgs.
• Passo 1: Passar pela verificação de atualidade ⛔ BLOQUEANTE
  • Registre a revisão nixpkgs alvo de flake.lock, uma entrada de repositório de pacote fixada ou o checkout nixpkgs; declare o fallback quando nenhum existir.
  • Inspecione a interface do builder/helper fixada e compare com a documentação oficial atual.
  • Relate deriva e impacto de migração; nunca aplique silenciosamente uma API mais nova a um lock mais antigo.
• Passo 2: Coletar evidências de fonte e pacote ⚠️ OBRIGATÓRIO
  • Pesquise a árvore alvo, entrada relevante do nixpkgs, overlays e helpers existentes em busca de um pacote ou implementação existente.
  • Verifique tag/commit upstream, comandos de construção, CI, licença, plataforma, artefato, nome do executável e layout de instalação.
  • Escolha a rota mais restrita: fonte, ELF pré-construído, AppImage, Electron/ASAR, dados, fonte/tema ou plugin.
• Passo 3: Apresentar o plano mínimo ⚠️ OBRIGATÓRIO para edições não triviais
  • Declare arquivos, dependências, riscos, comandos de verificação e o que permanecerá não verificado.
  • Pergunte antes de edições destrutivas, instalação, ativação do sistema, commit, push ou criação de PR.
• Passo 4: Implementar a menor derivação
  • Fixe pname, version, fonte/revisão e hashes SRI; use pname/version consistentemente em URLs e nomes de arquivo.
  • Use o builder mais restrito do nixpkgs e fases padrão; fases personalizadas devem executar seus hooks correspondentes.
  • Separe ferramentas de construção, bibliotecas de link/runtime, ferramentas de teste e comandos fornecidos por wrapper.
  • Complete a integração GUI como uma unidade: wrapper, entrada de desktop, ícone, Exec e flags de runtime.
  • Preserve ou exponha a superfície de pacote existente do alvo—saída do flake, overlay ou atributo de pacote—apenas quando estiver no escopo.
• Passo 5: Verificar em camadas ⚠️ OBRIGATÓRIO
  • Analise, avalie/verifique, construa, inspecione a saída do store e execute um teste de fumaça seguro.
  • Execute dry-build do sistema apenas quando o pacote estiver integrado ao NixOS/Home Manager.
  • Mantenha status de construção, teste de fumaça, dry-build e pós-ativação/ativo separados.
• Passo 6: Relatar e manter
  • Relate evidências, arquivos alterados, hashes, verificações, bloqueadores e o próximo passo manual exato.
  • Para atualizações, re-verifique changelog, lockfiles, licença, layout do artefato e todos os hashes.
  • Adicione um script de atualização apenas após o caminho de atualização ser comprovado estável e determinístico.

Verificação de atualidade

Carregue references/freshness-and-evidence.md antes de selecionar um builder ou escrever um novo hash. Use gh para investigações no GitHub. Prefira a fonte nixpkgs fixada para fatos de API e use a documentação oficial atual do Nixpkgs/nix.dev para detectar mudanças no processo. Quando eles discordarem, pause e explique se a mudança é compatível com o lock, requer uma atualização de lock ou deve permanecer uma exceção documentada.

Roteamento de builder e implementação

Carregue apenas a seção relevante de references/builder-routing.md após a etapa de evidência. Não adicione um conjunto amplo de dependências para esconder uma falha de fase desconhecida. Prefira uma construção de fonte quando for mantível; use um binário de release ou AppImage apenas quando a rota de fonte upstream não estiver disponível ou for materialmente menos confiável.

Para fases personalizadas buildPhase, checkPhase ou installPhase, preserve os correspondentes runHook preX e runHook postX. Para código nativo pré-construído, registre a proveniência e inspecione a arquitetura, interpretador, bibliotecas NEEDED e licenças de componentes empacotados.

Validação

Carregue references/validation.md para a matriz de tipo de pacote e verificações de saída. Adapte as seguintes verificações para a superfície de pacote alvo:

nix-instantiate --parse path/to/package.nix
nix flake check path:. --no-build       # quando o alvo expõe um flake
nix build path:.#pname -L --no-link --print-out-paths  # use o nome de saída alvo
git diff --check

Se o pacote estiver conectado a uma configuração NixOS/Home Manager, também execute:

nixos-rebuild dry-build --flake path:.

Use scripts/validate-skill.py para verificar este repositório de habilidade em si. É um lint determinístico, não um substituto para construir o pacote alvo.

Quando o usuário pedir para "executar validação" sem nomear um consumidor, por padrão realize evaluação do pacote, construção, inspeção de saída e um teste de fumaça seguro. Adicione uma construção a seco de NixOS/Home Manager ou outro consumidor apenas quando esse consumidor estiver no escopo.

Atualizações e manutenção de atualidade

Carregue references/update-policy.md para atualizações repetidas. Fixe entradas de fonte e documentação, torne as verificações de atualização explícitas e mantenha o trabalho automático como somente leitura por padrão. Um job automatizado pode abrir uma mudança de atualização revisável após as verificações passarem; ele não deve reescrever silenciosamente uma habilidade, trocar um sistema, commitar ou enviar.

Quatro formatos concretos de solicitação

Carregue references/examples.md quando a solicitação for ambígua. Os formatos suportados são: adicionar um pacote a um repositório de pacotes, expressão independente, flake ou overlay; atualizar uma derivação existente e renovar hashes de fonte/dependência; reparar um pacote pré-construído/AppImage, Electron, fonte/tema ou plugin; e integrar um pacote através de um flake ou overlay existente para um consumidor.

Anti-padrões

• Não use o sucesso de nix develop como prova de que nix build funciona.
• Não escolha um builder apenas a partir de Cargo.toml, package.json ou uma dependência adivinhada.
• Não baixe dependências online durante uma construção com sandbox (cargo fetch, npm install, pip install e similares).
• Não use URLs de fonte flutuantes, branches mutáveis, hashes de estilo antigo ou literais de versão duplicados em uma expressão.
• Não esconda bibliotecas ausentes com autoPatchelfIgnoreMissingDeps, um wrapper FHS padrão ou uma lista buildInputs superdimensionada.
• Não afirme que comportamento de desktop, IPC, reprodução, Wayland ou compositor foi testado quando apenas a derivação construiu.
• Não trate verificações de expressão de pacote como integração nixpkgs ou revisão de PR; use nixpkgs-maintainer para esse fluxo de trabalho upstream.
• Não execute nixos-rebuild switch, commit, push, exclua arquivos ou crie um PR sem autorização explícita.

Formato de entrega

Retorne um relatório de evidências compacto:

1. Escopo e rota — repositório alvo/superfície pública, tipo de tarefa, tipo de pacote e por que este builder foi escolhido.
2. Evidências — revisão/API nixpkgs fixada, revisão/artefato/licença upstream e hashes relevantes.
3. Alterações — expressão do pacote, superfície do flake ou overlay, consumidores e documentação.
4. Verificação — análise, verificação do flake, construção, saída/teste de fumaça, dry-build e status ativo separadamente.
5. Próxima ação — comando manual exato ou decisão do usuário ainda necessária.

Nunca chame um pacote de "pronto" enquanto uma verificação obrigatória estiver faltando; rotule o bloqueador e o menor próximo experimento.