failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,82 @@
+---
+title: Aliases пакетов
+description: "Зарегистрированные aliases для предотвращения опечаток и как они работают"
+icon: copy
+---
+
+## Официальный пакет
+
+Канонический npm пакет — это **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# or
+bun add -g failproofai
+```
+
+---
+
+## Почему мы владеем этими aliases
+
+Typosquatting — это распространённая атака на цепочку поставок, при которой злоумышленник регистрирует название пакета, отличающееся от популярного пакета на один символ. Пользователи, которые случайно ошибаются при вводе команды установки, запускают контролируемый атакующим код с полным доступом к системе — именно против такого рода угроз разработана система Failproof AI.
+
+Чтобы исключить эту уязвимость, **мы заблаговременно зарегистрировали все распространённые опечатки и варианты написания** `failproofai` на npm. Никто из третьих лиц не может зарегистрировать эти названия. Каждое из них — это тонкий proxy, который устанавливает и делегирует работу реальному пакету `failproofai`.
+
+---
+
+## Зарегистрированные aliases
+
+**Варианты написания** — разные способы написания "failproof ai":
+
+| Пакет | Статус |
+|---------|--------|
+| `failproof` | ✅ Опубликовано |
+| `failproof-ai` | ⏳ Ожидание поддержки npm |
+| `fail-proof-ai` | ⏳ Ожидание поддержки npm |
+| `failproof_ai` | ⏳ Ожидание поддержки npm |
+| `fail_proof_ai` | ⏳ Ожидание поддержки npm |
+| `fail-proofai` | ⏳ Ожидание поддержки npm |
+
+**`failprof*` опечатки** — пропущена одна буква `o` в слове "proof":
+
+| Пакет | Статус |
+|---------|--------|
+| `failprof` | ✅ Опубликовано |
+| `failprof-ai` | ✅ Опубликовано |
+| `failprofai` | ⏳ Ожидание поддержки npm |
+| `fail-prof-ai` | ⏳ Ожидание поддержки npm |
+| `failprof_ai` | ⏳ Ожидание поддержки npm |
+
+**`faliproof*` опечатки** — переставлены буквы `a` и `i`:
+
+| Пакет | Статус |
+|---------|--------|
+| `faliproof` | ✅ Опубликовано |
+| `faliproof-ai` | ✅ Опубликовано |
+| `faliproofai` | ⏳ Ожидание поддержки npm |
+
+> **Почему ожидание?** Политика npm по борьбе со спамом блокирует названия, которые нормализуются в ту же строку, что и существующий пакет, после удаления пунктуации и применения проверок на схожесть. Мы обратились в поддержку npm, чтобы зарезервировать эти названия в целях предотвращения squat-атак. Они будут активированы после одобрения.
+
+Вы можете проверить, что любой опубликованный alias принадлежит нам:
+
+```bash
+npm info failproof
+# Найдите: "ExosphereHost Inc." в поле maintainers
+```
+
+---
+
+## Как работают aliases
+
+Каждый alias пакет:
+
+1. Указывает `failproofai` как зависимость — таким образом устанавливается реальный пакет и становится доступным его binary
+2. Предоставляет binary с именем, совпадающим с его собственным названием (например `failprof-ai`), который передаёт все аргументы в binary `failproofai`
+
+Proxy — это двухстрочный скрипт Node.js; в нём нет логики, сетевых запросов и сбора данных помимо того, что делает сам `failproofai`.
+
+---
+
+## Если мы пропустили какое-то название
+
+Откройте issue в [failproofai/failproofai](https://github.com/failproofai/failproofai/issues), и мы зарегистрируем его.

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

@@ -0,0 +1,260 @@
+---
+title: Тестирование
+description: "Модульные тесты, E2E-тесты и вспомогательные утилиты для тестирования"
+icon: flask-vial
+---
+
+failproofai имеет два набора тестов: **модульные тесты** (быстрые, с моками) и **сквозные тесты** (реальные вызовы подпроцессов).
+
+---
+
+## Запуск тестов
+
+```bash
+# Запустить все модульные тесты один раз
+bun run test:run
+
+# Запустить модульные тесты в режиме наблюдения
+bun run test
+
+# Запустить E2E-тесты (требует предварительной настройки - см. ниже)
+bun run test:e2e
+
+# Проверка типов без сборки
+bunx tsc --noEmit
+
+# Проверка кода
+bun run lint
+```
+
+---
+
+## Модульные тесты
+
+Модульные тесты находятся в `__tests__/` и используют [Vitest](https://vitest.dev) с `jsdom`.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # Логика политик для каждой встроенной политики
+    hooks-config.test.ts          # Загрузка конфига и слияние областей видимости
+    policy-evaluator.test.ts      # Инъекция параметров и порядок оценки
+    custom-hooks-registry.test.ts # Регистр globalThis - добавление/получение/очистка
+    custom-hooks-loader.test.ts   # ESM загрузчик, транзитивные импорты, обработка ошибок
+    manager.test.ts               # Операции установки/удаления/списания
+  components/
+    sessions-list.test.tsx        # Компонент списка сессий
+    project-list.test.tsx         # Компонент списка проектов
+    ...
+  lib/
+    logger.test.ts
+    paths.test.ts
+    date-filters.test.ts
+    telemetry.test.ts
+    ...
+  actions/
+    get-hooks-config.test.ts
+    get-hook-activity.test.ts
+    ...
+  contexts/
+    ThemeContext.test.tsx
+    AutoRefreshContext.test.tsx
+```
+
+### Написание модульного теста политики
+
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { getBuiltinPolicies } from "../../src/hooks/builtin-policies";
+import { allow, deny } from "../../src/hooks/policy-types";
+
+describe("block-sudo", () => {
+  const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!;
+
+  it("denies sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo apt install nodejs" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai"));
+  });
+
+  it("allows non-sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "ls -la" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+
+  it("allows patterns in allowPatterns", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo systemctl status nginx" },
+      params: { allowPatterns: ["sudo systemctl status"] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+});
+```
+
+---
+
+## Сквозные тесты
+
+E2E-тесты вызывают реальный бинарный файл `failproofai` в виде подпроцесса, отправляют JSON-полезную нагрузку в stdin и проверяют вывод на stdout и код выхода. Это тестирует полный путь интеграции, который использует Claude Code.
+
+### Настройка
+
+E2E-тесты запускают бинарный файл непосредственно из исходного кода репозитория. Перед первым запуском соберите CJS-пакет, который используют файлы пользовательских hook при импорте из `'failproofai'`:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+Затем запустите тесты:
+
+```bash
+bun run test:e2e
+```
+
+Пересоберите `dist/` каждый раз, когда вы изменяете публичный API hook (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` или `src/hooks/policy-types.ts`).
+
+### Структура E2E-теста
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # Запуск бинарного файла, отправка JSON в stdin, получение кода выхода + stdout + stderr
+    fixture-env.ts      # Изолированные для каждого теста временные директории с файлами конфига
+    payloads.ts         # Фабрики полезных нагрузок для каждого типа события, совместимые с Claude
+  hooks/
+    builtin-policies.e2e.test.ts   # Каждая встроенная политика с реальным подпроцессом
+    custom-hooks.e2e.test.ts       # Загрузка и оценка пользовательских hook
+    config-scopes.e2e.test.ts      # Слияние конфига в проекте/локально/глобально
+    policy-params.e2e.test.ts      # Инъекция параметров для каждой параметризованной политики
+```
+
+### Использование E2E-вспомогательных утилит
+
+**`FixtureEnv`** - изолированная среда для каждого теста:
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - временная директория; передайте как payload.cwd для использования .failproofai/policies-config.json
+// env.home   - изолированная домашняя директория; никакие настоящие ~/.failproofai не протекают
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` автоматически регистрирует очистку `afterEach`.
+
+**`runHook`** - вызов бинарного файла:
+
+```typescript
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+const result = await runHook(
+  "PreToolUse",
+  Payloads.preToolUse.bash("sudo apt install nodejs", env.cwd),
+  { homeDir: env.home }
+);
+
+expect(result.exitCode).toBe(0);
+expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+```
+
+**`Payloads`** - готовые фабрики полезных нагрузок:
+
+```typescript
+Payloads.preToolUse.bash(command, cwd)
+Payloads.preToolUse.write(filePath, content, cwd)
+Payloads.preToolUse.read(filePath, cwd)
+Payloads.postToolUse.bash(command, output, cwd)
+Payloads.postToolUse.read(filePath, content, cwd)
+Payloads.notification(message, cwd)
+Payloads.stop(cwd)
+```
+
+### Написание E2E-теста
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { createFixtureEnv } from "../helpers/fixture-env";
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+describe("block-rm-rf (E2E)", () => {
+  it("denies rm -rf", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm -rf /", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+  });
+
+  it("allows non-recursive rm", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm /tmp/file.txt", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("");  // разрешено → пустой stdout
+  });
+});
+```
+
+### Форматы ответов E2E
+
+| Решение | Код выхода | stdout |
+|----------|-----------|--------|
+| `PreToolUse` отклонено | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` отклонено | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Инструкция (не Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop-инструкция | `2` | пустой stdout; причина в stderr |
+| Разрешить | `0` | пустая строка |
+
+### Конфиг Vitest
+
+E2E-тесты используют `vitest.config.e2e.mts` с:
+
+- `environment: "node"` - браузерные глобальные переменные не требуются
+- `pool: "forks"` - истинная изоляция процессов (тесты запускают подпроцессы)
+- `testTimeout: 20_000` - 20s на тест (запуск бинарного файла + оценка hook)
+
+Пул `forks` важен: рабочие на основе потоков совместно используют `globalThis`, что может помешать тестам, запускающим подпроцессы. Форки на основе процессов избегают этого.
+
+---
+
+## CI
+
+Полный запуск CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) должен пройти перед слиянием. E2E-набор запускается как отдельное задание CI параллельно.
+
+Смотрите [Участие в разработке](../CONTRIBUTING.md) для полного контрольного списка перед слиянием.

package/.next/standalone/docs-old/styles/config/vocabularies/Mintlify/accept.txt

@@ -0,0 +1,52 @@
+failproofai
+Claude
+Anthropic
+Codex
+Copilot
+Cursor
+OpenCode
+PreToolUse
+PostToolUse
+SessionStart
+SessionEnd
+UserPromptSubmit
+SubagentStop
+PreCompact
+Notification
+CLIs
+Namespaces
+namespace
+allowlist
+denylist
+blocklist
+subcommands
+argv
+metacharacters
+Codecov
+CodeRabbit
+SonarCloud
+LiteLLM
+Mintlify
+MCP
+dogfood
+bun
+bunx
+npx
+pnpx
+pnpm
+uv
+pipenv
+conda
+gcloud
+systemctl
+kubectl
+terraform
+helm
+curl
+wget
+mjs
+cjs
+tsx
+jsx
+failopen
+failclosed