failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,357 @@
+---
+title: Пользовательские политики
+description: "Напишите свои собственные политики на JavaScript - применяйте соглашения, предотвращайте дрейф, обнаруживайте сбои, интегрируйте с внешними системами"
+icon: code
+---
+
+Пользовательские политики позволяют написать правила для любого поведения агента: применять соглашения проекта, предотвращать дрейф, блокировать деструктивные операции, обнаруживать зависшие агенты или интегрироваться с Slack, рабочими процессами одобрения и многим другим. Они используют ту же систему событий перехватчиков и решения `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: На основе соглашений (рекомендуется, v0.0.2-beta.7+)
+
+Поместите файлы `*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`. Файл загружается заново при каждом событии перехватчика — кэширования между событиями нет.
+
+### Использование обоих способов вместе
+
+Политики на основе соглашений и явный файл `--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/`) политик. См. [Конфигурация → hint](/ru/configuration#hint-cross-cutting) для подробностей.
+</Tip>
+
+### Информационные сообщения allow (бета)
+
+<Note>
+`allow(message)` — это функция бета, доступная с v0.0.2-beta.3. API может измениться в будущих версиях. Более ранние версии поддерживают только `allow()` без аргументов.
+</Note>
+
+`allow(message)` разрешает операцию **и** отправляет информационное сообщение обратно Claude. Сообщение доставляется как `additionalContext` в ответе stdout обработчика перехватчика — тот же механизм, используемый `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" \| ... }` - перехватчики должны всегда возвращать `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**: ошибки никогда не блокируют встроенные политики и не приводят к сбою обработчика перехватчика.
+
+| Отказ | Поведение |
+|-------|----------|
+| `customPoliciesPath` не установлен | Явные пользовательские политики не запускаются; встроенные политики продолжают нормально работать |
+| Файл не найден | Предупреждение записывается в `~/.failproofai/hook.log`; встроенные политики продолжают работать |
+| Синтаксис/ошибка импорта (явная) | Ошибка записывается в `~/.failproofai/hook.log`; явные пользовательские политики пропускаются |
+| Синтаксис/ошибка импорта (соглашение) | Ошибка записывается; этот файл пропускается, другие файлы соглашений загружаются |
+| `fn` выбрасывает ошибку во время выполнения | Ошибка записывается; этот перехватчик рассматривается как `allow`; другие перехватчики продолжают работу |
+| `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();
+  },
+});
+
+// Предотвращайте незапланированные изменения зависимостей во время заморозки
+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` | Продвинутые паттерны: транзитивные импорты, асинхронные вызовы, очистка выводов и перехватчики завершения сессии |
+| `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/
+```
+
+Команда установки не требуется — файлы выбираются автоматически при следующем событии перехватчика.

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>