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

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

@@ -1,57 +0,0 @@
----
-title: Failproof AI
-description: "管理钩子与策略，让你的 AI 智能体保持可靠并自主运行"
----
-
-[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
-
-为 **Claude Code** 和 **Agents SDK** 提供钩子与策略，让你的 AI 智能体保持可靠并自主运行。
-
-AI 智能体的失败方式往往是可预测的：执行破坏性命令、泄露密钥、偏离任务、陷入循环，或直接推送到主分支。一旦无人看管，小问题就会接连爆发。
-
-Failproof AI 通过**策略**来解决这些问题——这些规则会钩入每一次智能体工具调用，能够**检测故障**、**缓解故障**（拦截、指令纠正、脱敏处理），并在需要关注时**提醒你**。本地仪表板让你事后随时查看所有详情。
-
-一切均在本地运行，数据不会离开你的机器。
-
-## 开始使用
-
-<CardGroup cols={2}>
-
-<Card title="26 条内置策略" icon="shield" href="/zh/built-in-policies">
-  开箱即用：拦截破坏性命令、防止密钥泄露、将智能体限制在项目边界内，以及更多功能。
-</Card>
-
-<Card title="自定义策略" icon="code" href="/zh/custom-policies">
-  使用简洁的 allow / deny / instruct API，用 JavaScript 编写你自己的规则。
-</Card>
-
-<Card title="智能体监控" icon="chart-line" href="/zh/dashboard">
-  查看智能体在你离开期间做了什么。浏览会话、检查工具调用、查看策略触发记录。
-</Card>
-
-<Card title="轻松配置" icon="gear" href="/zh/configuration">
-  无需编写代码即可调整任意策略。按项目或全局设置白名单、受保护分支或阈值。
-</Card>
-
-</CardGroup>
-
-## 快速上手
-
-<CodeGroup>
-
-```bash npm
-npm install -g failproofai
-```
-
-```bash bun
-bun add -g failproofai
-```
-
-</CodeGroup>
-
-```bash
-failproofai policies --install   # enable policies
-failproofai                      # launch the dashboard
-```
-
-完整的操作流程请参阅[入门指南](/zh/getting-started)。

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

@@ -1,82 +0,0 @@
----
-title: 包别名
-description: "已注册的防拼写错误别名及其工作原理"
-icon: copy
----
-
-## 官方包
-
-npm 的正式包名为 **`failproofai`**：
-
-```bash
-npm install -g failproofai
-# or
-bun add -g failproofai
-```
-
----
-
-## 为什么我们持有这些别名
-
-供应链攻击中，拼写抢注（typosquatting）是一种常见手段——恶意攻击者注册一个与热门包名仅有一个按键之差的包名，不知情的用户在安装时一旦输错，便会运行攻击者控制的代码，并获得完整的系统访问权限。这正是 Failproof AI 所要防范的威胁。
-
-为消除这一攻击面，**我们在 npm 上抢先注册了 `failproofai` 的所有常见拼写错误和格式变体**。这些包名均无法被第三方注册。每个别名都是一个轻量代理，安装后会自动委托给真正的 `failproofai` 包。
-
----
-
-## 已注册的别名
-
-**格式变体** —— "failproof ai" 的不同写法：
-
-| 包名 | 状态 |
-|---------|--------|
-| `failproof` | ✅ 已发布 |
-| `failproof-ai` | ⏳ 等待 npm 审核 |
-| `fail-proof-ai` | ⏳ 等待 npm 审核 |
-| `failproof_ai` | ⏳ 等待 npm 审核 |
-| `fail_proof_ai` | ⏳ 等待 npm 审核 |
-| `fail-proofai` | ⏳ 等待 npm 审核 |
-
-**`failprof*` 拼写错误** —— "proof" 中缺少一个 `o`：
-
-| 包名 | 状态 |
-|---------|--------|
-| `failprof` | ✅ 已发布 |
-| `failprof-ai` | ✅ 已发布 |
-| `failprofai` | ⏳ 等待 npm 审核 |
-| `fail-prof-ai` | ⏳ 等待 npm 审核 |
-| `failprof_ai` | ⏳ 等待 npm 审核 |
-
-**`faliproof*` 拼写错误** —— `a` 和 `i` 互换位置：
-
-| 包名 | 状态 |
-|---------|--------|
-| `faliproof` | ✅ 已发布 |
-| `faliproof-ai` | ✅ 已发布 |
-| `faliproofai` | ⏳ 等待 npm 审核 |
-
-> **为什么显示"等待审核"？** npm 的防滥用政策会拦截那些在去除标点符号并经过相似度检测后与已有包名规范化为同一字符串的新包名。我们已联系 npm 支持团队，申请以防抢注为由保留这些名称，获批后将正式激活。
-
-您可以通过以下命令验证任意已发布的别名均归我们所有：
-
-```bash
-npm info failproof
-# Look for: "ExosphereHost Inc." in the maintainers field
-```
-
----
-
-## 别名的工作原理
-
-每个别名包的工作方式如下：
-
-1. 将 `failproofai` 列为依赖项——安装时会运行真正的包（包括其 `postinstall` 钩子配置）
-2. 暴露一个与自身同名的可执行文件（例如 `failprof-ai`），将所有参数代理转发给 `failproofai` 二进制文件
-
-代理逻辑仅为两行 Node 脚本，没有任何业务逻辑、网络请求，也不会收集 `failproofai` 本身行为之外的任何数据。
-
----
-
-## 如果您发现我们遗漏的包名
-
-请在 [exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues) 提交 issue，我们会及时注册。

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

@@ -1,260 +0,0 @@
----
-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/eslint.config.mjs

@@ -1,15 +0,0 @@
-import nextConfig from "eslint-config-next/core-web-vitals";
-import tsParser from "@typescript-eslint/parser";
-
-const config = [
-  { ignores: ["dist/"] },
-  ...nextConfig,
-  { settings: { react: { version: "19" } } },
-  {
-    files: ["**/*.{js,jsx,mjs,mts,cts}"],
-    languageOptions: { parser: tsParser },
-  },
-];
-
-export default config;
-

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

@@ -1,40 +0,0 @@
-/**
- * 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

@@ -1,41 +0,0 @@
-/**
- * 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/examples/policies-advanced/index.js

@@ -1,103 +0,0 @@
-/**
- * policies-advanced/index.js — advanced custom policies example
- *
- * Demonstrates:
- *   - Transitive local imports (./utils.js is auto-rewritten by the loader)
- *   - Async hooks (await inside fn)
- *   - Using ctx.session (cwd, sessionId)
- *   - PostToolUse event (inspect tool output)
- *   - Stop event (verify before Claude finishes)
- *
- * Install:
- *   failproofai --install-hooks custom ./examples/policies-advanced/index.js
- *
- * See also: ../policies-notification.js for a Notification event example.
- */
-import { customPolicies, allow, deny, instruct } from "failproofai";
-import { isOutsideProject, extractPushBranch, looksLikeSecretFile } from "./utils.js";
-
-// 1. Block writes to secret-looking file paths (uses transitive import)
-customPolicies.add({
-  name: "block-secret-file-writes",
-  description: "Block writing to files that look like private keys or credentials",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Write") return allow();
-    const path = String(ctx.toolInput?.file_path ?? "");
-    if (looksLikeSecretFile(path)) {
-      return deny(`Writing to ${path} is blocked — looks like a secret or credential file`);
-    }
-    return allow();
-  },
-});
-
-// 2. Block pushing to version-tagged branches (e.g. v1.2.3) — must go through release process
-customPolicies.add({
-  name: "block-push-to-version-tags",
-  description: "Block git push directly to version branches (v*.*.*)",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = String(ctx.toolInput?.command ?? "");
-    if (!/git\s+push\b/.test(cmd)) return allow();
-    const branch = extractPushBranch(cmd);
-    if (branch && /^v\d+\.\d+/.test(branch)) {
-      return deny(`Pushing directly to version branch "${branch}" is not allowed — use the release workflow`);
-    }
-    return allow();
-  },
-});
-
-// 3. Warn if a Bash command touches paths outside the session cwd (uses ctx.session)
-customPolicies.add({
-  name: "warn-outside-cwd",
-  description: "Warn before Bash commands that reference absolute paths outside the session cwd",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = String(ctx.toolInput?.command ?? "");
-    const cwd = ctx.session?.cwd;
-    if (cwd && isOutsideProject(cmd, cwd)) {
-      return instruct(
-        `The command references a path outside the project root (${cwd}). ` +
-        "Confirm this is intentional before proceeding."
-      );
-    }
-    return allow();
-  },
-});
-
-// 4. PostToolUse: strip any line from Bash output that looks like a raw API key
-customPolicies.add({
-  name: "scrub-api-key-output",
-  description: "Redact lines containing raw API keys from Bash tool output",
-  match: { events: ["PostToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const output = String(ctx.payload?.tool_result ?? "");
-    // Simple heuristic: long alphanumeric tokens prefixed by known key prefixes
-    const keyPattern = /(?:sk-|ghp_|AIza|AKIA)[A-Za-z0-9_\-]{20,}/;
-    if (keyPattern.test(output)) {
-      return deny("Bash output contains what looks like a raw API key — output suppressed");
-    }
-    return allow();
-  },
-});
-
-// 5. Stop event: remind Claude to summarise what it changed before finishing
-customPolicies.add({
-  name: "require-change-summary",
-  description: "Ask Claude to include a change summary before stopping",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    const transcript = String(ctx.payload?.transcript ?? "");
-    // Only trigger if there were file-modifying tool calls in the session
-    const hadWrites = /\"tool_name\"\s*:\s*\"(Write|Edit|Bash)\"/.test(transcript);
-    if (hadWrites && !transcript.includes("## Summary")) {
-      return instruct(
-        "Before finishing, provide a brief '## Summary' of files you created or modified."
-      );
-    }
-    return allow();
-  },
-});

package/.next/standalone/examples/policies-advanced/utils.js

@@ -1,35 +0,0 @@
-/**
- * Shared utilities for hooks-advanced/index.js
- * This file is a transitive import — the loader rewrites it automatically.
- */
-
-/** Return true if the command touches a path outside the project root. */
-export function isOutsideProject(cmd, cwd) {
-  if (!cwd) return false;
-  // Very rough check: absolute paths that don't start with cwd
-  const absPathRe = /(?:^|\s)(\/[^\s]+)/g;
-  let match;
-  while ((match = absPathRe.exec(cmd)) !== null) {
-    if (!match[1].startsWith(cwd)) return true;
-  }
-  return false;
-}
-
-/** Extract the first git branch name from a push command, e.g. "git push origin feat/foo" → "feat/foo" */
-export function extractPushBranch(cmd) {
-  const m = cmd.match(/git\s+push\s+\S+\s+(\S+)/);
-  return m ? m[1] : null;
-}
-
-/** Return the list of staged secret file patterns to check. */
-export const SECRET_FILENAME_PATTERNS = [
-  /\.pem$/i,
-  /\.key$/i,
-  /id_rsa/i,
-  /credentials\.json$/i,
-  /\.p12$/i,
-];
-
-export function looksLikeSecretFile(path) {
-  return SECRET_FILENAME_PATTERNS.some((re) => re.test(path));
-}