failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/ru/examples.mdx

@@ -0,0 +1,254 @@
+---
+---
+title: Примеры
+description: "Как настроить hooks для Claude Code и Agents SDK"
+icon: book-open
+---
+
+Готовые к использованию примеры для типичных сценариев. Каждый показывает, как установить и чего ожидать.
+
+---
+
+## Настройка hooks для Claude Code
+
+Failproof AI интегрируется с Claude Code через его [систему hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Когда вы запускаете `failproofai policies --install`, он регистрирует команды hooks в `settings.json` Claude Code, которые срабатывают при каждом вызове инструмента.
+
+<Steps>
+  <Step title="Установите failproofai">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="Включите все встроенные политики">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="Проверьте, что hooks зарегистрированы">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    Вы должны увидеть записи hooks для событий `PreToolUse`, `PostToolUse`, `Notification` и `Stop`.
+  </Step>
+  <Step title="Запустите Claude Code">
+    ```bash
+    claude
+    ```
+
+    Политики теперь выполняются автоматически при каждом вызове инструмента. Попробуйте попросить Claude выполнить `sudo rm -rf /` — это будет заблокировано.
+  </Step>
+</Steps>
+
+---
+
+## Настройка hooks для Agents SDK
+
+Если вы разрабатываете с помощью [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), вы можете использовать ту же систему hooks программно.
+
+<Steps>
+  <Step title="Установите failproofai в ваш проект">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="Настройте hooks в вашем агенте">
+    Передайте команды hooks при создании процесса агента. Hooks срабатывают точно так же, как в Claude Code — через stdin/stdout JSON:
+
+    ```bash
+    failproofai --hook PreToolUse   # вызывается перед каждым инструментом
+    failproofai --hook PostToolUse  # вызывается после каждого инструмента
+    ```
+  </Step>
+  <Step title="Напишите пользовательскую политику для вашего агента">
+    ```javascript
+    import { customPolicies, allow, deny } from "failproofai";
+
+    customPolicies.add({
+      name: "limit-to-project-dir",
+      description: "Keep the agent inside the project directory",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        const path = String(ctx.toolInput?.file_path ?? "");
+        if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
+          return deny("Agent is restricted to the project directory");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="Установите пользовательскую политику">
+    ```bash
+    failproofai policies --install --custom ./my-agent-policies.js
+    ```
+  </Step>
+</Steps>
+
+---
+
+## Блокировка деструктивных команд
+
+Самая распространённая настройка — предотвращение необратимого ущерба от действий агентов.
+
+```bash
+failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
+```
+
+Что это делает:
+- `block-sudo` — блокирует все команды `sudo`
+- `block-rm-rf` — блокирует рекурсивное удаление файлов
+- `block-force-push` — блокирует `git push --force`
+- `block-curl-pipe-sh` — блокирует передачу удалённых скриптов в оболочку
+
+---
+
+## Предотвращение утечки секретов
+
+Остановите агентов от просмотра или утечки учётных данных в выводе инструментов.
+
+```bash
+failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
+```
+
+Эти политики срабатывают на `PostToolUse` — после выполнения инструмента они очищают вывод перед тем, как агент его увидит.
+
+---
+
+## Получайте оповещения в Slack, когда агентам требуется внимание
+
+Используйте hook уведомлений для отправки оповещений о неактивности в Slack.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "slack-on-idle",
+  description: "Alert Slack when the agent is waiting for input",
+  match: { events: ["Notification"] },
+  fn: async (ctx) => {
+    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
+    if (!webhookUrl) return allow();
+
+    const message = String(ctx.payload?.message ?? "Agent is waiting");
+    const project = ctx.session?.cwd ?? "unknown";
+
+    try {
+      await fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          text: `*${message}*\nProject: \`${project}\``,
+        }),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch {
+      // never block the agent if Slack is unreachable
+    }
+
+    return allow();
+  },
+});
+```
+
+Установите её:
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
+```
+
+---
+
+## Держите агентов на одной ветке
+
+Предотвратите переключение ветвей или отправку на защищённые ветви.
+
+```javascript
+import { customPolicies, allow, deny } from "failproofai";
+
+customPolicies.add({
+  name: "stay-on-branch",
+  description: "Prevent the agent from checking out other branches",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
+      return deny("Stay on the current branch. Create a new branch with -b if needed.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## Требуйте тесты перед коммитом
+
+Напоминайте агентам запускать тесты перед коммитом.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "test-before-commit",
+  description: "Remind the agent to run tests before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## Заблокируйте production репозиторий
+
+Добавьте конфигурацию на уровне проекта, чтобы все разработчики вашей команды получили одинаковые политики.
+
+Создайте `.failproofai/policies-config.json` в вашем репозитории:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-force-push",
+    "block-push-master",
+    "block-env-files",
+    "sanitize-api-keys",
+    "sanitize-jwt"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "production"]
+    }
+  }
+}
+```
+
+Затем добавьте её:
+
+```bash
+git add .failproofai/policies-config.json
+git commit -m "Add failproofai team policies"
+```
+
+Каждый член команды, у которого установлен failproofai, автоматически получит эти правила.
+
+---
+
+## Больше примеров
+
+Директория [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) в репозитории содержит:
+
+| Файл | Что он показывает |
+|------|---------------|
+| `policies-basic.js` | Базовые политики — блокировка записей в production, force-push, передачи скриптов |
+| `policies-notification.js` | Оповещения Slack для уведомлений о неактивности и завершении сессии |
+| `policies-advanced/index.js` | Переходные импорты, асинхронные hooks, очистка вывода PostToolUse, обработка события Stop |

package/.next/standalone/docs/ru/for-agents.mdx

@@ -0,0 +1,38 @@
+---
+title: "Для агентов"
+description: "Добавьте справку Failproof AI вашему кодирующему агенту одной командой. Работает с Claude Code, Cursor, Windsurf и другими."
+---
+
+Добавьте полную справку Failproof AI вашему кодирующему агенту одной командой. Работает с Claude Code, Cursor, Windsurf и любым другим агентом, поддерживающим навыки.
+
+```bash
+npx skills add https://docs.befailproof.ai
+```
+
+`npx skills` определяет, какие агенты у вас установлены, и автоматически добавляет навык в правильном формате для каждого.
+
+## Что включает навык
+
+| Область | Содержание |
+|------|----------------|
+| Policies | Встроенные имена политик, типы событий, параметры, включение/отключение |
+| Custom policies | `customPolicies.add()`, фильтры совпадений, API `allow`/`deny`/`instruct` |
+| Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` |
+| Configuration | Структура `policies-config.json`, слияние scope, `policyParams` |
+| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scope |
+| Dashboard | Просмотр сессий, активность политик, переменные окружения |
+| Architecture | Поток обработчика hook, коды выхода, контракт stdin/stdout |
+
+## Полон ли навык?
+
+Mintlify генерирует `llms.txt` из всех страниц в навигации. Документация Failproof AI охватывает полный API - каждая политика, опция и пример включены. Если вы обнаружите что-то отсутствующее, источник находится по адресу `https://docs.befailproof.ai/llms-full.txt`.
+
+Для целевого контекста создавайте ссылку непосредственно на конкретную страницу:
+
+```bash
+# Только API custom policies
+npx skills add https://docs.befailproof.ai/custom-policies
+
+# Только встроенные политики
+npx skills add https://docs.befailproof.ai/built-in-policies
+```

package/.next/standalone/docs/ru/getting-started.mdx

@@ -0,0 +1,134 @@
+---
+title: Начало работы
+description: "Установите failproofai, активируйте политики и позвольте вашим агентам работать надежно"
+icon: rocket
+---
+
+## Требования
+
+- **Node.js** >= 20.9.0
+- **Bun** >= 1.3.0 (опционально - требуется только для сборки из исходного кода)
+
+---
+
+## Установка
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+---
+
+## Быстрый старт
+
+<Steps>
+  <Step title="Активируйте политики">
+    Политики — это правила, которые выполняются до и после каждого вызова инструмента агента. Они перехватывают деструктивные команды, утечки секретов и другие режимы отказа до того, как они нанесут ущерб.
+
+    ```bash
+    failproofai policies --install
+    ```
+
+    Это записывает записи хуков в `settings.json` Claude Code. Вы также можете установить для одного проекта или выбрать определенные политики:
+
+    ```bash
+    failproofai policies --install --scope project
+    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
+    ```
+  </Step>
+  <Step title="Проверка">
+    ```bash
+    failproofai policies
+    ```
+
+    Показывает каждую политику, включена ли она и все настроенные параметры.
+  </Step>
+  <Step title="Запустите панель мониторинга">
+    ```bash
+    failproofai
+    ```
+
+    Открывает локальную панель мониторинга на `http://localhost:8020`, где вы можете просматривать сеансы, проверять вызовы инструментов и управлять политиками.
+  </Step>
+  <Step title="Запустите ваш агент">
+    Запустите Claude Code обычным образом. Если агент попытается что-то рискованное, failproofai автоматически его перехватит. Оставьте его работать без присмотра и проверьте то, что произошло, на панели мониторинга.
+  </Step>
+</Steps>
+
+---
+
+## Как работают политики
+
+Каждый раз, когда агент запускает инструмент, Claude Code вызывает failproofai как подпроцесс:
+
+```text
+Claude Code  →  failproofai --hook PreToolUse  →  читает JSON из stdin
+                                                 оценивает политики
+                                                 записывает решение в stdout
+```
+
+Каждая политика возвращает одно из трех решений:
+
+- **allow** — агент продолжает работу нормально
+- **deny** — действие блокируется, агенту объясняется причина
+- **instruct** — дополнительный контекст добавляется в подсказку агента
+
+<Note>
+Политики выполняются в вашем локальном процессе. Ничего не отправляется на удаленный сервис.
+</Note>
+
+---
+
+## Хранение данных
+
+Все конфигурации и логи остаются на вашем компьютере:
+
+| Путь | Что здесь хранится |
+|------|----------------|
+| `~/.failproofai/policies-config.json` | Глобальная конфигурация политик |
+| `~/.failproofai/hook-activity.jsonl` | История выполнения хуков |
+| `~/.failproofai/hook.log` | Лог отладки для ошибок пользовательских хуков |
+| `.failproofai/policies-config.json` | Конфигурация для каждого проекта (committed) |
+| `.failproofai/policies-config.local.json` | Личные переопределения (gitignored) |
+
+---
+
+## Удаление
+
+```bash
+failproofai policies --uninstall
+```
+
+Удаляет записи хуков из `~/.claude/settings.json`. Файлы конфигурации в `~/.failproofai/` сохраняются.
+
+---
+
+## Следующие шаги
+
+<CardGroup cols={2}>
+
+<Card title="Конфигурация" icon="gear" href="/ru/configuration">
+  Области действия и формат файла конфигурации
+</Card>
+
+<Card title="Встроенные политики" icon="shield" href="/ru/built-in-policies">
+  Все 26 политик с параметрами
+</Card>
+
+<Card title="Пользовательские политики" icon="code" href="/ru/custom-policies">
+  Напишите свои собственные политики на JavaScript
+</Card>
+
+<Card title="Монитор агента" icon="chart-line" href="/ru/dashboard">
+  Мониторьте сеансы и проверяйте активность политик
+</Card>
+
+</CardGroup>

package/.next/standalone/docs/ru/introduction.mdx

@@ -0,0 +1,57 @@
+---
+title:  Failproof AI
+description: "Управляйте хуками и политиками, которые делают ваших AI агентов надежными и позволяют им работать автономно"
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+Хуки и политики, которые делают ваших AI агентов надежными и позволяют им работать автономно — для **Claude Code** и **Agents SDK**.
+
+AI агенты отказывают предсказуемым образом. Они запускают деструктивные команды, утекают секреты, отклоняются от задачи, застревают в циклах или пушат напрямую в main. Без присмотра небольшие сбои каскадируют.
+
+Failproof AI решает эту проблему с помощью **политик** — правил, которые интегрируются в каждый вызов инструмента агента и могут **обнаруживать сбои**, **смягчать их** (блокировать, инструктировать, санитизировать) и **оповещать вас**, когда требуется внимание. Локальная панель мониторинга позволяет просмотреть всё впоследствии.
+
+Всё работает локально. Никакие данные не покидают вашу машину.
+
+## Начните работу
+
+<CardGroup cols={2}>
+
+<Card title="26 встроенных политик" icon="shield" href="/ru/built-in-policies">
+  Блокируйте деструктивные команды, предотвращайте утечки секретов, удерживайте агентов внутри границ проекта и многое другое — прямо из коробки.
+</Card>
+
+<Card title="Пользовательские политики" icon="code" href="/ru/custom-policies">
+  Напишите свои собственные правила на JavaScript с простым API allow / deny / instruct.
+</Card>
+
+<Card title="Монитор агентов" icon="chart-line" href="/ru/dashboard">
+  Смотрите, что делали ваши агенты, пока вас не было. Просматривайте сессии, проверяйте вызовы инструментов, смотрите, где срабатывали политики.
+</Card>
+
+<Card title="Простая конфигурация" icon="gear" href="/ru/configuration">
+  Настраивайте любую политику без кода. Устанавливайте списки разрешений, защищённые ветки или пороги по проектам или глобально.
+</Card>
+
+</CardGroup>
+
+## Быстрый старт
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # enable policies
+failproofai                      # launch the dashboard
+```
+
+Подробное руководство см. в [Getting started](/ru/getting-started).

package/.next/standalone/docs/ru/package-aliases.mdx

@@ -0,0 +1,82 @@
+---
+title: Альтернативные имена пакетов
+description: "Зарегистрированные альтернативные имена для защиты от опечаток и их работа"
+icon: copy
+---
+
+## Официальный пакет
+
+Основной npm-пакет — **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# или
+bun add -g failproofai
+```
+
+---
+
+## Почему мы владеем альтернативными именами
+
+Typosquatting — это распространённая атака на цепочку поставок, при которой злоумышленник регистрирует имя пакета, отличающееся на один символ от популярного пакета. Невнимательные пользователи, допустившие опечатку в команде установки, в итоге запускают код, контролируемый злоумышленником, с полным доступом к системе — это именно тот вид угрозы, против которого разработана Failproof AI.
+
+Чтобы исключить эту уязвимость, **мы заранее регистрируем все распространённые опечатки и варианты написания** `failproofai` на npm. Ни одно из этих имён не может быть зарегистрировано третьей стороной. Каждое из них — это тонкий прокси, который устанавливает и делегирует работу основному пакету `failproofai`.
+
+---
+
+## Зарегистрированные альтернативные имена
+
+**Варианты написания** — разные способы написания "failproof ai":
+
+| Пакет | Статус |
+|---------|--------|
+| `failproof` | ✅ Опубликован |
+| `failproof-ai` | ⏳ Ожидает поддержки npm |
+| `fail-proof-ai` | ⏳ Ожидает поддержки npm |
+| `failproof_ai` | ⏳ Ожидает поддержки npm |
+| `fail_proof_ai` | ⏳ Ожидает поддержки npm |
+| `fail-proofai` | ⏳ Ожидает поддержки npm |
+
+**Опечатки `failprof*`** — пропущена одна буква `o` в слове "proof":
+
+| Пакет | Статус |
+|---------|--------|
+| `failprof` | ✅ Опубликован |
+| `failprof-ai` | ✅ Опубликован |
+| `failprofai` | ⏳ Ожидает поддержки npm |
+| `fail-prof-ai` | ⏳ Ожидает поддержки npm |
+| `failprof_ai` | ⏳ Ожидает поддержки npm |
+
+**Опечатки `faliproof*`** — переставлены буквы `a` и `i`:
+
+| Пакет | Статус |
+|---------|--------|
+| `faliproof` | ✅ Опубликован |
+| `faliproof-ai` | ✅ Опубликован |
+| `faliproofai` | ⏳ Ожидает поддержки npm |
+
+> **Почему в статусе "ожидает"?** Политика npm по защите от спама блокирует имена, которые нормализуются в одну строку с существующим пакетом после удаления пунктуации и проверки сходства. Мы связались с поддержкой npm, чтобы зарезервировать эти имена в целях защиты от typosquatting. Они будут активированы после одобрения.
+
+Вы можете проверить, что любое опубликованное альтернативное имя принадлежит нам:
+
+```bash
+npm info failproof
+# Ищите: "ExosphereHost Inc." в поле maintainers
+```
+
+---
+
+## Как работают альтернативные имена
+
+Каждый пакет-альтернатива:
+
+1. Указывает `failproofai` как зависимость — поэтому при установке запускается основной пакет (включая его hook `postinstall`)
+2. Экспортирует бинарный файл с собственным именем (например `failprof-ai`), который пробрасывает все аргументы на бинарный файл `failproofai`
+
+Прокси — это двухстрочный скрипт Node.js; в нём нет никакой логики, сетевых запросов и сбора данных, кроме того, что делает сам `failproofai`.
+
+---
+
+## Если мы пропустили какое-то имя
+
+Откройте задачу на [exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues) и мы его зарегистрируем.