failproofai 0.0.6-beta.3 → 0.0.6-beta.5

package/.next/standalone/docs/ru/custom-policies.mdx

@@ -1,354 +0,0 @@
----
----
-title: Пользовательские политики
-description: "Напишите собственные политики на JavaScript - обеспечьте соблюдение соглашений, предотвратите дрейф, выявляйте сбои, интегрируйтесь с внешними системами"
-icon: code
----
-
-Пользовательские политики позволяют писать правила для любого поведения агента: обеспечивать соблюдение соглашений проекта, предотвращать дрейф, блокировать деструктивные операции, выявлять зависшие агенты или интегрироваться со Slack, рабочими процессами одобрения и многим другим. Они используют ту же систему событий hook и решения `allow`, `deny`, `instruct`, что и встроенные политики.
-
----
-
-## Быстрый пример
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-customPolicies.add({
-  name: "no-production-writes",
-  description: "Block writes to paths containing 'production'",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
-    const path = ctx.toolInput?.file_path ?? "";
-    if (path.includes("production")) {
-      return deny("Writes to production paths are blocked");
-    }
-    return allow();
-  },
-});
-```
-
-Установите её:
-
-```bash
-failproofai policies --install --custom ./my-policies.js
-```
-
----
-
-## Два способа загрузки пользовательских политик
-
-### Вариант 1: На основе соглашения (рекомендуется)
-
-Разместите файлы `*policies.{js,mjs,ts}` в `.failproofai/policies/` и они будут загружены автоматически — без флагов или изменений конфигурации. Это работает как git hooks: положите файл, и он просто работает.
-
-```
-# На уровне проекта — добавляется в git, совместно используется командой
-.failproofai/policies/security-policies.mjs
-.failproofai/policies/workflow-policies.mjs
-
-# На уровне пользователя — личные, применяются ко всем проектам
-~/.failproofai/policies/my-policies.mjs
-```
-
-**Как это работает:**
-- Оба каталога (проекта и пользователя) сканируются (объединение — не первый найденный)
-- Файлы загружаются в алфавитном порядке в каждом каталоге. Добавьте префикс `01-`, `02-` для управления порядком
-- Загружаются только файлы, соответствующие `*policies.{js,mjs,ts}`; остальные файлы игнорируются
-- Каждый файл загружается независимо (fail-open для каждого файла)
-- Работает рядом с явными `--custom` и встроенными политиками
-
-<Tip>
-Политики на основе соглашения — самый простой способ установить стандарт качества для вашей организации. Добавьте `.failproofai/policies/` в git, и каждый участник команды получит одни и те же правила автоматически — не требуется настройка для каждого разработчика. По мере того как ваша команда обнаруживает новые режимы сбоев, добавьте политику и отправьте её. Со временем эти политики становятся живым стандартом качества, который улучшается с каждым вкладом.
-</Tip>
-
-### Вариант 2: Явный путь к файлу
-
-```bash
-# Установка с пользовательским файлом политик
-failproofai policies --install --custom ./my-policies.js
-
-# Замена пути к файлу политик
-failproofai policies --install --custom ./new-policies.js
-
-# Удаление пути к пользовательским политикам из конфигурации
-failproofai policies --uninstall --custom
-```
-
-Разрешённый абсолютный путь сохраняется в `policies-config.json` как `customPoliciesPath`. Файл загружается заново при каждом событии hook — кеширования между событиями нет.
-
-### Использование обоих способов вместе
-
-Политики на основе соглашения и явный файл `--custom` могут сосуществовать. Порядок загрузки:
-
-1. Файл с явным `customPoliciesPath` (если настроен)
-2. Файлы соглашения проекта (`{cwd}/.failproofai/policies/`, в алфавитном порядке)
-3. Файлы соглашения пользователя (`~/.failproofai/policies/`, в алфавитном порядке)
-
----
-
-## API
-
-### Импорт
-
-```js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-```
-
-### `customPolicies.add(hook)`
-
-Регистрирует политику. Вызывайте столько раз, сколько нужно для нескольких политик в одном файле.
-
-```ts
-customPolicies.add({
-  name: string;                         // обязателен - уникальный идентификатор
-  description?: string;                 // показывается в выводе `failproofai policies`
-  match?: { events?: HookEventType[] }; // фильтр по типу события; опустите для соответствия всем
-  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
-});
-```
-
-### Вспомогательные функции принятия решений
-
-| Функция | Эффект | Когда использовать |
-|---------|--------|-------------------|
-| `allow()` | Разрешить операцию молча | Действие безопасно, сообщение не требуется |
-| `deny(message)` | Блокировать операцию | Агент не должен выполнять это действие |
-| `instruct(message)` | Добавить контекст без блокировки | Дать агенту дополнительный контекст для остановки на пути |
-
-`deny(message)` - сообщение появляется Claude с префиксом `"Blocked by failproofai:"`. Один `deny` прерывает всю дальнейшую оценку.
-
-`instruct(message)` - сообщение добавляется в контекст Claude для текущего вызова инструмента. Все сообщения `instruct` накапливаются и доставляются вместе.
-
-<Tip>
-Вы можете добавить дополнительное руководство к любому сообщению `deny` или `instruct`, добавив поле `hint` в `policyParams` — без изменения кода. Это работает для пользовательских (`custom/`), проектных соглашений (`.failproofai-project/`) и пользовательских соглашений (`.failproofai-user/`) политик. Смотрите [Configuration → hint](/ru/configuration#hint-cross-cutting) для деталей.
-</Tip>
-
-### Информационные сообщения allow
-
-`allow(message)` разрешает операцию **и** отправляет информационное сообщение обратно Claude. Сообщение доставляется как `additionalContext` в ответе stdout обработчика hook — тот же механизм, используемый `instruct`, но семантически отличающийся: это обновление статуса, а не предупреждение.
-
-| Функция | Эффект | Когда использовать |
-|---------|--------|-------------------|
-| `allow(message)` | Разрешить и отправить контекст Claude | Подтвердить прохождение проверки или объяснить, почему проверка была пропущена |
-
-Примеры использования:
-- **Подтверждения статуса:** `allow("All CI checks passed.")` — сообщает Claude, что всё хорошо
-- **Fail-open объяснения:** `allow("GitHub CLI not installed, skipping CI check.")` — сообщает Claude, почему проверка была пропущена, чтобы у него был полный контекст
-- **Несколько сообщений накапливаются:** если несколько политик каждая возвращает `allow(message)`, все сообщения объединяются с новыми строками и доставляются вместе
-
-```js
-customPolicies.add({
-  name: "confirm-branch-status",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    const cwd = ctx.session?.cwd;
-    if (!cwd) return allow("No working directory, skipping branch check.");
-
-    // ... check branch status ...
-    if (allPushed) {
-      return allow("Branch is up to date with remote.");
-    }
-    return deny("Unpushed changes detected.");
-  },
-});
-```
-
-### Поля `PolicyContext`
-
-| Поле | Тип | Описание |
-|------|-----|---------|
-| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | Вызываемый инструмент (например `"Bash"`, `"Write"`, `"Read"`) |
-| `toolInput` | `Record<string, unknown> \| undefined` | Входные параметры инструмента |
-| `payload` | `Record<string, unknown>` | Полная необработанная полезная нагрузка события из Claude Code |
-| `session` | `SessionMetadata \| undefined` | Контекст сессии (см. ниже) |
-
-### Поля `SessionMetadata`
-
-| Поле | Тип | Описание |
-|------|-----|---------|
-| `sessionId` | `string` | Идентификатор сессии Claude Code |
-| `cwd` | `string` | Рабочий каталог сессии Claude Code |
-| `transcriptPath` | `string` | Путь к файлу транскрипта JSONL сессии |
-
-### Типы событий
-
-| Событие | Когда срабатывает | Содержимое `toolInput` |
-|--------|------------------|----------------------|
-| `PreToolUse` | Перед запуском инструмента Claude | Входные данные инструмента (например `{ command: "..." }` для Bash) |
-| `PostToolUse` | После завершения инструмента | Входные данные инструмента + `tool_result` (выход) |
-| `Notification` | Когда Claude отправляет уведомление | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks должны всегда возвращать `allow()`, они не могут блокировать уведомления |
-| `Stop` | Когда сессия Claude заканчивается | Пусто |
-
----
-
-## Порядок оценки
-
-Политики оцениваются в этом порядке:
-
-1. Встроенные политики (в порядке определения)
-2. Явные пользовательские политики из `customPoliciesPath` (в порядке `.add()`)
-3. Политики соглашения из проекта `.failproofai/policies/` (файлы в алфавитном порядке, `.add()` порядок внутри)
-4. Политики соглашения из пользователя `~/.failproofai/policies/` (файлы в алфавитном порядке, `.add()` порядок внутри)
-
-<Note>
-Первый `deny` прерывает все последующие политики. Все сообщения `instruct` накапливаются и доставляются вместе.
-</Note>
-
----
-
-## Транзитивные импорты
-
-Файлы пользовательских политик могут импортировать локальные модули, используя относительные пути:
-
-```js
-// my-policies.js
-import { isBlockedPath } from "./utils.js";
-import { checkApproval } from "./approval-client.js";
-
-customPolicies.add({
-  name: "approval-gate",
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
-    return approved ? allow() : deny("Approval required for this command");
-  },
-});
-```
-
-Все относительные импорты, доступные из файла входа, разрешаются. Это реализуется путём переписывания импортов `from "failproofai"` на фактический путь dist и создания временных файлов `.mjs` для обеспечения совместимости ESM.
-
----
-
-## Фильтрация по типу события
-
-Используйте `match.events` для ограничения, когда срабатывает политика:
-
-```js
-customPolicies.add({
-  name: "require-summary-on-stop",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    // Срабатывает только при завершении сессии
-    // ctx.session.transcriptPath содержит полный журнал сессии
-    return allow();
-  },
-});
-```
-
-Опустите `match` полностью, чтобы срабатывать при каждом типе события.
-
----
-
-## Обработка ошибок и режимы сбоя
-
-Пользовательские политики — **fail-open**: ошибки никогда не блокируют встроенные политики и не приводят к краху обработчика hook.
-
-| Сбой | Поведение |
-|------|-----------|
-| `customPoliciesPath` не установлен | Явные пользовательские политики не запускаются; встроенные и политики соглашения продолжают работать нормально |
-| Файл не найден | Предупреждение записывается в `~/.failproofai/hook.log`; встроенные продолжают работать |
-| Синтаксическая/ошибка импорта (явная) | Ошибка записывается в `~/.failproofai/hook.log`; явные пользовательские политики пропускаются |
-| Синтаксическая/ошибка импорта (соглашение) | Ошибка записывается; этот файл пропускается, остальные файлы соглашения всё ещё загружаются |
-| `fn` выбрасывает исключение во время выполнения | Ошибка записывается; этот hook рассматривается как `allow`; остальные hooks продолжают работу |
-| `fn` работает дольше 10 сек | Тайм-аут записывается; рассматривается как `allow` |
-| Каталог соглашения отсутствует | Политики соглашения не запускаются; нет ошибки |
-
-<Tip>
-Для отладки ошибок пользовательских политик смотрите файл журнала:
-
-```bash
-tail -f ~/.failproofai/hook.log
-```
-</Tip>
-
----
-
-## Полный пример: несколько политик
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-// Запретить агенту писать в каталог secrets/
-customPolicies.add({
-  name: "block-secrets-dir",
-  description: "Prevent agent from writing to secrets/ directory",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
-    const path = ctx.toolInput?.file_path ?? "";
-    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
-    return allow();
-  },
-});
-
-// Держать агента на пути: проверить тесты перед коммитом
-customPolicies.add({
-  name: "remind-test-before-commit",
-  description: "Keep the agent on track: verify tests pass before committing",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = ctx.toolInput?.command ?? "";
-    if (/git\s+commit/.test(cmd)) {
-      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
-    }
-    return allow();
-  },
-});
-
-// Запретить незапланированные изменения зависимостей во время freeze
-customPolicies.add({
-  name: "dependency-freeze",
-  description: "Prevent unplanned dependency changes during freeze period",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = ctx.toolInput?.command ?? "";
-    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
-    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
-      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
-    }
-    return allow();
-  },
-});
-
-export { customPolicies };
-```
-
----
-
-## Примеры
-
-Каталог `examples/` содержит готовые к запуску файлы политик:
-
-| Файл | Содержимое |
-|------|-----------|
-| `examples/policies-basic.js` | Пять начальных политик, охватывающих распространённые режимы сбоев агента |
-| `examples/policies-advanced/index.js` | Продвинутые паттерны: транзитивные импорты, асинхронные вызовы, очистка выходных данных и hooks конца сессии |
-| `examples/convention-policies/security-policies.mjs` | Политики безопасности на основе соглашения (блокировка записей .env, предотвращение переписывания истории git) |
-| `examples/convention-policies/workflow-policies.mjs` | Политики рабочего процесса на основе соглашения (напоминания о тестах, аудит записей файлов) |
-
-### Использование примеров с явным файлом
-
-```bash
-failproofai policies --install --custom ./examples/policies-basic.js
-```
-
-### Использование примеров на основе соглашения
-
-```bash
-# Копировать на уровень проекта
-mkdir -p .failproofai/policies
-cp examples/convention-policies/*.mjs .failproofai/policies/
-
-# Или копировать на уровень пользователя
-mkdir -p ~/.failproofai/policies
-cp examples/convention-policies/*.mjs ~/.failproofai/policies/
-```
-
-Команда установки не требуется — файлы будут подхвачены автоматически при следующем событии hook.

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

@@ -1,142 +0,0 @@
----
-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>