failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/ru/built-in-policies.mdx

@@ -0,0 +1,562 @@
+---
+title: Встроенные политики
+description: "Все 30 встроенных политик, которые ловят распространённые сбои агентов"
+icon: shield
+---
+
+failproofai поставляется с 30 встроенными политиками, которые ловят распространённые сбои агентов. Каждая политика срабатывает на определённый тип события hook и имя инструмента. Девять политик принимают параметры, которые позволяют вам настраивать их поведение без написания кода. Четыре бета-политики рабочего потока обеспечивают выполнение конвейера commit → push → PR → CI перед остановкой Claude.
+
+---
+
+## Обзор
+
+Политики сгруппированы по категориям:
+
+| Категория | Политики | Тип hook |
+|----------|----------|-----------|
+| [Опасные команды](#опасные-команды) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse |
+| [Секреты (санитайзеры)](#секреты-санитайзеры) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse |
+| [Окружение](#окружение) | block-env-files, protect-env-vars | PreToolUse |
+| [Доступ к файлам](#доступ-к-файлам) | block-read-outside-cwd, block-secrets-write | PreToolUse |
+| [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse |
+| [База данных](#база-данных) | warn-destructive-sql, warn-schema-alteration | PreToolUse |
+| [Предупреждения](#предупреждения) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse |
+| [Рабочий поток (beta)](#рабочий-поток-beta) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-ci-green-before-stop | Stop |
+
+- **`block-`** — остановить агента от выполнения действия.
+- **`warn-`** — предоставить агенту дополнительный контекст, чтобы он мог себя исправить.
+- **`sanitize-`** — удалить чувствительные данные из вывода инструмента перед тем, как агент их увидит.
+- **`require-`** — заблокировать событие Stop до выполнения условий.
+
+---
+
+<Tip>
+Каждая политика поддерживает необязательное поле `hint` в `policyParams`. Подсказка добавляется к сообщению deny или instruct, которое видит Claude, предоставляя практические рекомендации без изменения кода политики. Работает со встроенными, пользовательскими и конвенциональными политиками. См. [Configuration → hint](/ru/configuration#hint-cross-cutting) для подробностей.
+</Tip>
+
+---
+
+## Опасные команды
+
+Предотвратите запуск агентами операций, которые сложно отменить или которые могут повредить хост-систему.
+
+### `block-sudo`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Запрещает любую команду `sudo`.
+
+Блокирует вызовы, содержащие ключевое слово `sudo`. Сопоставление паттернов выполняется на разобранных токенах команды, а не на исходной строке, чтобы предотвратить обход через инъекцию оператора shell.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | Точные префиксы команд, которые разрешены. Каждая запись сопоставляется с разобранными токенами argv. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    }
+  }
+}
+```
+
+С этой конфигурацией `sudo systemctl status nginx` разрешена, но `sudo rm /etc/hosts` запрещена.
+
+<Note>
+Паттерны сопоставляются с разобранными токенами, а не с исходной строкой команды. Это предотвращает обход через добавленные операторы shell (например, `sudo systemctl status x; rm -rf /` не совпадает с `sudo systemctl status *`).
+</Note>
+
+---
+
+### `block-rm-rf`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Запрещает `rm -rf`, `rm -fr` и подобные формы рекурсивного удаления.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | Пути, которые безопасно рекурсивно удалять (например, `/tmp`). |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-rm-rf": {
+      "allowPaths": ["/tmp", "/var/cache"]
+    }
+  }
+}
+```
+
+---
+
+### `block-curl-pipe-sh`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Запрещает `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash` и подобные паттерны.
+
+Нет параметров.
+
+---
+
+### `block-failproofai-commands`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Запрещает команды, которые бы деинсталлировали или отключили failproofai (например, `npm uninstall failproofai`, `failproofai policies --uninstall`).
+
+Нет параметров.
+
+---
+
+## Секреты (санитайзеры)
+
+Предотвратите утечку учётных данных агентами в их контекст или вывод. Политики-санитайзеры срабатывают на событиях **PostToolUse**. Когда Claude запускает команду Bash, читает файл или вызывает любой инструмент, эти политики проверяют вывод перед тем, как он возвращается Claude. Если обнаружен паттерн секрета, политика возвращает решение deny, которое предотвращает передачу вывода обратно.
+
+### `sanitize-jwt`
+
+**Событие:** PostToolUse (все инструменты)  
+**По умолчанию:** Скрывает JWT-токены (три base64url сегмента, разделённые `.`).
+
+Нет параметров.
+
+---
+
+### `sanitize-api-keys`
+
+**Событие:** PostToolUse (все инструменты)  
+**По умолчанию:** Скрывает распространённые форматы API-ключей: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS access keys (`AKIA`), Stripe keys (`sk_live_`, `sk_test_`) и Google API keys (`AIza`).
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Дополнительные regex-паттерны для рассмотрения в качестве секретов. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
+        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
+      ]
+    }
+  }
+}
+```
+
+---
+
+### `sanitize-connection-strings`
+
+**Событие:** PostToolUse (все инструменты)  
+**По умолчанию:** Скрывает строки подключения к БД, которые содержат встроенные учётные данные (например, `postgresql://user:password@host/db`).
+
+Нет параметров.
+
+---
+
+### `sanitize-private-key-content`
+
+**Событие:** PostToolUse (все инструменты)  
+**По умолчанию:** Скрывает PEM блоки (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` и т.д.).
+
+Нет параметров.
+
+---
+
+### `sanitize-bearer-tokens`
+
+**Событие:** PostToolUse (все инструменты)  
+**По умолчанию:** Скрывает заголовки `Authorization: Bearer <token>`, где токен содержит 20 или более символов.
+
+Нет параметров.
+
+---
+
+## Окружение
+
+Защитите чувствительную конфигурацию окружения от чтения или раскрытия агентами.
+
+### `block-env-files`
+
+**Событие:** PreToolUse (Bash, Read)  
+**По умолчанию:** Запрещает чтение файлов `.env` через `cat .env`, вызовы инструмента Read с `.env` в качестве пути файла и т.д.
+
+Не блокирует `.envrc` или другие файлы, связанные с окружением — только файлы с именем ровно `.env`.
+
+Нет параметров.
+
+---
+
+### `protect-env-vars`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Запрещает команды, которые выводят переменные окружения: `printenv`, `env`, `echo $VAR`.
+
+Нет параметров.
+
+---
+
+## Доступ к файлам
+
+Держите агентов в пределах проекта и вдали от чувствительных файлов.
+
+### `block-read-outside-cwd`
+
+**Событие:** PreToolUse (Read, Bash)  
+**По умолчанию:** Запрещает чтение файлов вне текущей рабочей директории (корень проекта).
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | Абсолютные префиксы путей, которые разрешены даже если вне cwd. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company/config"]
+    }
+  }
+}
+```
+
+---
+
+### `block-secrets-write`
+
+**Событие:** PreToolUse (Write, Edit)  
+**По умолчанию:** Запрещает запись в файлы, обычно используемые для приватных ключей и сертификатов: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `string[]` | `[]` | Дополнительные паттерны имён файлов (в стиле glob) для блокировки. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-secrets-write": {
+      "additionalPatterns": [".token", ".secret"]
+    }
+  }
+}
+```
+
+---
+
+## Git
+
+Предотвратите случайные push'и, force-push'и и ошибки ветвей, которые сложно отменить.
+
+### `block-push-master`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Запрещает `git push origin main` и `git push origin master`.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | Имена ветвей, которые не могут быть pushed напрямую. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "master", "release", "prod"]
+    }
+  }
+}
+```
+
+<Tip>
+Чтобы разрешить push'и на все ветви (фактически отключив эту политику без удаления её из `enabledPolicies`), установите `protectedBranches: []`.
+</Tip>
+
+---
+
+### `block-work-on-main`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Запрещает прямой checkout ветвей `main` или `master`.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | Имена ветвей, которые не могут быть checked out напрямую. |
+
+---
+
+### `block-force-push`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Запрещает `git push --force` и `git push -f`.
+
+Нет специфичных для политики параметров. Используйте кросс-функциональную [`hint`](/ru/configuration#hint-cross-cutting) для предложения альтернатив:
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Создайте новую ветвь из текущего HEAD (например, `git checkout -b <new-branch>`) и вместо этого push'ьте её."
+    }
+  }
+}
+```
+
+---
+
+### `warn-git-amend`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude действовать осторожно при запуске `git commit --amend`. Не блокирует команду.
+
+Нет параметров.
+
+---
+
+### `warn-git-stash-drop`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude подтвердить перед запуском `git stash drop`. Не блокирует команду.
+
+Нет параметров.
+
+---
+
+### `warn-all-files-staged`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude проверить, что он staging'ует при запуске `git add -A` или `git add .`. Не блокирует команду.
+
+Нет параметров.
+
+---
+
+## База данных
+
+Поймайте деструктивные SQL-операции перед выполнением их против вашей БД.
+
+### `warn-destructive-sql`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude подтвердить перед запуском SQL, содержащего `DROP TABLE`, `DROP DATABASE` или `DELETE` без `WHERE` клаузулы.
+
+Нет параметров.
+
+---
+
+### `warn-schema-alteration`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude подтвердить перед запуском `ALTER TABLE` statements.
+
+Нет параметров.
+
+---
+
+## Предупреждения
+
+Предоставьте агентам дополнительный контекст перед потенциально рискованными, но неразрушительными операциями.
+
+### `warn-large-file-write`
+
+**Событие:** PreToolUse (Write)  
+**По умолчанию:** Инструктирует Claude подтвердить перед записью файлов больше 1024 KB.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|-------|------|---------|-------------|
+| `thresholdKb` | `number` | `1024` | Порог размера файла в килобайтах, выше которого выдаётся предупреждение. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "warn-large-file-write": {
+      "thresholdKb": 256
+    }
+  }
+}
+```
+
+<Note>
+Обработчик hook усиливает ограничение на stdin в 1 MB для payload'ей. Чтобы протестировать эту политику с малым содержимым, установите `thresholdKb` на значение намного ниже 1024.
+</Note>
+
+---
+
+### `warn-package-publish`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude подтвердить перед запуском `npm publish`.
+
+Нет параметров.
+
+---
+
+### `warn-background-process`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude быть осторожным при запуске фоновых процессов через `nohup`, `&`, `disown` или `screen`.
+
+Нет параметров.
+
+---
+
+### `warn-global-package-install`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude подтвердить перед запуском `npm install -g`, `yarn global add` или `pip install` без виртуального окружения.
+
+Нет параметров.
+
+---
+
+## Поведение AI
+
+Обнаружьте, когда агенты застревают или ведут себя неожиданно.
+
+### `warn-repeated-tool-calls`
+
+**Событие:** PreToolUse (все инструменты)  
+**По умолчанию:** Инструктирует Claude пересмотреть, когда один и тот же инструмент вызывается 3+ раза с идентичными параметрами — распространённый признак того, что агент застрял в цикле.
+
+Нет параметров.
+
+---
+
+## Рабочий поток (beta)
+
+Усильте дисциплинированный рабочий поток конца сессии. Эти политики срабатывают на событие **Stop** и запрещают Claude остановиться до выполнения каждого условия. Они следуют естественной цепочке зависимостей: commit → push → PR → CI. Если политика запрещает, последующие политики в цепочке пропускаются (deny коротко-замыкает).
+
+Все политики рабочего потока **fail-open**: если требуемый инструмент не доступен (например, `gh` не установлен, нет удалённого git репозитория), политика разрешает с информационным сообщением, объясняющим причину пропуска проверки.
+
+### `require-commit-before-stop`
+
+**Событие:** Stop  
+**По умолчанию:** Запрещает остановку, когда есть незакоммитные изменения (изменённые, staged или неотследённые файлы). Возвращает информационное сообщение, когда рабочая директория чистая.
+
+Нет параметров.
+
+---
+
+### `require-push-before-stop`
+
+**Событие:** Stop  
+**По умолчанию:** Запрещает остановку, когда есть unpushed коммиты или когда текущая ветвь не имеет удалённой ветви для отслеживания. Предлагает `git push -u` для создания ветви отслеживания при необходимости. Fail open если нет настроенного удалённого репозитория.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|-------|------|---------|-------------|
+| `remote` | `string` | `"origin"` | Имя удалённого репозитория для push'а. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "require-push-before-stop": {
+      "remote": "upstream"
+    }
+  }
+}
+```
+
+---
+
+### `require-pr-before-stop`
+
+**Событие:** Stop  
+**По умолчанию:** Запрещает остановку, когда не существует pull request'а для текущей ветви или когда существующий PR закрыт/merged. Инструктирует Claude создать PR с `gh pr create`.
+
+Нет параметров.
+
+<Note>
+Эта политика требует установленного и аутентифицированного [GitHub CLI](https://cli.github.com/) (`gh`).
+Запустите `gh auth login` с персональным токеном доступа, имеющим область `repo` для чтения pull request'ов. Если `gh` не установлен или не аутентифицирован, политика fail open и сообщит причину Claude.
+</Note>
+
+---
+
+### `require-ci-green-before-stop`
+
+**Событие:** Stop  
+**По умолчанию:** Запрещает остановку, когда CI проверки падают или всё ещё выполняются на текущей ветви. Проверяет как GitHub Actions workflow runs, так и проверки сторонних ботов (например, CodeRabbit, SonarCloud, Codecov). Рассматривает заключения `skipped` как успех. Возвращает информационное сообщение когда все проверки проходят.
+
+Нет параметров.
+
+<Note>
+Эта политика требует установленного и аутентифицированного [GitHub CLI](https://cli.github.com/) (`gh`).
+Запустите `gh auth login` с персональным токеном доступа, имеющим область `repo` для чтения Actions workflow runs и Checks API. Если `gh` не установлен или не аутентифицирован, политика fail open и сообщит причину Claude.
+</Note>
+
+---
+
+## Бета-политики
+
+Некоторые политики помечены `beta` и не устанавливаются по умолчанию. Бета-политики могут иметь шероховатости или генерировать ложные срабатывания. Они переходят в стабильное состояние в будущих релизах.
+
+**Текущие бета-политики:**
+
+- `require-commit-before-stop` — закоммитьте все изменения перед остановкой
+- `require-push-before-stop` — push'ьте все коммиты на удалённый репозиторий
+- `require-pr-before-stop` — убедитесь, что PR существует для ветви
+- `require-ci-green-before-stop` — все CI проверки должны пройти
+
+Вместе они усиливают рабочий поток **commit → push → PR → CI**.
+
+Для установки всех бета-политик:
+
+```bash
+failproofai policies --install --beta
+```
+
+Или установите конкретные политики рабочего потока:
+
+```bash
+failproofai policies --install require-commit-before-stop require-push-before-stop require-pr-before-stop require-ci-green-before-stop
+```
+
+Запустите `failproofai policies` для просмотра того, какие политики имеют флаг beta.
+
+---
+
+## Отключение отдельных политик
+
+Удалите конкретную политику из `enabledPolicies` в вашей конфигурации или переключите её в табе Policies на панели управления.
+
+```json
+{
+  "enabledPolicies": [
+    "block-rm-rf",
+    "sanitize-api-keys"
+  ]
+}
+```
+
+Политики, не перечисленные в `enabledPolicies`, не запускаются, даже если для них существуют записи `policyParams`.

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

@@ -0,0 +1,28 @@
+---
+title: Просмотр сеансов
+description: "Запустите панель управления для просмотра сеансов агентов и управления политиками"
+---
+
+```bash
+failproofai
+```
+
+Запускает веб-панель управления по адресу `http://localhost:8020`.
+
+## Параметры
+
+| Флаг | Описание |
+|------|---------|
+| `--port <number>` | Порт для прослушивания (по умолчанию: `8020`) |
+| `--projects-path <path>` | Переопределить расположение папок проектов Claude Code |
+| `--allowed-origins <origins>` | Список хостов/IP-адресов через запятую, которым разрешен доступ к ресурсам разработки |
+
+## Примеры
+
+```bash
+# Запуск на другом порту
+failproofai --port 9000
+
+# Использование пользовательского пути проектов
+failproofai --projects-path ~/my-claude-projects
+```

package/.next/standalone/docs/ru/cli/environment-variables.mdx

@@ -0,0 +1,34 @@
+---
+title: Переменные окружения
+description: "Настройка поведения failproofai с помощью переменных окружения"
+---
+
+## Dashboard
+
+| Переменная | Описание |
+|----------|-------------|
+| `PORT` | Порт панели управления (по умолчанию: `8020`) |
+| `CLAUDE_PROJECTS_PATH` | Переопределить расположение папок проектов Claude Code |
+| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Список страниц панели управления для скрытия, разделённый запятыми |
+| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Хосты/IP-адреса, которым разрешён доступ к ресурсам для разработки. То же самое, что `--allowed-origins`. |
+
+## Логирование
+
+| Переменная | Описание |
+|----------|-------------|
+| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Уровень логирования сервера (по умолчанию: `warn`) |
+| `FAILPROOFAI_HOOK_LOG_FILE` | Пользовательский путь файла логов хуков или `true` для стандартного пути (`~/.failproofai/logs/hooks.log`) |
+
+## Телеметрия
+
+| Переменная | Описание |
+|----------|-------------|
+| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Отключить анонимную телеметрию использования |
+
+## LLM (для оценки политик)
+
+| Переменная | Описание |
+|----------|-------------|
+| `FAILPROOFAI_LLM_BASE_URL` | Endpoint API LLM (по умолчанию: `https://api.openai.com/v1`) |
+| `FAILPROOFAI_LLM_API_KEY` | API ключ для политик на базе LLM |
+| `FAILPROOFAI_LLM_MODEL` | Имя модели (по умолчанию: `gpt-4o-mini`) |

package/.next/standalone/docs/ru/cli/hook.mdx

@@ -0,0 +1,30 @@
+---
+title: Обработчик хука (внутренний)
+description: "Подпроцесс, который вызывает Claude Code при каждом событии инструмента"
+---
+
+```bash
+failproofai --hook <EventType>
+```
+
+Это команда, зарегистрированная в `settings.json` Claude Code через `failproofai policies --install`. Обычно вы не вызываете её напрямую.
+
+Читает JSON-полезную нагрузку из stdin, вычисляет все включённые политики и выходит с кодом, указывающим на решение:
+
+| Код выхода | Решение | Эффект |
+|-----------|---------|--------|
+| `0` | `allow` | Разрешить действие |
+| `1` | `deny` | Заблокировать действие — Claude видит причину отказа |
+| `2` | `instruct` | Внедрить руководство в контекст Claude |
+
+### Поддерживаемые типы событий
+
+| Категория | События |
+|-----------|---------|
+| **Выполнение инструментов** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` |
+| **Жизненный цикл сеанса** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` |
+| **Взаимодействие пользователя** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` |
+| **Подагенты и задачи** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` |
+| **Конфигурация** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` |
+| **Файловая система** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` |
+| **Контекст** | `PreCompact`, `PostCompact` |