failproofai 0.0.2 → 0.0.4-beta.0

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

@@ -0,0 +1,82 @@
+---
+title: Альтернативные имена пакетов
+description: "Зарегистрированные альтернативные имена для защиты от опечаток и их работа"
+icon: copy
+---
+
+## Официальный пакет
+
+Основной npm-пакет — **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# или
+bun add -g failproofai
+```
+
+---
+
+## Почему мы владеем альтернативными именами
+
+Typosquatting — это распространённая атака на цепочку поставок, при которой злоумышленник регистрирует имя пакета, отличающееся на один символ от популярного пакета. Невнимательные пользователи, допустившие опечатку в команде установки, в итоге запускают код, контролируемый злоумышленником, с полным доступом к системе — это именно тот вид угрозы, против которого разработана Failproof AI.
+
+Чтобы исключить эту уязвимость, **мы заранее регистрируем все распространённые опечатки и варианты написания** `failproofai` на npm. Ни одно из этих имён не может быть зарегистрировано третьей стороной. Каждое из них — это тонкий прокси, который устанавливает и делегирует работу основному пакету `failproofai`.
+
+---
+
+## Зарегистрированные альтернативные имена
+
+**Варианты написания** — разные способы написания "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, чтобы зарезервировать эти имена в целях защиты от typosquatting. Они будут активированы после одобрения.
+
+Вы можете проверить, что любое опубликованное альтернативное имя принадлежит нам:
+
+```bash
+npm info failproof
+# Ищите: "ExosphereHost Inc." в поле maintainers
+```
+
+---
+
+## Как работают альтернативные имена
+
+Каждый пакет-альтернатива:
+
+1. Указывает `failproofai` как зависимость — поэтому при установке запускается основной пакет (включая его hook `postinstall`)
+2. Экспортирует бинарный файл с собственным именем (например `failprof-ai`), который пробрасывает все аргументы на бинарный файл `failproofai`
+
+Прокси — это двухстрочный скрипт Node.js; в нём нет никакой логики, сетевых запросов и сбора данных, кроме того, что делает сам `failproofai`.
+
+---
+
+## Если мы пропустили какое-то имя
+
+Откройте задачу на [exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues) и мы его зарегистрируем.

package/.next/standalone/docs/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) с `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.md → testing.mdx}

@@ -17,7 +17,7 @@ bun run test:run
 # Run unit tests in watch mode
 bun run test
 
-# Run E2E tests (requires setup — see below)
+# Run E2E tests (requires setup - see below)
 bun run test:e2e
 
 # Type-check without building
@@ -33,7 +33,7 @@ bun run lint
 
 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
@@ -130,7 +130,7 @@ Rebuild `dist/` whenever you change the public hook API (`src/hooks/custom-hooks
 
 ### E2E test structure
 
-```
+```text
 __tests__/e2e/
   helpers/
     hook-runner.ts      # Spawn the binary, pipe payload JSON, capture exit code + stdout + stderr
@@ -145,14 +145,14 @@ __tests__/e2e/
 
 ### Using the E2E helpers
 
-**`FixtureEnv`** — isolated per-test environment:
+**`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.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"],
@@ -164,7 +164,7 @@ env.writeConfig({
 
 `createFixtureEnv()` registers `afterEach` cleanup automatically.
 
-**`runHook`** — invoke the binary:
+**`runHook`** - invoke the binary:
 
 ```typescript
 import { runHook } from "../helpers/hook-runner";
@@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0);
 expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
 ```
 
-**`Payloads`** — ready-made payload factories:
+**`Payloads`** - ready-made payload factories:
 
 ```typescript
 Payloads.preToolUse.bash(command, cwd)
@@ -245,9 +245,9 @@ describe("block-rm-rf (E2E)", () => {
 
 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)
+- `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.