Publicar um pack - Failproof AI

Um pack consiste em três arquivos anexados a uma release do GitHub. failproofai pack build gera os três a partir de um arquivo de política que você já possui.

1. Escreva as políticas

Um único arquivo, usando a mesma API de qualquer política personalizada. Dois campos extras são importantes para um pack:

import { customPolicies, deny, allow } from "failproofai";

customPolicies.add({
  name: "block-refunds",
  description: "Refunds above the approved limit need a human",
  category: "Billing",        // groups it, and is what --category selects on
  defaultEnabled: true,       // switched on by a plain `pack add`
  match: { events: ["PreToolUse"], tools: ["Bash"] },
  fn: async (ctx) =>
    String(ctx.toolInput?.command ?? "").includes("refund")
      ? deny("Refunds need a human. Ask before running this.")
      : allow(),
});

defaultEnabled assume o valor false quando omitido. Um failproofai pack 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.

O entry deve ser um único arquivo autocontido. Apenas o entry tem seu digest fixado, então um pack que importa arquivos locais não poderia honestamente afirmar que o digest cobre o que é executado. Faça o bundle primeiro (esbuild, bun build, rollup) e construa o pack a partir do bundle — pack build rejeita uma importação local em vez de fazer uma promessa que não pode cumprir.

2. Construa os assets da release

failproofai pack build ./policies.mjs \
  --id acme/support-agent \
  --version 1.0.0 \
  --out ./dist-pack

O comando gera três arquivos e valida todas as políticas com as próprias regras do loader primeiro — assim, um pack que nunca poderia ser instalado falha aqui, onde você pode corrigir:

Arquivo	O que é
`failproofai-pack.json`	O manifest: id, versão, efeito e uma entrada por política
`failproofai-pack.mjs`	Seu entry, literalmente
`SHA256SUMS`	`<sha256> <filename>` para os outros dois

Rejeitado no momento do build: um id que não segue o formato publisher/name, um nome de política contendo /, uma política declarando alwaysOn, description, category ou match ausentes, um entry que não registra nada e um entry que importa arquivos locais.

3. Anexe os arquivos à release

Crie a tag da release com a mesma versão que você usou no build e anexe os três arquivos como assets da release:

gh release create 1.0.0 \
  ./dist-pack/failproofai-pack.json \
  ./dist-pack/failproofai-pack.mjs \
  ./dist-pack/SHA256SUMS

Agora qualquer pessoa pode instalá-lo:

failproofai pack add acme/support-agent

Os nomes dos assets são fixos — são eles que a CLI do consumidor usa para construir suas URLs, sem chamada de API nem descoberta automática.

Lançando uma nova versão

Faça o build com o novo --version, crie uma nova release com a tag correspondente e anexe os três assets novamente. Os consumidores executam o mesmo pack add e mantêm o subconjunto que haviam escolhido; uma política que foi desativada permanece desativada após a atualização. Alterar o nome de uma política é uma mudança incompatível: uma máquina que a havia desativado 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, portanto comprova que os bytes são os que você publicou — mas não comprova quem você é. Qualquer pessoa com acesso de escrita ao repositório pode modificar ambos os arquivos. A proteção dos seus usuários está no fato de que o digest é fixado no momento da instalação, de modo que o que você distribuiu não pode ser alterado depois. Publique a partir de um repositório cujo acesso de escrita você controla e trate uma release de pack como a publicação de um pacote.

Observe antes de aplicar

Um manifest pode declarar "effect": "observe". 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.

{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] }

​1. Escreva as políticas

​2. Construa os assets da release

​3. Anexe os arquivos à release

​Lançando uma nova versão

​O que seus usuários estão confiando

​Observe antes de aplicar

1. Escreva as políticas

2. Construa os assets da release

3. Anexe os arquivos à release

Lançando uma nova versão

O que seus usuários estão confiando

Observe antes de aplicar