failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,307 @@
+---
+title: Примеры
+description: "Как настроить хуки для Claude Code и Agents SDK"
+icon: book-open
+---
+
+Готовые примеры для часто встречающихся сценариев. Каждый показывает, как установить и чего ожидать.
+
+---
+
+## Настройка хуков для Claude Code
+
+Failproof AI интегрируется с Claude Code через его [систему хуков](https://docs.anthropic.com/en/docs/claude-code/hooks). Когда вы запускаете `failproofai policies --install`, он регистрирует команды хуков в файле `settings.json` Claude Code, которые срабатывают при каждом вызове инструмента.
+
+<Steps>
+  <Step title="Установите failproofai">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="Включите все встроенные политики">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="Проверьте, что хуки зарегистрированы">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    Вы должны увидеть записи хуков для событий `PreToolUse`, `PostToolUse`, `Notification` и `Stop`.
+  </Step>
+  <Step title="Запустите Claude Code">
+    ```bash
+    claude
+    ```
+
+    Политики теперь автоматически запускаются при каждом вызове инструмента. Попросите Claude выполнить `sudo rm -rf /` — это будет заблокировано.
+  </Step>
+</Steps>
+
+---
+
+## Настройка хуков для Agents SDK
+
+Если вы разрабатываете с использованием [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), вы можете использовать ту же систему хуков программно.
+
+<Steps>
+  <Step title="Установите failproofai в ваш проект">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="Настройте хуки в вашем агенте">
+    Передайте команды хуков при создании процесса агента. Хуки срабатывают так же, как в Claude Code — через JSON в stdin/stdout:
+
+    ```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, когда агентам нужно внимание
+
+Используйте хук уведомления для отправки предупреждений об ожидании в 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();
+  },
+});
+```
+
+---
+
+## Заблокируйте производственный репозиторий
+
+Зафиксируйте конфигурацию на уровне проекта, чтобы каждый разработчик вашей команды получал одинаковые политики.
+
+Создайте `.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, автоматически получит эти правила.
+
+---
+
+## Создайте стандарт качества на уровне организации с политиками по соглашению
+
+Наиболее эффективная настройка: зафиксируйте `.failproofai/policies/` в вашем репозитории с политиками, адаптированными к вашему проекту. Каждый член команды получает их автоматически — без команд установки, без изменения конфигурации.
+
+<Steps>
+  <Step title="Создайте директорию и добавьте политики">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+
+    ```js
+    // .failproofai/policies/team-policies.mjs
+    import { customPolicies, allow, deny, instruct } from "failproofai";
+
+    // Enforce your team's preferred package manager
+    // (or enable the built-in prefer-package-manager policy instead)
+    customPolicies.add({
+      name: "enforce-bun",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        const cmd = String(ctx.toolInput?.command ?? "");
+        if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm.");
+        return allow();
+      },
+    });
+
+    // Remind the agent to run tests before committing
+    customPolicies.add({
+      name: "test-before-commit",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
+          return instruct("Run tests before committing.");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="Зафиксируйте в git">
+    ```bash
+    git add .failproofai/policies/
+    git commit -m "Add team quality policies"
+    ```
+  </Step>
+  <Step title="Продолжайте совершенствоваться">
+    Когда ваша команда сталкивается с новыми режимами отказа, добавляйте политики и отправляйте их. Каждый получит обновление при следующем `git pull`. Эти политики становятся живым стандартом качества, который растет вместе с вашей командой.
+  </Step>
+</Steps>
+
+---
+
+## Больше примеров
+
+Директория [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) в репозитории содержит:
+
+| Файл | Что он показывает |
+|------|---------------|
+| `policies-basic.js` | Базовые политики — блокировка производственных записей, force-push, скриптов с передачей |
+| `policies-notification.js` | Оповещения Slack для уведомлений об ожидании и завершении сессии |
+| `policies-advanced/index.js` | Транзитивные импорты, асинхронные хуки, очистка выводов PostToolUse, обработка события Stop |

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

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

@@ -0,0 +1,199 @@
+---
+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
+    ```
+
+    Это добавляет записи крючков в установленные CLI агентов (Claude Code в `~/.claude/settings.json`, OpenAI Codex в `~/.codex/hooks.json`, GitHub Copilot CLI в `~/.copilot/hooks/failproofai.json`, Cursor Agent в `~/.cursor/hooks.json`, OpenCode в сгенерированный модуль плагина `~/.config/opencode/plugins/failproofai.mjs` плюс запись регистрации в массиве `plugin` файла `~/.config/opencode/opencode.json`, Pi в `~/.pi/agent/settings.json`, Hermes в `~/.hermes/config.yaml`, OpenClaw в `~/.openclaw/openclaw.json`, Factory Droid в `~/.factory/hooks.json`, Devin CLI в `~/.config/devin/config.json`, Antigravity CLI в `~/.gemini/config/hooks.json` или Goose в автоматически обнаруживаемую директорию плагинов `~/.agents/plugins/failproofai/hooks/hooks.json`). Если присутствует более одного, вам будет предложено выбрать; передайте `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (любое подмножество), чтобы пропустить запрос.
+
+    Поддержка GitHub Copilot CLI, Cursor Agent, OpenCode и Pi находится на **стадии бета** — устанавливайте с `--cli copilot`, `--cli cursor`, `--cli opencode` или `--cli pi`. Hermes (hermes-agent, шлюз Slack/Telegram) устанавливается с пользовательской областью с `--cli hermes` и также является **источником офлайн-аудита**. OpenClaw (шлюз openclaw, самостоятельно размещаемый многоканальный помощник) устанавливается с пользовательской областью с `--cli openclaw` — принудительное применение работает через его встроенные крючки плагина (`before_agent_finalize` — это реальный запрос на конец хода, поэтому встроенные `require-*-before-stop` применяются) — и является **также источником офлайн-аудита**. Factory Droid (`droid`) устанавливается с `--cli factory` (пользовательская + проектная область) и является **также источником офлайн-аудита**. Devin CLI (`devin`, Cognition) устанавливается с `--cli devin` (пользовательская + проектная область) и является **также источником офлайн-аудита**. Antigravity CLI (`agy`) устанавливается с `--cli antigravity` (пользовательская + проектная область) и является **также источником офлайн-аудита**. Goose (кодовое имя goose, Block) устанавливается с `--cli goose` (пользовательская + проектная область) — установщик просто создаёт директорию плагина в `~/.agents/plugins/failproofai/`, которую Goose автоматически обнаруживает, и это **также источник офлайн-аудита**.
+
+    ```bash
+    failproofai policies --install --scope project
+    failproofai policies --install --cli codex --scope project
+    failproofai policies --install --cli copilot --scope project
+    failproofai policies --install --cli cursor --scope project
+    failproofai policies --install --cli opencode --scope project
+    failproofai policies --install --cli pi --scope project
+    failproofai policies --install --cli hermes --scope user
+    failproofai policies --install --cli openclaw --scope user
+    failproofai policies --install --cli factory --scope project
+    failproofai policies --install --cli devin --scope project
+    failproofai policies --install --cli antigravity --scope project
+    failproofai policies --install --cli goose --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/`. Поместите файлы политик в эту директорию и они будут загружены автоматически — без флагов, без изменения конфигурации, без команд установки.
+
+<Steps>
+  <Step title="Создайте директорию политик">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+  </Step>
+  <Step title="Добавьте файлы политик">
+    Скопируйте примеры для начинающих или напишите свои:
+
+    ```bash
+    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
+    ```
+
+    Или создайте новый:
+
+    ```js
+    // .failproofai/policies/team-policies.mjs
+    import { customPolicies, allow, deny, instruct } from "failproofai";
+
+    customPolicies.add({
+      name: "test-before-commit",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
+          return instruct("Запустите тесты перед коммитом.");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="Закоммитьте в git">
+    ```bash
+    git add .failproofai/policies/
+    git commit -m "Add team quality policies"
+    ```
+
+    Каждый член команды с установленным failproofai автоматически получает эти политики. Не требуется настройка для каждого разработчика.
+  </Step>
+</Steps>
+
+<Tip>
+Закоммитьте `.failproofai/policies/` в ваш репозиторий, чтобы вся команда придерживалась одних и тех же стандартов. По мере того как ваша команда открывает новые режимы отказов, добавляйте политики и отправляйте их — все получат обновление при следующем `git pull`. Со временем эти политики становятся живым стандартом качества, который постоянно улучшается.
+</Tip>
+
+---
+
+## Хранение данных
+
+Вся конфигурация и логи остаются на вашей машине:
+
+| Путь | Что хранится |
+|------|----------------|
+| `~/.failproofai/policies/local-policies/policies-config.json` | Глобальная конфигурация политик |
+| `~/.failproofai/hook-activity/` | История выполнения крючков (постраничный JSONL) |
+| `~/.failproofai/logs/` | Логи отладки для ошибок пользовательских крючков |
+| `.failproofai/policies-config.json` | Конфигурация на проект (коммитится) |
+| `.failproofai/policies-config.local.json` | Личные переопределения (в .gitignore) |
+
+---
+
+## Удаление
+
+```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-old/ru/introduction.mdx

@@ -0,0 +1,58 @@
+---
+---
+title: "Failproof AI"
+description: "FailproofAI предоставляет AI-агентам 39 встроенных политик отказоустойчивости, которые ловят циклы, утечки секретов, деструктивные вызовы инструментов и многое другое с помощью одной установки."
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+Хуки и политики для **обработки сбоев AI**, **восстановления после ошибок** и **надежности LLM**. Делайте ваши AI-агенты надежными и работающими автономно в **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** и **Agents SDK**.
+
+AI-агенты отказывают предсказуемым образом. Они выполняют деструктивные команды, утекают секреты, отклоняются от задачи, застревают в циклах или пушат прямо в основную ветку. Без контроля небольшие сбои перерастают в сбои системы, утечки учетных данных и потерю работы.
+
+FailproofAI решает эту проблему с помощью **политик**. Эти правила перехватывают каждый вызов инструмента агента для **обнаружения сбоев**, **их смягчения** (блокировка, инструктирование, санитизация) и **оповещения вас** о проблемах, требующих внимания. Локальная панель мониторинга позволяет просмотреть каждый вызов инструмента, отказ агента и действие восстановления впоследствии.
+
+Стенограммы и оценка политик остаются на вашем компьютере. Данные отправляются только при явном использовании онлайн-функции, такой как аутентифицированные напоминания об аудите или приглашения.
+
+## Начало работы
+
+<CardGroup cols={2}>
+
+<Card title="39 встроенных политик" 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   # включить политики (или пропустить — `failproofai` предложит настроить их при первом запуске)
+failproofai                      # запустить панель мониторинга
+```
+
+Полный обзор см. в руководстве [Начало работы](/ru/getting-started).