failproofai 0.0.6-beta.3 → 0.0.6-beta.4

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

@@ -1,260 +0,0 @@
----
-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) с `happy-dom`.
-
-```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-пакет, который используют файлы пользовательских хуков при импорте из `'failproofai'`:
-
-```bash
-bun build src/index.ts --outdir dist --target node --format cjs
-```
-
-Затем запустите тесты:
-
-```bash
-bun run test:e2e
-```
-
-Пересобирайте `dist/` всякий раз, когда вы изменяете публичный API хуков (`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, захват кода выхода + stdout + stderr
-    fixture-env.ts      # Изолированные на тест временные каталоги с файлами конфига
-    payloads.ts         # Фабрики полезных нагрузок с точностью Claude для каждого типа события
-  hooks/
-    builtin-policies.e2e.test.ts   # Каждая встроенная политика с реальным подпроцессом
-    custom-hooks.e2e.test.ts       # Загрузка и оценка пользовательских хуков
-    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("");  // allow → пустой stdout
-  });
-});
-```
-
-### Формы ответов E2E
-
-| Решение | Код выхода | stdout |
-|----------|-----------|--------|
-| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
-| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
-| Instruct (не-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
-| Stop instruct | `2` | пустой stdout; причина в stderr |
-| Allow | `0` | пустая строка |
-
-### Конфигурация Vitest
-
-E2E тесты используют `vitest.config.e2e.mts` с:
-
-- `environment: "node"` - глобальные переменные браузера не требуются
-- `pool: "forks"` - истинная изоляция процессов (тесты запускают подпроцессы)
-- `testTimeout: 20_000` - 20 сек на тест (запуск бинарного файла + оценка хука)
-
-Пул `forks` важен: рабочие потоки используют совместно `globalThis`, что может помешать тестам, запускающим подпроцессы. Процессные fork избегают этой проблемы.
-
----
-
-## CI
-
-Полный запуск CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) должен пройти перед слиянием. Набор E2E запускается как отдельная задача CI параллельно.
-
-См. [Contributing](../CONTRIBUTING.md) для полного контрольного списка перед слиянием.

package/.next/standalone/docs/testing.mdx

@@ -1,260 +0,0 @@
----
-title: Testing
-description: "Unit tests, E2E tests, and test helpers"
-icon: flask-vial
----
-
-failproofai has two test suites: **unit tests** (fast, mocked) and **end-to-end tests** (real subprocess invocations).
-
----
-
-## Running tests
-
-```bash
-# Run all unit tests once
-bun run test:run
-
-# Run unit tests in watch mode
-bun run test
-
-# Run E2E tests (requires setup - see below)
-bun run test:e2e
-
-# Type-check without building
-bunx tsc --noEmit
-
-# Lint
-bun run lint
-```
-
----
-
-## Unit tests
-
-Unit tests live in `__tests__/` and use [Vitest](https://vitest.dev) with `happy-dom`.
-
-```text
-__tests__/
-  hooks/
-    builtin-policies.test.ts      # Policy logic for each builtin
-    hooks-config.test.ts          # Config loading and scope merging
-    policy-evaluator.test.ts      # Param injection and evaluation order
-    custom-hooks-registry.test.ts # globalThis registry add/get/clear
-    custom-hooks-loader.test.ts   # ESM loader, transitive imports, error handling
-    manager.test.ts               # install/remove/list operations
-  components/
-    sessions-list.test.tsx        # Session list component
-    project-list.test.tsx         # Project list component
-    ...
-  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
-```
-
-### Writing a policy unit test
-
-```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());
-  });
-});
-```
-
----
-
-## End-to-end tests
-
-E2E tests invoke the real `failproofai` binary as a subprocess, pipe a JSON payload to stdin, and assert on the stdout output and exit code. This tests the complete integration path that Claude Code uses.
-
-### Setup
-
-E2E tests run the binary directly from the repo source. Before the first run, build the CJS bundle that custom hook files use when they import from `'failproofai'`:
-
-```bash
-bun build src/index.ts --outdir dist --target node --format cjs
-```
-
-Then run the tests:
-
-```bash
-bun run test:e2e
-```
-
-Rebuild `dist/` whenever you change the public hook API (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, or `src/hooks/policy-types.ts`).
-
-### E2E test structure
-
-```text
-__tests__/e2e/
-  helpers/
-    hook-runner.ts      # Spawn the binary, pipe payload JSON, capture exit code + stdout + stderr
-    fixture-env.ts      # Per-test isolated temp directories with config files
-    payloads.ts         # Claude-accurate payload factories for each event type
-  hooks/
-    builtin-policies.e2e.test.ts   # Each builtin policy with real subprocess
-    custom-hooks.e2e.test.ts       # Custom hook loading and evaluation
-    config-scopes.e2e.test.ts      # Config merging across project/local/global
-    policy-params.e2e.test.ts      # Parameter injection for each parameterized policy
-```
-
-### Using the E2E helpers
-
-**`FixtureEnv`** - isolated per-test environment:
-
-```typescript
-import { createFixtureEnv } from "../helpers/fixture-env";
-
-const env = createFixtureEnv();
-// env.cwd    - temp dir; pass as payload.cwd to pick up .failproofai/policies-config.json
-// env.home   - isolated home dir; no real ~/.failproofai leaks in
-
-env.writeConfig({
-  enabledPolicies: ["block-sudo"],
-  policyParams: {
-    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
-  },
-});
-```
-
-`createFixtureEnv()` registers `afterEach` cleanup automatically.
-
-**`runHook`** - invoke the binary:
-
-```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`** - ready-made payload factories:
-
-```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)
-```
-
-### Writing an E2E test
-
-```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("");  // allow → empty stdout
-  });
-});
-```
-
-### E2E response shapes
-
-| Decision | Exit code | stdout |
-|----------|-----------|--------|
-| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
-| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
-| Instruct (non-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
-| Stop instruct | `2` | empty stdout; reason in stderr |
-| Allow | `0` | empty string |
-
-### Vitest config
-
-E2E tests use `vitest.config.e2e.mts` with:
-
-- `environment: "node"` - no browser globals needed
-- `pool: "forks"` - true process isolation (tests spawn subprocesses)
-- `testTimeout: 20_000` - 20s per test (binary startup + hook eval)
-
-The `forks` pool is important: thread-based workers share `globalThis`, which can interfere with subprocess-spawning tests. Process-based forks avoid this.
-
----
-
-## CI
-
-The full CI run (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) is required to pass before merging. The E2E suite runs as a separate CI job in parallel.
-
-See [Contributing](../CONTRIBUTING.md) for the complete pre-merge checklist.