failproofai 0.0.2 → 0.0.4-beta.0

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

@@ -0,0 +1,142 @@
+---
+title: Панель управления
+description: "Мониторинг сеансов агентов, проверка вызовов инструментов и управление политиками"
+icon: chart-line
+---
+
+Панель управления failproofai — это локальное веб-приложение для мониторинга сеансов вашего AI-агента и управления политиками. Посмотрите, что делали ваши агенты, пока вас не было рядом.
+
+---
+
+## Запуск панели управления
+
+```bash
+failproofai
+```
+
+Открывается по адресу `http://localhost:8020`.
+
+Панель управления читает данные непосредственно из файловой системы — из папок проектов Claude Code и файлов конфигурации failproofai. Ничего не отправляется на удаленный сервис.
+
+---
+
+## Страницы
+
+### Проекты
+
+Показывает все проекты Claude Code, найденные на вашем компьютере. Проекты обнаруживаются в `~/.claude/projects/` (или в пути, установленном переменной `CLAUDE_PROJECTS_PATH`).
+
+Для каждого проекта отображается:
+- Имя проекта (полученное из пути папки)
+- Количество сеансов
+- Дата последней активности в сеансе
+
+Нажмите на проект, чтобы увидеть его сеансы.
+
+### Сеансы
+
+Показывает все сеансы в проекте. Для каждого сеанса отображается:
+- ID сеанса
+- Временные метки начала и завершения
+- Количество вызовов инструментов
+- Количество срабатываний хуков (политик, которые были применены)
+
+Используйте фильтр диапазона дат и поиск по ID сеанса, чтобы сузить список. Сеансы разбиты на страницы.
+
+Нажмите на сеанс, чтобы открыть просмотр сеанса.
+
+### Просмотр сеанса
+
+Просмотр сеанса отвечает на ключевой вопрос для автономных агентов: что делал агент и оставался ли он на правильном пути? Он показывает временную шкалу всего, что произошло в сеансе:
+
+- **Сообщения** — текстовые ответы Claude и подсказки пользователя
+- **Вызовы инструментов** — каждый инструмент, который вызвал Claude, с его входными и выходными данными
+- **Активность политик** — для каждого вызова инструмента показывает, какие политики сработали и какое решение они вернули
+
+Панель статистики в верхней части показывает длительность сеанса, общее количество вызовов инструментов и сводку решений хуков (количество разрешений / отказов / инструкций).
+
+Вы можете экспортировать сеанс в файл ZIP или JSONL с помощью кнопки загрузки.
+
+### Политики
+
+Страница с двумя вкладками для управления политиками и проверки активности.
+
+<Tabs>
+  <Tab title="Вкладка политик">
+  - Включайте или отключайте отдельные политики одним нажатием (записывает в `~/.failproofai/policies-config.json`)
+  - Разверните политику, чтобы настроить её параметры (для политик, поддерживающих `policyParams`)
+  - Устанавливайте или удаляйте хуки для определенной области
+  - Установите пользовательский путь файла политик
+  </Tab>
+  <Tab title="Вкладка активности">
+  - Полная история со страничной навигацией всех срабатываний хуков на всех сеансах
+  - Поиск по имени политики, ID сеанса, имени инструмента или решению
+  - Каждая строка показывает: временную метку, имя политики, решение, имя инструмента, ID сеанса и причину отказа/инструкций
+  </Tab>
+</Tabs>
+
+---
+
+## Автоматическое обновление
+
+Панель управления имеет переключатель автоматического обновления в верхней навигации. При включении текущая страница периодически обновляется, отображая новые сеансы и активность политик по мере их появления. Это важно при мониторинге долгих сеансов автономных агентов.
+
+---
+
+## Отключение страниц
+
+Если вам нужны только определенные части панели управления, установите `FAILPROOFAI_DISABLE_PAGES` в список имен страниц, разделенный запятыми:
+
+```bash
+FAILPROOFAI_DISABLE_PAGES=policies failproofai
+```
+
+Допустимые значения: `policies`, `projects`.
+
+---
+
+## Тема оформления
+
+Панель управления поддерживает светлый и темный режимы. Переключайте их с помощью кнопки в навигационной панели. Предпочтение сохраняется в локальном хранилище вашего браузера.
+
+---
+
+## Настройка пути к проектам
+
+По умолчанию панель управления читает из стандартного каталога проектов Claude Code. Переопределите его для пользовательских настроек:
+
+```bash
+CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
+```
+
+---
+
+## Доступ с хоста, отличного от localhost
+
+При запуске панели управления в **режиме разработки** (`npm run dev`) и доступе к ней с хоста, отличного от `localhost` — например, с пользовательского домена, удаленного IP или туннелированного URL-адреса — вы можете увидеть предупреждение:
+
+```text
+⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
+```
+
+Next.js блокирует кроссисточниковый доступ к своему WebSocket HMR (горячей перезагрузки модулей), которая является функцией только для разработки. Чтобы разрешить ваш хост, используйте флаг `--allowed-origins`:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com
+```
+
+Для нескольких хостов или IP-адресов передайте список, разделенный запятыми:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
+```
+
+Вы также можете установить переменную окружения `FAILPROOFAI_ALLOWED_DEV_ORIGINS`:
+
+```bash
+FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
+```
+
+<Note>
+Это относится только к режиму разработки. При запуске `failproofai` (производственный режим) нет WebSocket HMR и нет проблем с кроссисточниковыми ресурсами разработки.
+</Note>

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).