Опубликовать пакет политик

Пакет — это три файла, прикреплённые к GitHub release. failproofai publish создаёт все три из файлов политик, создаёт release и загружает их.

1. Напишите политики

Начните с чего-то, что уже работает, а не с шаблона с пропусками:

failproofai publish --init

Это спросит название пакета, напишет <name>.mjs и остановится — никакой сети, никакого git, ничего не опубликовано. Файл, который он создаёт — это одна политика, которая уже блокирует git push --force. Он не перезаписывает существующие файлы. Политики используют тот же API, что и любая пользовательская политика. Два дополнительных поля важны для пакета:

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

customPolicies.add({
  name: "block-refunds",
  description: "Refunds above the approved limit need a human",
  category: "Billing",        // группирует её, и это то, что выбирает --category
  defaultEnabled: true,       // включается обычной командой `policies 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 по умолчанию равен false, если вы его опустите. Обычная команда failproofai policies add включает только отмеченные вами политики — установка всех политик незнакомца без присмотра — это не решение, которое установщик должен принимать за своего пользователя. Напишите столько файлов, сколько хотите; по одному на категорию читается хорошо. Каждый файл в директории, который регистрирует политики, будет собран в единый артефакт, который должен быть пакет.

Сборка требует bun. Без него придерживайтесь одного самостоятельного файла. В любом случае опубликованная точка входа не должна импортировать локальные файлы при установке: только точка входа имеет закреплённый дайджест, поэтому пакет, который загружал соседние файлы, не мог бы честно утверждать, что дайджест охватывает то, что запускается — и publish отказывает в таком случае, чтобы не отправить обещание, которое не может быть выполнено.

2. Сначала попробуйте здесь

Перед тем, как это смогут увидеть другие, примените файл на этой машине:

failproofai policies -i -c ./<name>.mjs

Любой путь, любое имя файла. Попросите вашего агента выполнить то, что вы заблокировали, и смотрите, как это будет отклонено. Ничего не опубликовано и никто другой не затронут. Протестировать политику охватывает остальное: правомерный случай, который она должна разрешить, и входные данные, которые её сломают.

3. Опубликуйте

failproofai publish

Она выясняет, где опубликовать, что собирать и какой версии это дать, и только спрашивает, когда репозиторий ничего не подсказывает. По порядку, останавливаясь перед созданием release, если что-то не так:

Находит файлы политик здесь по содержимому — те, что импортируют failproofai и вызывают customPolicies.add — а не по имени файла, так что находит guards.mjs и игнорирует несвязанный policies.mjs. Она не спускается в подпапки, так что тестовый fixture никогда не будет случайно собран.
Читает репо из git remote get-url origin, в директории файла, а не в вашей, и определяет версию.
Находит ваши учётные данные: GITHUB_TOKEN, GH_TOKEN или gh auth login. Нужны права release-write и ничего больше, никогда не выводится.
Создаёт репозиторий, если он не существует. Это происходит перед сборкой, так что пакет, отклонённый на следующем шаге, может оставить новый репозиторий без release в нём.
Создаёт три ресурса, валидируя их собственными правилами загрузчика — тем же кодом, который решает, что может быть установлено на чужой машине — так что пакет, который никогда не сможет быть установлен, отказывается здесь, где вы ещё можете его исправить.
Создаёт или переиспользует release и загружает, заменяя ресурсы с тем же именем.

Файл	Что это
`failproofai-pack.json`	Манифест: id, версия, эффект и одна запись на политику
`failproofai-pack.mjs`	Ваша собранная точка входа
`SHA256SUMS`	`<sha256> <filename>` для двух остальных

Имена ресурсов фиксированы — это то, из чего CLI потребителя конструирует URL, без вызова API и без поиска. Отклонено при сборке: id, который не publisher/name, имя политики с /, политика, объявляющая alwaysOn, отсутствующее description, category или match, точка входа, которая ничего не регистрирует, и точка входа, которая импортирует локальные файлы. Переопределите всё, что она решила:

failproofai publish \
  --repo acme/support-agent \
  --version 1.0.0 \
  --effect observe \
  --dry-run

--id устанавливает id пакета, когда он должен отличаться от репо, --tag устанавливает тег release, --notes заменяет сгенерированные примечания release — это то, откуда policies show --releases читает счётчики и коммит каждого release — --out выбирает, где писать ресурсы (по умолчанию dist-pack), и --dry-run создаёт их без публикации и не нужны учётные данные. Теперь кто угодно может установить его с помощью failproofai policies add acme/support-agent. Смотрите пакеты политик для закрепления версии и взятия только части одного.

Выведите его на хаб политик

Добавьте тему failproofai-policies к репозиторию на GitHub. Нет формы отправки и нет очереди одобрения: хаб политик сканер подхватывает репозиторий при следующем проходе. Тема только выводит его на рассмотрение — то, что выводит его в список — это release, чей манифест проверяется против его собственного SHA256SUMS и разбирается по тем же правилам, которые использует CLI, что точно производит failproofai publish.

Как определяется версия

Версия — это коммит, из которого вы публикуете — его короткий sha, двенадцать символов: a1b2c3d4e5f6. Нет ничего, что нужно выбирать и ничего, что нужно увеличивать, и версия точно называет то, откуда пришли байты, так что публикация одного и того же источника дважды даёт одну и ту же версию. Она читается из дерева перед вами, никогда не из release репозитория, так что свежий клон и машина без интернета вычисляют один и тот же ответ без запроса GitHub о том, что было раньше. Потому что версия называет коммит, этот коммит должен существовать. При терминале publish создаёт его для вас: инициализирует репозиторий, когда его нет, и коммитит изменённые файлы политик перед сборкой. Она отказывает вместо этого — называя --version как выход — когда работает без терминала (коммит, сделанный на CI runner, не существовал бы больше нигде), когда файлы кроме политик не закоммичены, или в checkout, который не имеет коммитов вообще. Тег на HEAD выигрывает над sha — тот, кто отметил v1.2.0, сказал, что это release. Sha не имеет собственного упорядочения, так что используйте failproofai policies show <owner>/<repo> --releases чтобы увидеть, какой release был первым — новейший вверху.

Доставка новой версии

Закоммитьте изменение и запустите failproofai publish снова — новый коммит — это новая версия. Потребители запускают один и тот же failproofai policies add. Без терминала или с флагом выбора, они сохраняют подмножество, которое выбрали, и политика, которую они отключили, остаётся отключенной; при терминале без флага, выбиратель открывается с предварительно отмеченными вашими значениями по умолчанию и их ответ заменяет их выбор. Изменение имени политики — это критическое изменение: машина, которая отключила её, отключает имя, которое больше не существует, и новое имя приходит с тем, что говорит defaultEnabled.

Чему доверяют ваши пользователи

SHA256SUMS находится в одном release с артефактом, так что доказывает, что байты — это те, что вы опубликовали — не то, кто вы. Тот, кто может писать в репозиторий, может писать оба файла. Защита ваших пользователей в том, что дайджест закреплён при установке, так что то, что вы отправили, не может измениться под ними после этого. Публикуйте из репозитория, доступ на запись в который вы контролируете, и относитесь к выпуску пакета как к публикации пакета. Репозиторий также должен быть публичным. Установки — это анонимный HTTPS без учётных данных, так что существующий приватный репо отказывается перед тем, как что-либо собирается или загружается, и один publish создаёт публичный по той же причине. --allow-private переопределяет это для кого-то, передающего три ресурса другим способом, и говорит ясно, что никакой policies add не сможет их достичь. Только release имеет значение: установки читают releases/download/<tag>/<asset> и никогда не трогают ваше git дерево.

Наблюдайте перед тем, как применять

Манифест может объявить "effect": "observe" — failproofai publish --effect observe это то, что это устанавливает. Те политики запускаются и их вердикты записываются и отбрасываются — ничего не блокируется. Это способ измерить новое правило против реального трафика перед тем, как оно может помешать чьей-либо работе.

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

Prevent repeat failures

Get a policy

Ship a policy

Опубликовать пакет политик

1. Напишите политики

2. Сначала попробуйте здесь

3. Опубликуйте

Выведите его на хаб политик

Как определяется версия

Доставка новой версии

Чему доверяют ваши пользователи

Наблюдайте перед тем, как применять

​1. Напишите политики

​2. Сначала попробуйте здесь

​3. Опубликуйте

​Выведите его на хаб политик

​Как определяется версия

​Доставка новой версии

​Чему доверяют ваши пользователи

​Наблюдайте перед тем, как применять

1. Напишите политики

2. Сначала попробуйте здесь

3. Опубликуйте

Выведите его на хаб политик

Как определяется версия

Доставка новой версии

Чему доверяют ваши пользователи

Наблюдайте перед тем, как применять