🛡️O Guardião Inviolável · o CI que revisa cada mudança antes que ela toque seus usuários

O momento · quando a necessidade aparece

No começo você constrói sozinho. Muda algo, atualiza a tela, vê que funciona, e pronto. Não há risco: o único que sofre com um erro é você, na sua própria máquina, e você conserta em dois minutos. Essa etapa é um paraíso — e também uma armadilha, porque você se acostuma a achar que "se funciona na minha tela, está tudo bem".

O momento muda no dia em que outra pessoa depende do seu app. O primeiro usuário que se cadastra. O cliente que já paga. O colega que também mexe no código. A partir daí, cada mudança que você sobe já não afeta só você: pode quebrar o app de gente real, ou pior, vazar os dados delas. E aqui está o problema — você já não vê todas as mudanças uma por uma. Você pede algo à IA, ela mexe em 8 arquivos, você lê 2, aprova, e sobe. Naqueles 6 que você não leu pode estar o desastre.

A dor · de onde ela sai e por que dói tanto

A dor não é dramática de cara. Não é um filme de hackers. É mais uma série de acidentes pequenos que, somados, saem caro. E todos nascem do mesmo lugar: a IA em modo construtor é otimista. Ela está pensando em fazer a função nova funcionar, não nas mil formas em que essa mudança pode quebrar outra coisa. É a natureza dela — e também a sua quando você está empolgado construindo.

O acidente mais caro é a chave secreta vazada. Você pede à IA para conectar um serviço, e para "que funcione rápido" ela cola a sua chave de API direto num arquivo. Você não percebe, aprova, sobe para o GitHub. Essa chave agora é pública. Há bots que escaneiam o GitHub 24 horas por dia procurando exatamente isso — podem encontrá-la em minutos e começar a gastar seu dinheiro ou entrar nos seus sistemas. Não é um ataque sofisticado: é um descuido que a máquina de outra pessoa recolheu do chão, como quem pega uma carteira que caiu do seu bolso sem você notar.

O segundo é o buraco no banco de dados. Uma mudança que, sem querer, deixa uma tabela dos seus usuários acessível para qualquer um, ou cria uma função com permissões que não deveria ter. Não dá para ver. O app continua funcionando idêntico. Mas você acabou de deixar uma janela aberta que ninguém vai fechar até alguém encontrá-la — e aí já é tarde.

O terceiro é o mais comum e menos glamouroso: você quebrou algo que antes rodava. Consertou o botão A e sem perceber desconectou o botão B. No seu teste rápido você só mexeu no A, então não viu. O usuário que usava o B se depara com o app quebrado. Em programação isso tem nome — regressão — e é 80% da dor real do dia a dia.

E o que acontece se você NÃO fizer isso? Nada… por um tempo. Essa é a armadilha. Funciona sem guardião por semanas, você se confia, e bem quando o projeto começa a importar de verdade — quando já há usuários, dinheiro, ou reputação em jogo — chega o acidente que teria levado 30 segundos para evitar. O guardião é um seguro barato contra um dia muito caro.

Os 7 inspetores · o que cada um revisa

O guardião não é um bloco mágico: são 7 revisões concretas que rodam automaticamente em cada mudança. Se as 7 passam, você vê um check verde e a mudança pode seguir. Se UMA só falhar, fica vermelho e a mudança fica bloqueada até você consertar. Simples assim, rigoroso assim. Vamos uma por uma, na ordem em que rodam.

1 · Gitleaks — você meteu uma chave secreta por acidente? Escaneia toda a mudança procurando coisas que pareçam credenciais: chaves de API, senhas, tokens. Se encontrar algo com cheiro de segredo, para na hora. É o inspetor que te salva do acidente mais caro de todos, e por isso roda entre os primeiríssimos — antes até de instalar qualquer coisa, sobre a árvore limpa do git, para que essa chave não avance nem mais um passo rumo ao repositório público.

2 · Portão de segurança (Supabase advisors) — esta mudança abriu um buraco no banco de dados? É o inspetor chefe, e por isso roda primeiro entre os que revisam seu código. Ele pergunta ao Supabase diretamente: alguma tabela de usuários ficou sem seu cadeado (RLS)? alguém criou uma função com permissões perigosas? foi concedido um acesso que não deveria? Se a resposta for sim, bloqueia. Este é o que protege os dados dos seus usuários de um descuido silencioso.

3 · Type-check — os tipos batem? Na programação moderna, cada dado tem um "tipo" (isto é um número, isto é um texto, isto é uma data). Este inspetor confirma que você não está, por exemplo, somando um texto com uma data. Caça uma família enorme de bugs antes de o app sequer iniciar — erros que, se não, apareceriam na cara do usuário no pior momento.

4 · Lint — o código está limpo? O linter é o inspetor de maus hábitos: variáveis que são declaradas e nunca usadas, código morto, padrões que se sabe que causam problemas. Não é estética por capricho — o código sujo é onde os bugs se escondem. Um linter obriga a manter a casa arrumada para que a sujeira de verdade fique visível.

5 · Format — o formato é consistente? Que todo o código tenha a mesma aparência: mesmos espaços, mesmas aspas, mesmo estilo. Parece mania, mas é idioma comum. Quando várias pessoas (ou várias sessões de IA) mexem no mesmo projeto sem um formato combinado, cada mudança mistura o que você fez com um enxame de aspas trocadas e indentações reordenadas — e você já não distingue a ideia do ruído. O inspetor impõe o mesmo dialeto para todos, de uma vez por todas, assim ninguém precisa discutir isso nunca.

6 · Tests — o que antes funcionava ainda funciona? Este é o que caça as regressões, a dor #3 lá de cima. São testes automáticos que verificam se as funções-chave continuam dando o resultado correto. Você consertou o botão A; os testes confirmam que o B, o C e o D continuam rodando. É o inspetor que te deixa fazer mudanças grandes sem medo, porque você sabe que se quebrar algo, ele te avisa na hora.

7 · Build — compila de verdade? O último inspetor monta o app do zero, como se fosse ser publicado. Porque uma coisa é "funcionar no seu computador" e outra é conseguir ser construído limpo desde o início. Se o build falhar aqui, na porta, é infinitamente melhor do que falhar em produção com usuários olhando uma tela em branco.

O custo · por que isto é praticamente de graça

A gente esperaria que um guardião de nível empresa custasse dinheiro. Não. Este custa ~$0 e adiciona uns ~15 segundos por revisão. Detalhamento honesto: os advisors do Supabase são grátis. O GitHub Actions (o motor que roda os inspetores) te dá 2.000 minutos grátis por mês em repositórios privados — e é ilimitado e grátis em repositórios públicos. Uma revisão das 7 leva segundos, então com 2.000 minutos você faz milhares de revisões por mês sem pagar um centavo.

O repo · o que você vai copiar

Você não precisa inventar nada. Todo o guardião está empacotado num repositório público, verificado, pronto para copiar. São 4 arquivos que você leva para o seu projeto, mais um guia de instalação em espanhol, passo a passo. Está escrito em JavaScript puro e não depende de nada estranho.

O protocolo de instalação · uma única vez, para sempre

Aqui está a parte boa: você instala uma vez e ele cuida de você para sempre. Não há manutenção diária, não precisa lembrar de rodar. Ele vive no seu repositório e dispara sozinho a cada mudança. A instalação são 6 passos, e o prompt mestre lá embaixo cola isso para a sua IA para que ela os faça junto com você. Primeiro olhe o mapa completo para entender o que vai acontecer.

// Passo 3: o script que você adiciona ao seu package.json (na seção "scripts")
{
  "scripts": {
    "db:advisors:gate": "node scripts/supabase-advisors-gate.mjs"
  }
}

# Os 2 secrets do passo 5 são criados no GitHub, NÃO no código:
# Repositório → Settings → Secrets and variables → Actions → New secret
#
#   SUPABASE_PROJECT_REF   → o ref do seu projeto (muda por projeto)
#   SUPABASE_ACCESS_TOKEN  → seu token de conta (o mesmo para todos os seus projetos)
#
# O portão foi feito para se pular sozinho (com aviso) se esses secrets faltarem,
# então nunca quebra um projeto que ainda não os tem configurados.

O prompt mestre · cole para a sua IA e deixe ela instalar para você

Este é o único prompt que você precisa. Você o cola no seu agente de código (Claude Code, Cursor, ou o que você usar) parado dentro do seu projeto, e ele te guia pelos 6 passos, ajustando os 3 dados por você e explicando cada movimento. Preencha os [colchetes] com o que é seu antes de enviar.

Quero montar neste projeto um guardião de integração contínua (CI) que revise cada mudança antes que ela chegue à produção. O template está no repo público github.com/MentexDev/NeuralOS-CI-Blindaje e traz 7 inspetores: Gitleaks (segredos), portão de segurança dos Supabase advisors (que roda PRIMEIRO entre os que revisam o código), type-check, lint, format, tests e build. Se UM falhar, a mudança é bloqueada.

Contexto do meu projeto:
- Banco de dados: Supabase.
- Gerenciador de pacotes: [npm / pnpm / yarn].
- Nome do meu pacote (o "name" do package.json): [nome].

Me guie passo a passo, sem que eu precise saber programar, e nesta ordem:

1. Traga os 4 arquivos do template (backend-ci.template.yml, gitleaks.toml.template, scripts/supabase-advisors-gate.mjs e scripts/supabase-advisors-allowlist.json) e coloque cada um onde deve ficar. O workflow deve ficar em .github/workflows/ SEM o sufixo .template.

2. Procure nos arquivos os 3 marcadores <<<CAMBIAR>>> e substitua pelos dados reais do meu projeto (pasta, caminhos, nome do pacote). Me mostre exatamente o que você mudou em cada um.

3. Adicione ao meu package.json o script "db:advisors:gate": "node scripts/supabase-advisors-gate.mjs" sem apagar meus scripts existentes.

4. Me explique EXATAMENTE onde eu encontro meu PROJECT_REF no Supabase, e como eu gero meu ACCESS_TOKEN de conta.

5. Me diga passo a passo como criar os 2 secrets no GitHub (SUPABASE_PROJECT_REF e SUPABASE_ACCESS_TOKEN). Me lembre que eles NUNCA devem ir dentro de um arquivo do projeto, só nos Secrets do GitHub.

6. Me lembre de ativar "Leaked Password Protection" no Supabase (Auth → Settings).

No final:
- Me dê o comando exato para fazer commit e push desses arquivos, e me diga o que eu deveria ver na aba de checks do GitHub (os 7 inspetores rodando, e qual roda primeiro).
- Se algum inspetor ficaria vermelho com meu projeto do jeito que ele está agora (por exemplo, não tenho tests, ou meu código tem erros de tipo), me avise ANTES e me diga a forma mais simples de deixá-lo verde honestamente, sem desativar o inspetor.

O hábito · onde isto vive no seu dia a dia

A beleza do guardião é que ele não exige disciplina da sua parte. Não é um hábito que você tenha que lembrar, tipo "beber água" ou "fazer exercício". Uma vez instalado, ele dispara sozinho toda vez que você sobe uma mudança. Seu único trabalho é olhar a cor: verde, siga; vermelho, conserte o que o inspetor aponta antes de continuar.

O momento em que você o vive é bem na hora de subir uma mudança para o GitHub (ou de abrir um "pull request", se você trabalha com branches — veja o recurso de branches paralelas). Aí o GitHub lança os 7 inspetores automaticamente. Em segundos você tem o veredito. Se você trabalha com a IA, este é o ponto onde o otimismo dela de construtora encontra um auditor que não se empolga: a máquina revisa a frio o que a IA construiu a quente.

Os caminhos mais fáceis · o que você faz e o que a máquina faz

Para deixar clarííssimo onde você põe a mão e onde não: a instalação você faz UMA vez (com o prompt lá de cima, sua IA te acompanha). Depois, tudo é automático. Esta é a divisão real de esforço.

Fechamento · um guardião que não dorme

Construir com IA é rápido e viciante, e essa velocidade é justamente o que a torna perigosa: você vai tão rápido que não vê tudo o que sobe. O guardião não te freia — ele te deixa ir rápido com uma rede embaixo. Cada mudança passa por 7 inspetores em segundos, e se algo cheira mal, ele para antes de tocar um só usuário. Custa zero, se monta uma vez, e te dá algo que o dinheiro normalmente não compra: dormir tranquilo sabendo que nada quebrado chega à produção por descuido.