Публикация пакета

Пакет — это три файла, прикреплённые к GitHub-релизу. failproofai pack build создаёт все три файла на основе уже имеющегося файла политики.

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

Один файл, использующий тот же API, что и любая пользовательская политика. Для пакета важны два дополнительных поля:

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 по умолчанию имеет значение false, если вы его опустите. Простая команда failproofai pack add включает только то, что вы отметили — установка всех политик незнакомца без участия пользователя — это решение, которое установщик не должен принимать за своего пользователя.

Точка входа должна быть одним самостоятельным файлом. Только точка входа закреплена по хешу, поэтому пакет, который импортирует локальные файлы, не может честно утверждать, что хеш покрывает то, что запустится. Сначала объедините файлы (esbuild, bun build, rollup), а затем создайте пакет из объединённого результата — pack build отказывает локальным импортам, чтобы не поставить обещание, которое оно не может выполнить.

2. Создайте релиз-артефакты

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

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

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

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

3. Прикрепите их к релизу

Отметьте релиз той же версией, которую вы создали, и прикрепите все три файла как артефакты релиза:

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

Теперь кто угодно может установить его:

failproofai pack add acme/support-agent

Имена артефактов фиксированы — это то, из чего CLI потребителя строит свои URL-адреса, без вызовов API и без обнаружения.

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

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

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

SHA256SUMS находится в том же релизе, что и артефакт, поэтому он доказывает, что байты — это те, которые вы опубликовали, но не кто вы. Кто угодно, у кого есть доступ на запись в репозиторий, может записать оба файла. Защита ваших пользователей в том, что хеш закреплён при установке, поэтому то, что вы поставили, не может измениться после этого. Публикуйте из репозитория, доступ на запись в который вы контролируете, и относитесь к релизу пакета как к публикации пакета.

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

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

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

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

​2. Создайте релиз-артефакты

​3. Прикрепите их к релизу

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

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

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