Skip to main content
Um pacote consiste em três arquivos anexados a uma release do GitHub. O comando failproofai publish gera os três a partir dos arquivos de políticas fornecidos, cria a release e faz o upload deles.

​
1. Escreva as políticas

Comece a partir de algo que já funciona, em vez de um template em branco:
O comando pergunta o nome do pacote, gera <nome>.mjs e encerra — sem rede, sem git, sem nada publicado. O arquivo gerado contém uma política que já bloqueia git push --force. Ele se recusa a sobrescrever um arquivo existente. As políticas usam a mesma API que qualquer política personalizada. Dois campos extras são relevantes para um pacote:
defaultEnabled assume o valor false quando omitido. Um failproofai policies add simples ativa apenas o que você marcou — instalar todas as políticas de um desconhecido sem supervisão não é uma decisão que o instalador deve tomar pelo usuário. Escreva quantos arquivos quiser; um por categoria facilita a leitura. Todos os arquivos do diretório que registram políticas são empacotados em um único artefato, que é o que um pacote deve ser.
O empacotamento requer bun. Sem ele, mantenha um único arquivo autocontido. De qualquer forma, o entry point publicado não deve importar arquivos locais no momento da instalação: apenas o entry point tem o digest fixado, então um pacote que buscasse arquivos vizinhos não poderia garantir honestamente que o digest cobre o que é executado — e o publish se recusa a publicá-lo em vez de entregar uma promessa que não pode cumprir.

​
2. Teste localmente primeiro

Antes que qualquer outra pessoa possa ver o pacote, aplique o arquivo nesta máquina:
Qualquer caminho, qualquer nome de arquivo. Peça ao seu agente para executar a ação que você bloqueou e observe a recusa. Nada é publicado e ninguém mais é afetado. Testar uma política cobre o restante: o caso legítimo que deve ser permitido e as entradas que a quebram.

​
3. Publique

O comando descobre onde publicar, o que empacotar e qual versão atribuir, e só pergunta quando o repositório não fornece essa informação. Em ordem, interrompendo antes de criar uma release se algo estiver errado:
  1. Encontra os arquivos de política pelo conteúdo — aqueles que importam failproofai e chamam customPolicies.add — e não pelo nome do arquivo. Assim, encontra guards.mjs e ignora um policies.mjs não relacionado. Não desce em subdiretórios, portanto fixtures de teste nunca são incluídas por acidente.
  2. Lê o repositório via git remote get-url origin, no diretório do arquivo e não no seu, e determina a versão.
  3. Encontra sua credencial: GITHUB_TOKEN, GH_TOKEN ou gh auth login. Requer apenas permissão de escrita em releases e nunca é exibida.
  4. Cria o repositório se ele não existir. Isso ocorre antes do build, então um pacote recusado na etapa seguinte pode deixar um novo repositório sem nenhuma release.
  5. Faz o build dos três assets, validando-os com as próprias regras do loader — o mesmo código que decide o que pode ser instalado na máquina de outra pessoa — para que um pacote que nunca poderia ser instalado falhe aqui, onde você ainda pode corrigi-lo.
  6. Cria ou reutiliza a release e faz o upload, substituindo assets de mesmo nome.
Os nomes dos assets são fixos — são eles que a CLI do consumidor usa para construir as URLs, sem chamadas de API e sem descoberta dinâmica. Recusado no momento do build: um id que não seja publisher/name, um nome de política contendo /, uma política que declare alwaysOn, uma description, category ou match ausente, um entry point que não registra nada e um entry point que importa arquivos locais. Substitua qualquer decisão tomada automaticamente:
--id define o id do pacote quando ele deve diferir do repositório, --tag define a tag da release, --notes substitui as notas de release geradas automaticamente — que é onde policies show --releases lê a contagem e o commit de cada release — --out escolhe onde os assets são gravados (padrão: dist-pack) e --dry-run faz o build sem publicar e não requer credencial. Qualquer pessoa pode agora instalar o pacote com failproofai policies add acme/support-agent. Consulte pacotes de políticas para fixar uma versão ou instalar apenas parte de um pacote.

​
Liste no hub de políticas

Adicione o tópico failproofai-policies ao repositório no GitHub. Não há formulário de envio nem fila de aprovação: o crawler do policy hub indexa o repositório na próxima varredura. O tópico apenas o coloca em consideração — o que efetivamente o lista é uma release cujo manifesto se verifica contra seu próprio SHA256SUMS e é parseado pelas mesmas regras que a CLI usa, que é exatamente o que failproofai publish produz.

​
Como a versão é determinada

A versão é o commit a partir do qual você está publicando — seu sha curto, doze caracteres: a1b2c3d4e5f6. Não há nada para escolher nem incrementar, e a versão identifica exatamente a origem dos bytes, então publicar a mesma fonte duas vezes produz a mesma versão. Ela é lida da árvore à sua frente, nunca das releases do repositório, então um clone recente e uma máquina air-gapped calculam a mesma resposta sem consultar o GitHub sobre o histórico. Como a versão nomeia um commit, esse commit precisa existir. Em um terminal, o publish cria um para você: inicializa um repositório quando não há nenhum e faz commit dos arquivos de política alterados antes do build. Ele se recusa — indicando --version como saída — quando executado sem terminal (um commit feito em um runner de CI não existiria em nenhum outro lugar), quando há arquivos além das políticas sem commit, ou em um checkout sem commits ainda. Uma tag no HEAD tem prioridade sobre o sha — quem taggeou v1.2.0 declarou o que essa release é. Um sha não carrega ordenação própria, então use failproofai policies show <owner>/<repo> --releases para ver qual release veio primeiro — a mais recente no topo.

​
Lançando uma nova versão

Faça commit da alteração e execute failproofai publish novamente — o novo commit é a nova versão. Os consumidores executam o mesmo failproofai policies add. Sem terminal, ou com uma flag de seleção, eles mantêm o subconjunto que haviam escolhido e uma política desativada permanece desativada; em um terminal sem flag, o seletor abre pré-marcado com seus padrões e a resposta do usuário substitui a seleção anterior. Alterar o nome de uma política é uma mudança incompatível: uma máquina que havia desativado esse nome está desativando um nome que não existe mais, e o novo nome chega com o valor que defaultEnabled define.

​
O que seus usuários estão confiando

O SHA256SUMS fica na mesma release que o artefato, então prova que os bytes são os que você publicou — mas não quem você é. Qualquer pessoa com acesso de escrita ao repositório pode escrever ambos os arquivos. A proteção dos seus usuários é que o digest é fixado no momento da instalação, então o que você enviou não pode mudar depois. Publique a partir de um repositório cujo acesso de escrita você controla, e trate uma release de pacote como a publicação de um pacote de software. O repositório também deve ser público. As instalações usam HTTPS anônimo sem credencial, então um repositório privado existente é recusado antes de qualquer build ou upload, e um repositório criado pelo publish também é público pelo mesmo motivo. --allow-private substitui esse comportamento para quem distribui os três assets por outro meio, e indica claramente que nenhum policies add poderá acessá-los. Apenas a release importa: as instalações leem releases/download/<tag>/<asset> e nunca tocam na árvore git.

​
Observe antes de aplicar

Um manifesto pode declarar "effect": "observe" — failproofai publish --effect observe é o que o define. Essas políticas são executadas e seus vereditos são registrados e descartados — nada é bloqueado. É a forma de medir uma nova regra contra tráfego real antes que ela possa interromper o trabalho de alguém.