failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,260 @@
+---
+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

@@ -0,0 +1,332 @@
+---
+title: 架构
+description: "钩子处理器、配置加载和策略评估的内部工作原理"
+icon: sitemap
+---
+
+本文档介绍 failproofai 的内部工作机制：钩子系统如何拦截 Agent 工具调用、配置如何加载与合并、策略如何评估，以及仪表板如何监控 Agent 活动。
+
+---
+
+## 概述
+
+failproofai 包含两个独立的子系统：
+
+1. **钩子处理器** - 一个高速 CLI 子进程，Claude Code 在每次 Agent 工具调用时调用它。负责评估策略并返回决策结果。
+2. **Agent 监控器（仪表板）** - 一个 Next.js Web 应用，用于监控 Agent 会话和管理策略。
+
+两个子系统共享 `~/.failproofai/` 目录和项目 `.failproofai/` 目录中的配置文件，但它们作为独立进程运行，仅通过文件系统进行通信。
+
+---
+
+## 钩子处理器
+
+### 与 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 为空
+
+**允许并携带消息（测试版）：**
+
+自 v0.0.2-beta.3 起，`allow(message)` 允许策略在操作被允许时仍向 Claude 发送信息性上下文。钩子处理器将以下 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 仪表板不是通过项目 cwd 调用的，它使用 `readHooksConfig()`（仅全局）进行读写。
+
+---
+
+## 策略评估
+
+`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()` 获取已注册的钩子。
+7. 在 `finally` 块中清理所有临时文件。
+
+遇到任何错误（文件未找到、语法错误、导入失败）时，错误信息会被记录到 `~/.failproofai/hook.log`，加载器返回空数组。内置策略不受影响。
+
+自定义策略在所有内置策略之后评估。自定义策略的 `deny` 仍会短路后续自定义策略（但此时所有内置策略已执行完毕）。
+
+---
+
+## 活动日志
+
+每次钩子事件处理后，处理器会向 `~/.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
+}
+```
+
+每条记录对应一条做出非允许决策的策略。允许决策不记录日志（以保持文件精简）。
+
+---
+
+## 仪表板架构
+
+仪表板是一个 **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      ← 从浏览器安装/移除钩子
+  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——加快首次加载速度，数据获取无需客户端包。
+- 仅在需要交互的地方使用客户端组件（策略切换、活动搜索、日志查看器）。
+
+---
+
+## 文件结构
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # CLI 路由器（hook / dashboard / install 等）
+├── src/hooks/
+│   ├── handler.ts                # 钩子事件流水线
+│   ├── builtin-policies.ts       # 26 条策略定义
+│   ├── policy-evaluator.ts       # 策略执行引擎
+│   ├── policy-registry.ts        # 策略注册与查找
+│   ├── policy-types.ts           # TypeScript 接口
+│   ├── hooks-config.ts           # 多级范围配置加载
+│   ├── custom-hooks-registry.ts  # 基于 globalThis 的钩子注册表
+│   ├── custom-hooks-loader.ts    # 用户 JS 钩子的 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 仪表板（页面 + 服务端 Actions）
+├── lib/                          # 共享工具库
+│   ├── projects.ts               # 从文件系统枚举 Claude 项目
+│   ├── log-entries.ts            # 解析 Claude 转录 JSONL 格式
+│   ├── paths.ts                  # 解析系统路径
+│   └── ...
+├── components/                   # 共享 React UI 组件
+├── contexts/                     # React Context 提供者（主题、自动刷新、遥测）
+├── examples/                     # 自定义钩子文件示例
+└── __tests__/                    # 单元测试与 E2E 测试
+```