failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,260 @@
+---
+title: 测试
+description: "单元测试、端到端测试与测试辅助工具"
+icon: flask-vial
+---
+
+failproofai 包含两套测试套件：**单元测试**（快速、使用 mock）和**端到端测试**（真实子进程调用）。
+
+---
+
+## 运行测试
+
+```bash
+# 单次运行所有单元测试
+bun run test:run
+
+# 以监视模式运行单元测试
+bun run test
+
+# 运行端到端测试（需要配置环境，详见下文）
+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());
+  });
+});
+```
+
+---
+
+## 端到端测试
+
+端到端测试将真实的 `failproofai` 二进制文件作为子进程调用，通过 stdin 传入 JSON payload，并对 stdout 输出和退出码进行断言。这能够测试 Claude Code 所使用的完整集成路径。
+
+### 环境配置
+
+端到端测试直接从仓库源码运行二进制文件。在首次运行前，需要构建自定义 hook 文件从 `'failproofai'` 导入时所使用的 CJS 包：
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+然后运行测试：
+
+```bash
+bun run test:e2e
+```
+
+每当修改公共 hook API（`src/hooks/custom-hooks-registry.ts`、`src/hooks/policy-helpers.ts` 或 `src/hooks/policy-types.ts`）后，请重新构建 `dist/`。
+
+### 端到端测试结构
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # 启动二进制进程，传入 payload JSON，捕获退出码 + stdout + stderr
+    fixture-env.ts      # 为每个测试创建包含配置文件的隔离临时目录
+    payloads.ts         # 符合 Claude 格式的各事件类型 payload 工厂函数
+  hooks/
+    builtin-policies.e2e.test.ts   # 每个内置策略的真实子进程测试
+    custom-hooks.e2e.test.ts       # 自定义 hook 的加载与评估
+    config-scopes.e2e.test.ts      # 跨项目/本地/全局的配置合并
+    policy-params.e2e.test.ts      # 各参数化策略的参数注入
+```
+
+### 使用端到端测试辅助工具
+
+**`FixtureEnv`** - 每个测试的隔离环境：
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - 临时目录；作为 payload.cwd 传入以加载 .failproofai/policies-config.json
+// env.home   - 隔离的 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`** - 现成的 payload 工厂函数：
+
+```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)
+```
+
+### 编写端到端测试
+
+```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
+  });
+});
+```
+
+### 端到端响应格式
+
+| 决策 | 退出码 | 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 配置
+
+端到端测试使用 `vitest.config.e2e.mts`，配置如下：
+
+- `environment: "node"` - 无需浏览器全局变量
+- `pool: "forks"` - 真正的进程隔离（测试会派生子进程）
+- `testTimeout: 20_000` - 每个测试 20 秒超时（含二进制启动和 hook 评估时间）
+
+使用 `forks` 池至关重要：基于线程的 worker 共享 `globalThis`，可能干扰需要派生子进程的测试。基于进程的 forks 模式可避免此问题。
+
+---
+
+## 持续集成
+
+在合并前，必须通过完整的 CI 运行（`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`）。端到端测试套件作为独立的 CI 任务并行运行。
+
+完整的合并前检查清单请参阅 [Contributing](../CONTRIBUTING.md)。

package/.next/standalone/examples/convention-policies/security-policies.mjs

@@ -0,0 +1,40 @@
+/**
+ * security-policies.mjs — Convention-based security policies
+ *
+ * Drop this file into .failproofai/policies/ at the project or user level
+ * and it will be automatically loaded — no --custom flag needed.
+ *
+ * Project level:  .failproofai/policies/security-policies.mjs
+ * User level:     ~/.failproofai/policies/security-policies.mjs
+ */
+import { customPolicies, allow, deny } from "failproofai";
+
+// Block writes to .env files
+customPolicies.add({
+  name: "block-env-writes",
+  description: "Prevent Claude from writing to .env files",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = String(ctx.toolInput?.file_path ?? "");
+    if (/\.env($|\.)/.test(path)) {
+      return deny(`Writing to .env files is blocked: ${path}`);
+    }
+    return allow();
+  },
+});
+
+// Block commands that delete git history
+customPolicies.add({
+  name: "block-git-history-rewrite",
+  description: "Prevent destructive git history operations",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+(rebase\s+-i|filter-branch|reflog\s+expire)/.test(cmd)) {
+      return deny("Rewriting git history is not allowed — use a revert commit instead");
+    }
+    return allow();
+  },
+});

package/.next/standalone/examples/convention-policies/workflow-policies.mjs

@@ -0,0 +1,41 @@
+/**
+ * workflow-policies.mjs — Convention-based workflow policies
+ *
+ * Drop this file into .failproofai/policies/ at the project or user level
+ * and it will be automatically loaded — no --custom flag needed.
+ *
+ * Project level:  .failproofai/policies/workflow-policies.mjs
+ * User level:     ~/.failproofai/policies/workflow-policies.mjs
+ */
+import { customPolicies, allow, instruct } from "failproofai";
+
+// Remind to run tests before committing
+customPolicies.add({
+  name: "test-before-commit",
+  description: "Remind Claude to run tests before git commit",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+commit/.test(cmd)) {
+      return instruct(
+        "Before committing, make sure all tests pass. " +
+        "Run the test suite first if you haven't already."
+      );
+    }
+    return allow();
+  },
+});
+
+// Log all file writes for audit trail
+customPolicies.add({
+  name: "audit-file-writes",
+  description: "Log all file write operations",
+  match: { events: ["PostToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "unknown";
+    console.error(`[audit] File written: ${path}`);
+    return allow();
+  },
+});

package/.next/standalone/next.config.ts

@@ -1,4 +1,8 @@
 import type { NextConfig } from "next";
+import { readFileSync } from "fs";
+import { join } from "path";
+
+const pkg = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf-8"));
 
 const allowedDevOrigins = process.env.FAILPROOFAI_ALLOWED_DEV_ORIGINS
   ? process.env.FAILPROOFAI_ALLOWED_DEV_ORIGINS.split(",").map((s) => s.trim()).filter(Boolean)
@@ -19,9 +23,7 @@ const nextConfig: NextConfig = {
     return config;
   },
   env: {
-    // Expose CLAUDE_PROJECTS_PATH to the client-side if needed
-    // Note: Only use this if you need it on the client side
-    // For server-side only, you can access it via process.env.CLAUDE_PROJECTS_PATH
+    NEXT_PUBLIC_APP_VERSION: pkg.version,
   },
 };
 

package/.next/standalone/node_modules/@next/env/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next/env",
-  "version": "16.2.2",
+  "version": "16.2.3",
   "keywords": [
     "react",
     "next",

package/.next/standalone/node_modules/next/dist/build/swc/index.js

@@ -134,7 +134,7 @@ var HmrTarget = /*#__PURE__*/ function(HmrTarget) {
     HmrTarget["Server"] = "server";
     return HmrTarget;
 }({});
-const nextVersion = "16.2.2";
+const nextVersion = "16.2.3";
 const ArchName = (0, _os.arch)();
 const PlatformName = (0, _os.platform)();
 function infoLog(...args) {