Alterar um monorepo auto-hospedado de automação de certificados sem expor segredos

## Entender o ciclo de vida dos certificados e os segredos que o sistema guarda Trate o sistema como um produto privado e auto-hospedado que gerencia solicitação, renovação, implantação, monitoramento e notificação de certificados, além de integrações por API. Seu pipeline principal pode solicitar certificados por meio de ACME, concluir validações DNS-01, HTTP-01, por proxy CNAME ou específicas de um provedor, exportar formatos como PEM, PFX, DER, JKS e P7B e implantar em servidores, proxies, clusters, CDNs, serviços de nuvem ou painéis de controle. O sistema armazena certificados, credenciais de serviços de nuvem, informações de SSH, chaves de API e outras configurações sensíveis. Nunca exponha dados locais nem secrets em alterações de código-fonte, logs, fixtures, capturas de tela, relatórios ou metadados gerados. ## Manter separados os workspaces do monorepo e não mexer nos dados de execução Use o gerenciador de pacotes, a definição de workspace e o lockfile designados pelo repositório; não introduza lockfiles de outro gerenciador de pacotes. Se um pacote for um workspace independente de controle de versão, inspecione seu status e seu diff de dentro desse workspace e mantenha suas alterações separadas das alterações do repositório raiz. Não modifique nem inclua em commits dados de runtime, logs, resultados temporários, metadados gerados, distribuições ou manifestos de plugins exportados, a menos que a tarefa os defina explicitamente como alvo. Um diretório de dependências de runtime pode ser inspecionado em modo somente leitura quando for necessário entender um SDK instalado dinamicamente, mas ele não é código-fonte e não deve entrar no conjunto de alterações. ## Colocar cada mudança no pacote ou plugin responsável Identifique a responsabilidade antes de editar: os clientes de protocolo são responsáveis pelo comportamento de contas, pedidos e desafios; os pacotes do pipeline, pelos modelos de execução e ciclos de vida das tarefas; os módulos do servidor, por entidades, serviços, controllers, permissões e migrations; os módulos do cliente, por views, formulários, rotas e adaptadores de API; e os plugins de provedores, pelo comportamento de DNS, implantação e notificação específico do provedor. Mantenha um defeito de um único provedor no plugin desse provedor. Transfira um comportamento para o núcleo do pipeline ou para uma biblioteca compartilhada de plugins somente quando ele representar uma semântica reutilizável que deva ser consistente entre provedores. Prefira módulos, serviços, componentes e padrões de plugins consolidados a implementações paralelas. ## Usar os comandos de cada pacote sem instalar dependências extras Leia os comandos documentados antes de executar uma validação. Use os comandos próprios do pacote afetado para testes unitários, lint, formatação e build, e amplie as verificações somente quando a alteração atravessar claramente os limites entre pacotes. Não substitua uma validação por arquivo compatível por uma verificação de tipos sabidamente defeituosa nem por um script de teste provisório. Não instale dependências preventivamente. Se dependências ausentes, requisitos do terminal ou acesso à rede impedirem uma verificação necessária, interrompa essa tentativa e informe a limitação do ambiente. Para comportamentos de SDK que dependam da versão, inspecione a dependência de runtime realmente instalada e a documentação que a acompanha, em vez de confiar na memória ou em outra versão. ## Escrever código legível com etapas nomeadas e comentários que expliquem o porquê Priorize a legibilidade em vez de uma sintaxe compacta. Divida condições complexas, ternários aninhados, cadeias longas, objetos inline e chamadas de helpers em várias camadas em valores intermediários com nomes claros ou em métodos focados. Não coloque uma chamada de método diretamente dentro do argumento de outro método quando uma variável local significativa puder tornar a transição visível. Use parâmetros de objeto quando, de outra forma, um método precisaria de mais de três argumentos. Explique em comentários por que existem regras de negócio, restrições de compatibilidade, detalhes de protocolo e riscos ocultos. Mantenha a lógica pequena no local de uso, mas extraia regras de negócio, conversões de campos, verificações de permissão, seleção de repositório, propagação de transações ou cálculos recorrentes quando suas cópias precisarem permanecer sincronizadas. ## Escrever primeiro um teste que falhe e depois fazer a menor correção Adicione testes unitários focados para o comportamento principal do negócio. Em uma nova funcionalidade ou correção de defeito, comece preferencialmente por um teste que reproduza o comportamento esperado e falhe antes da implementação; depois, faça a menor alteração e execute novamente o teste do pacote. Se um teste adicionado posteriormente exigir a mudança de um comportamento estabelecido, confirme antes de alterá-lo que se trata de um defeito, e não de um requisito existente. Coloque os testes unitários puros perto do código-fonte e mantenha-os fora dos builds de produção. Use uma ferramenta apropriada de mocking de módulos para imports ESM estáticos, em vez de reestruturar o código de produção apenas para o teste. Defina explicitamente o ambiente de testes unitários do pacote e execute builds mais amplos somente quando o impacto entre pacotes os tornar necessários. ## Acompanhar mudanças de tabela com migrações SQL e passar as transações corretamente Associe cada alteração na estrutura de tabelas a uma migration SQL explícita; nunca dependa da sincronização de schema do ORM. Promova chaves temporárias de upload por meio do serviço de arquivos aprovado antes de armazená-las permanentemente e preserve o proprietário exigido e a visibilidade pública ou privada. Para propagar uma transação, passe um contexto que contenha o gerenciador de transações opcional antes do objeto de requisição e use os helpers compartilhados de repositório e transação. Não adicione contexto de transação a consultas simples nem a funções puras. Crie os predicados opcionais de tenant ou projeto com o helper canônico de consultas, para que valores null ou undefined não possam se transformar em uma condição de igualdade inválida. Evite nomes e assinaturas de métodos de serviço que entrem em conflito com métodos base herdados. Escolha nomes específicos que preservem o contrato base e tornem explícito o escopo da operação. ## Criar telas de administração com o framework CRUD e os diálogos de formulário existentes Localize a view responsável pela funcionalidade e seu módulo de API antes de editar. Use o framework CRUD aprovado para administração rotineira, busca de registros e gerenciamento por tabelas. Crie uma lista personalizada somente para apresentações leves e somente leitura, interfaces de forte interação ou casos em que esteja documentada uma incompatibilidade com o framework padrão. Grades de dados incorporadas exigem uma altura estável ou uma cadeia flex ininterrupta com elementos filhos que possam encolher. Reutilize os dicionários remotos estabelecidos para campos de identidade pesquisáveis. Uma confirmação simples pode usar um diálogo de confirmação, mas qualquer diálogo que colete campos, valide entradas ou envie valores adicionais deve usar a abstração aprovada de diálogo de formulário. Quando for conhecido que a verificação ampla de tipos ou o comando unitário do repositório é inválido, execute somente o formatador e o linter compatíveis nos arquivos de cliente alterados. ## Corrigir problemas de certificado na camada certa e proteger as chaves da conta Inspecione os plugins de provedores antes de alterar o código compartilhado do pipeline e examine o SDK realmente instalado de forma dinâmica quando o comportamento do provedor depender da versão. Antes de aplicar uma correção, determine se o problema do certificado pertence ao cliente ACME, à execução do pipeline, a um serviço do servidor, a um plugin de provedor, a um utilitário compartilhado de certificados ou ao formulário do cliente. Use uma operação de conta apenas para consulta com a chave privada da conta existente quando o cliente do protocolo puder recuperar a URL de uma conta existente sem consumir novo material de vinculação externa da conta. Se um identificador de vinculação externa da conta mudar, gere uma nova chave privada de conta vinculada a esse identificador; caso contrário, bloqueie a emissão e exija a atualização da chave da conta. Mantenha os valores de credenciais fora do código, dos logs, dos testes, dos relatórios e dos artefatos incluídos em commits. Preserve os limites de validação e autorização ao ampliar fluxos de upload, implantação, notificação ou API aberta. ## Manter configurações antigas funcionando e relatar quais verificações rodaram Ao adicionar um parâmetro de plugin, trate sua ausência nas configurações legadas armazenadas e preserve o comportamento anterior, a menos que uma migration o altere explicitamente. Não reinterprete um valor ausente como um novo modo sem uma ramificação de compatibilidade definida. Antes de concluir, inspecione o diff focado, verifique separadamente a raiz e cada workspace aninhado, execute os testes diretamente afetados e as verificações de formatação ou lint por arquivo e confirme as migrations necessárias. Garanta que dados de runtime e resultados gerados permaneçam fora do conjunto de alterações. Informe o que mudou, quais verificações foram aprovadas, quais não puderam ser executadas e por que uma validação mais ampla ficou fora do escopo.