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

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

@@ -1,260 +0,0 @@
----
-title: Kiểm thử
-description: "Kiểm thử đơn vị, kiểm thử end-to-end và trình hỗ trợ kiểm thử"
-icon: flask-vial
----
-
-failproofai có hai bộ kiểm thử: **kiểm thử đơn vị** (nhanh, được mock) và **kiểm thử end-to-end** (gọi subprocess thực tế).
-
----
-
-## Chạy kiểm thử
-
-```bash
-# Chạy tất cả kiểm thử đơn vị một lần
-bun run test:run
-
-# Chạy kiểm thử đơn vị ở chế độ watch
-bun run test
-
-# Chạy kiểm thử E2E (yêu cầu cài đặt - xem bên dưới)
-bun run test:e2e
-
-# Kiểm tra kiểu dữ liệu mà không xây dựng
-bunx tsc --noEmit
-
-# Lint
-bun run lint
-```
-
----
-
-## Kiểm thử đơn vị
-
-Các kiểm thử đơn vị nằm trong `__tests__/` và sử dụng [Vitest](https://vitest.dev) với `happy-dom`.
-
-```text
-__tests__/
-  hooks/
-    builtin-policies.test.ts      # Logic chính sách cho mỗi builtin
-    hooks-config.test.ts          # Tải config và gộp scope
-    policy-evaluator.test.ts      # Tiêm param và thứ tự đánh giá
-    custom-hooks-registry.test.ts # Thêm/lấy/xóa registry globalThis
-    custom-hooks-loader.test.ts   # Trình tải ESM, import bắc cầu, xử lý lỗi
-    manager.test.ts               # Hoạt động install/remove/list
-  components/
-    sessions-list.test.tsx        # Thành phần danh sách phiên
-    project-list.test.tsx         # Thành phần danh sách dự án
-    ...
-  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
-```
-
-### Viết kiểm thử đơn vị cho chính sách
-
-```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());
-  });
-});
-```
-
----
-
-## Kiểm thử end-to-end
-
-Các kiểm thử E2E gọi binary `failproofai` thực tế dưới dạng subprocess, pipe payload JSON tới stdin, và kiểm tra kết quả stdout và mã thoát. Điều này kiểm thử đường dẫn tích hợp hoàn chỉnh mà Claude Code sử dụng.
-
-### Cài đặt
-
-Các kiểm thử E2E chạy binary trực tiếp từ mã nguồn repo. Trước lần chạy đầu tiên, xây dựng gói CJS mà các tệp custom hook sử dụng khi nhập từ `'failproofai'`:
-
-```bash
-bun build src/index.ts --outdir dist --target node --format cjs
-```
-
-Sau đó chạy kiểm thử:
-
-```bash
-bun run test:e2e
-```
-
-Xây dựng lại `dist/` bất cứ khi nào bạn thay đổi API hook công khai (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, hoặc `src/hooks/policy-types.ts`).
-
-### Cấu trúc kiểm thử E2E
-
-```text
-__tests__/e2e/
-  helpers/
-    hook-runner.ts      # Sinh binary, pipe payload JSON, bắt mã thoát + stdout + stderr
-    fixture-env.ts      # Thư mục tạm biệt lập cho mỗi kiểm thử với các tệp config
-    payloads.ts         # Nhà máy payload chính xác theo Claude cho mỗi loại sự kiện
-  hooks/
-    builtin-policies.e2e.test.ts   # Mỗi chính sách builtin với subprocess thực
-    custom-hooks.e2e.test.ts       # Tải và đánh giá custom hook
-    config-scopes.e2e.test.ts      # Gộp config trên project/local/global
-    policy-params.e2e.test.ts      # Tiêm tham số cho mỗi chính sách tham số hóa
-```
-
-### Sử dụng trình hỗ trợ E2E
-
-**`FixtureEnv`** - môi trường biệt lập cho mỗi kiểm thử:
-
-```typescript
-import { createFixtureEnv } from "../helpers/fixture-env";
-
-const env = createFixtureEnv();
-// env.cwd    - thư mục tạm; truyền làm payload.cwd để lấy .failproofai/policies-config.json
-// env.home   - thư mục home biệt lập; không rò rỉ ~/.failproofai thực tế
-
-env.writeConfig({
-  enabledPolicies: ["block-sudo"],
-  policyParams: {
-    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
-  },
-});
-```
-
-`createFixtureEnv()` đăng ký dọn dẹp `afterEach` tự động.
-
-**`runHook`** - gọi 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`** - nhà máy payload có sẵn:
-
-```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)
-```
-
-### Viết kiểm thử 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 trống
-  });
-});
-```
-
-### Hình dạng phản hồi E2E
-
-| Quyết định | Mã thoát | stdout |
-|----------|-----------|--------|
-| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
-| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
-| Instruct (không-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
-| Instruct Stop | `2` | stdout trống; lý do trong stderr |
-| Allow | `0` | chuỗi trống |
-
-### Cấu hình Vitest
-
-Các kiểm thử E2E sử dụng `vitest.config.e2e.mts` với:
-
-- `environment: "node"` - không cần globals trình duyệt
-- `pool: "forks"` - cô lập process thực (kiểm thử sinh subprocess)
-- `testTimeout: 20_000` - 20s cho mỗi kiểm thử (khởi động binary + đánh giá hook)
-
-Pool `forks` rất quan trọng: worker dựa trên luồng chia sẻ `globalThis`, điều này có thể gây ảnh hưởng đến các kiểm thử sinh subprocess. Các forks dựa trên process tránh điều này.
-
----
-
-## CI
-
-Chạy CI đầy đủ (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) được yêu cầu phải vượt qua trước khi merge. Bộ kiểm thử E2E chạy như một công việc CI riêng biệt song song.
-
-Xem [Contributing](../CONTRIBUTING.md) để biết danh sách kiểm tra trước merge hoàn chỉnh.

package/.next/standalone/docs/zh/architecture.mdx

@@ -1,332 +0,0 @@
----
-title: 架构
-description: "Hook 处理器、配置加载和策略评估的内部工作原理"
-icon: sitemap
----
-
-本文档介绍 failproofai 的内部工作机制：Hook 系统如何拦截 Agent 工具调用、配置如何加载和合并、策略如何评估，以及 Dashboard 如何监控 Agent 活动。
-
----
-
-## 概览
-
-failproofai 包含两个独立的子系统：
-
-1. **Hook 处理器** - 一个快速的 CLI 子进程，Claude Code 在每次 Agent 工具调用时都会调用它。负责评估策略并返回决策结果。
-2. **Agent 监控（Dashboard）** - 一个用于监控 Agent 会话和管理策略的 Next.js Web 应用。
-
-两个子系统共享 `~/.failproofai/` 和项目 `.failproofai/` 目录中的配置文件，但它们作为独立进程运行，仅通过文件系统进行通信。
-
----
-
-## Hook 处理器
-
-### 与 Claude Code 的集成
-
-运行 `failproofai policies --install` 后，它会在 `~/.claude/settings.json` 中写入如下配置：
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "failproofai --hook PreToolUse"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [ ... ]
-  }
-}
-```
-
-随后，Claude Code 会在每次工具调用前将 `failproofai --hook PreToolUse` 作为子进程调用，并通过 stdin 传入一个 JSON 数据包。
-
-### 数据包格式
-
-```json
-{
-  "session_id": "abc123",
-  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
-  "cwd": "/home/user/myproject",
-  "permission_mode": "default",
-  "hook_event_name": "PreToolUse",
-  "tool_name": "Bash",
-  "tool_input": { "command": "sudo apt install nodejs" }
-}
-```
-
-对于 `PostToolUse` 事件，数据包还包含 `tool_result` 字段，其中包含工具的输出结果。
-
-处理器对 stdin 限制为 1 MB。超过此限制的数据包将被丢弃，所有策略默认隐式允许。
-
-### 响应格式
-
-**拒绝（PreToolUse）：**
-```json
-{
-  "hookSpecificOutput": {
-    "permissionDecision": "deny",
-    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
-  }
-}
-```
-
-**拒绝（PostToolUse）：**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Blocked by failproofai because: API key detected in output"
-  }
-}
-```
-
-**指令（除 Stop 以外的任何事件）：**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
-  }
-}
-```
-
-**Stop 事件指令：**
-- 退出码：`2`
-- 原因写入 stderr（而非 stdout）
-
-**允许：**
-- 退出码：`0`
-- stdout 为空
-
-**带消息的允许：**
-
-`allow(message)` 允许策略在操作被允许时向 Claude 发送信息性上下文。Hook 处理器将以下 JSON 写入 **stdout**（而非配置文件——这是处理器对 Claude Code 的响应，与 deny 和 instruct 响应一样）：
-
-```json
-// Written to stdout by the hook handler process
-{
-  "hookSpecificOutput": {
-    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
-  }
-}
-```
-- 退出码：`0`（操作被允许）
-- 当多个策略返回带消息的 `allow` 时，这些消息会以换行符合并为单个 `additionalContext` 字符串
-- 若没有策略提供消息，则 stdout 为空（与之前相同）
-
-### 处理流水线
-
-`src/hooks/handler.ts` 实现了完整的处理流水线：
-
-```text
-stdin JSON
-  → 解析数据包（最大 1 MB）
-  → 提取会话元数据（session_id、cwd、tool_name、tool_input 等）
-  → readMergedHooksConfig(cwd)    ← 合并项目 + 本地 + 全局配置
-  → 注册已启用的内置策略及其解析后的参数
-  → 从 customPoliciesPath 加载自定义策略（如已设置）
-  → 将自定义策略注册到策略注册表
-  → 评估所有策略（先内置策略，后自定义策略）
-      → 第一个 deny 会短路后续评估
-      → instruct 决策会累积
-      → allow 消息会累积
-  → 将 JSON 决策写入 stdout
-  → 将事件持久化到 ~/.failproofai/hook-activity.jsonl
-  → 退出
-```
-
-整个过程在典型数据包下运行耗时不超过 100ms，且不涉及任何 LLM 调用。
-
----
-
-## 配置加载
-
-`src/hooks/hooks-config.ts` 实现了三层作用域的配置加载。
-
-```text
-[1] {cwd}/.failproofai/policies-config.json        ← 项目级（最高优先级）
-[2] {cwd}/.failproofai/policies-config.local.json  ← 本地级
-[3] ~/.failproofai/policies-config.json             ← 全局级（最低优先级）
-```
-
-合并逻辑：
-- `enabledPolicies` - 对三个文件进行去重并集
-- `policyParams` - 按策略键，第一个定义该键的文件完全优先
-- `customPoliciesPath` - 第一个定义它的文件优先
-- `llm` - 第一个定义它的文件优先
-
-Web Dashboard 使用 `readHooksConfig()`（仅全局）进行读写，因为它不带项目 cwd 调用。
-
----
-
-## 策略评估
-
-`src/hooks/policy-evaluator.ts` 按顺序运行策略。
-
-对于每条策略：
-
-1. 查找策略的 `params` 模式（如有）。
-2. 从合并后的配置中读取 `policyParams[policy.name]`。
-3. 将用户提供的值覆盖到模式默认值之上，生成 `ctx.params`。
-4. 以解析后的上下文调用 `policy.fn(ctx)`。
-5. 若结果为 `deny`，立即停止并返回该决策。
-6. 若结果为 `instruct`，累积消息并继续。
-7. 若结果为 `allow`，继续执行下一条策略。
-
-所有策略运行完毕后：
-- 若有任意 `deny` 返回，发出拒绝响应。
-- 若收集到任意 `instruct` 返回，发出单条指令响应，将所有消息合并。
-- 否则，发出允许响应（stdout 为空，退出码 0）。
-
----
-
-## 内置策略
-
-`src/hooks/builtin-policies.ts` 将所有 26 个内置策略定义为 `BuiltinPolicyDefinition` 对象：
-
-```typescript
-interface BuiltinPolicyDefinition {
-  name: string;
-  description: string;
-  fn: (ctx: PolicyContext) => PolicyResult;
-  match: {
-    events: HookEventType[];
-    tools?: string[];
-  };
-  defaultEnabled: boolean;
-  category: string;
-  beta?: boolean;
-  params?: PolicyParamsSchema;
-}
-```
-
-接受 `params` 的策略会声明一个 `PolicyParamsSchema`，为每个参数指定类型和默认值。策略评估器在调用 `fn` 之前将解析后的值注入 `ctx.params`。策略函数读取 `ctx.params` 时无需进行空值检查，因为默认值始终已被应用。
-
-策略内部的模式匹配使用已解析的命令 token（argv），而非原始字符串匹配。这可防止通过 Shell 运算符注入进行绕过（例如，针对 `sudo systemctl status *` 的模式无法通过在命令后追加 `; rm -rf /` 来绕过）。
-
----
-
-## 自定义策略
-
-`src/hooks/custom-hooks-registry.ts` 实现了基于 `globalThis` 的注册表：
-
-```typescript
-const REGISTRY_KEY = "__failproofai_custom_hooks__";
-
-export const customPolicies = {
-  add(hook: CustomHook): void { ... }
-};
-
-export function getCustomHooks(): CustomHook[] { ... }
-export function clearCustomHooks(): void { ... }  // used in tests
-```
-
-`src/hooks/custom-hooks-loader.ts` 负责加载用户的策略文件：
-
-1. 从配置中读取 `customPoliciesPath`；若不存在则跳过。
-2. 解析为绝对路径；检查文件是否存在。
-3. 将所有 `from "failproofai"` 的导入重写为实际的 dist 路径，确保 `customPolicies` 解析到同一个 `globalThis` 注册表。
-4. 递归重写传递性本地导入，以确保 ESM 兼容性。
-5. 写入临时 `.mjs` 文件并 `import()` 入口文件。
-6. 调用 `getCustomHooks()` 获取已注册的 Hook。
-7. 在 `finally` 块中清理所有临时文件。
-
-发生任何错误时（文件不存在、语法错误、导入失败），错误将记录到 `~/.failproofai/hook.log`，加载器返回空数组。内置策略不受影响。
-
-自定义策略在所有内置策略之后评估。自定义策略的 `deny` 仍会短路后续自定义策略的执行（但此时所有内置策略均已运行完毕）。
-
----
-
-## 活动日志
-
-每次 Hook 事件后，处理器会向 `~/.failproofai/hook-activity.jsonl` 追加一行 JSONL 记录：
-
-```json
-{
-  "timestamp": "2026-04-06T12:34:56.789Z",
-  "sessionId": "abc123",
-  "eventType": "PreToolUse",
-  "toolName": "Bash",
-  "policyName": "block-sudo",
-  "decision": "deny",
-  "reason": "sudo command blocked by failproofai",
-  "durationMs": 12
-}
-```
-
-每条非允许决策对应一行记录。允许决策不会被记录（以保持文件精简）。
-
----
-
-## Dashboard 架构
-
-Dashboard 是一个 **Next.js 16** 应用，使用 App Router，结合 React Server Components 和 Server Actions。
-
-```text
-app/
-  layout.tsx                  ← 根布局（主题、遥测、导航）
-  projects/page.tsx           ← 服务端组件：列出所有 Claude 项目
-  project/[name]/page.tsx     ← 服务端组件：列出项目中的会话
-  project/[name]/session/
-    [sessionId]/page.tsx      ← 服务端组件：渲染会话查看器
-  policies/page.tsx           ← 客户端组件：策略管理 + 活动日志
-  actions/
-    get-hooks-config.ts       ← 读取配置 + 策略列表
-    update-hooks-config.ts    ← 开启/关闭策略
-    update-policy-params.ts   ← 更新策略参数
-    get-hook-activity.ts      ← 分页/搜索活动日志
-    install-hooks-web.ts      ← 通过浏览器安装/移除 Hook
-  api/
-    download/[project]/[session]/route.ts   ← 将会话导出为 ZIP/JSONL
-```
-
-**数据流：**
-
-- 页面组件调用 `lib/projects.ts` 和 `lib/log-entries.ts` 直接从文件系统读取项目/会话数据（读取操作无需 API 层）。
-- 策略页面的所有变更操作（切换、参数更新、安装/移除）均使用 Server Actions。
-- 会话查看器解析 Claude 的 JSONL 转录格式，并渲染消息和工具调用的时间线。
-
-**关键设计决策：**
-
-- 无数据库——所有持久化状态均存储在纯文本文件中（`~/.failproofai/`、`~/.claude/projects/`）。
-- 变更操作使用 Server Actions——CRUD 操作无需 REST API。
-- 读取页面使用 React Server Components——更快的首次加载，数据获取无需客户端 bundle。
-- 仅在需要交互的地方使用客户端组件（策略切换、活动搜索、日志查看器）。
-
----
-
-## 文件布局
-
-```text
-failproofai/
-├── bin/
-│   └── failproofai.mjs           # CLI 路由器（hook / dashboard / install 等）
-├── src/hooks/
-│   ├── handler.ts                # Hook 事件流水线
-│   ├── builtin-policies.ts       # 26 个策略定义
-│   ├── policy-evaluator.ts       # 策略执行引擎
-│   ├── policy-registry.ts        # 策略注册与查找
-│   ├── policy-types.ts           # TypeScript 接口
-│   ├── hooks-config.ts           # 多作用域配置加载
-│   ├── custom-hooks-registry.ts  # 基于 globalThis 的 Hook 注册表
-│   ├── custom-hooks-loader.ts    # 用户 JS Hook 的 ESM 加载器
-│   ├── manager.ts                # 安装 / 移除 / 列出操作
-│   ├── install-prompt.ts         # 交互式策略选择提示
-│   ├── hook-logger.ts            # 记录日志到 hook.log
-│   ├── hook-activity-store.ts    # 将活动持久化到 hook-activity.jsonl
-│   └── llm-client.ts             # LLM API 客户端（用于 AI 驱动的策略）
-├── app/                          # Next.js Dashboard（页面 + Server Actions）
-├── lib/                          # 共享工具库
-│   ├── projects.ts               # 从文件系统枚举 Claude 项目
-│   ├── log-entries.ts            # 解析 Claude 转录 JSONL 格式
-│   ├── paths.ts                  # 解析系统路径
-│   └── ...
-├── components/                   # 共享 React UI 组件
-├── contexts/                     # React Context 提供者（主题、自动刷新、遥测）
-├── examples/                     # 自定义 Hook 示例文件
-└── __tests__/                    # 单元测试和 E2E 测试
-```