failproofai 0.0.2-beta.7 → 0.0.2-beta.9

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

@@ -0,0 +1,253 @@
+---
+title: Ví dụ
+description: "Cách thiết lập hooks cho Claude Code và Agents SDK"
+icon: book-open
+---
+
+Các ví dụ sẵn sàng sử dụng cho các tình huống phổ biến. Mỗi ví dụ cho thấy cách cài đặt và những gì bạn có thể mong đợi.
+
+---
+
+## Thiết lập hooks cho Claude Code
+
+Failproof AI tích hợp với Claude Code thông qua [hệ thống hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) của nó. Khi bạn chạy `failproofai policies --install`, nó sẽ đăng ký các lệnh hook trong `settings.json` của Claude Code để kích hoạt trên mỗi lệnh gọi công cụ.
+
+<Steps>
+  <Step title="Cài đặt failproofai">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="Bật tất cả các chính sách tích hợp">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="Xác minh rằng hooks đã được đăng ký">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    Bạn sẽ thấy các mục hook cho các sự kiện `PreToolUse`, `PostToolUse`, `Notification` và `Stop`.
+  </Step>
+  <Step title="Chạy Claude Code">
+    ```bash
+    claude
+    ```
+
+    Các chính sách giờ đây chạy tự động trên mỗi lệnh gọi công cụ. Hãy thử yêu cầu Claude chạy `sudo rm -rf /` - nó sẽ bị chặn.
+  </Step>
+</Steps>
+
+---
+
+## Thiết lập hooks cho Agents SDK
+
+Nếu bạn đang xây dựng bằng [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), bạn có thể sử dụng hệ thống hook tương tự theo cách lập trình.
+
+<Steps>
+  <Step title="Cài đặt failproofai trong dự án của bạn">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="Cấu hình hooks trong agent của bạn">
+    Truyền các lệnh hook khi tạo quy trình agent của bạn. Các hooks kích hoạt giống như trong Claude Code - thông qua JSON stdin/stdout:
+
+    ```bash
+    failproofai --hook PreToolUse   # được gọi trước mỗi công cụ
+    failproofai --hook PostToolUse  # được gọi sau mỗi công cụ
+    ```
+  </Step>
+  <Step title="Viết một chính sách tùy chỉnh cho agent của bạn">
+    ```javascript
+    import { customPolicies, allow, deny } from "failproofai";
+
+    customPolicies.add({
+      name: "limit-to-project-dir",
+      description: "Giữ agent trong thư mục dự án",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        const path = String(ctx.toolInput?.file_path ?? "");
+        if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
+          return deny("Agent bị hạn chế trong thư mục dự án");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="Cài đặt chính sách tùy chỉnh">
+    ```bash
+    failproofai policies --install --custom ./my-agent-policies.js
+    ```
+  </Step>
+</Steps>
+
+---
+
+## Chặn các lệnh có tính chất phá hủy
+
+Cấu hình phổ biến nhất - ngăn chặn agents thực hiện các thiệt hại không thể đảo ngược.
+
+```bash
+failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
+```
+
+Điều này làm gì:
+- `block-sudo` - chặn tất cả các lệnh `sudo`
+- `block-rm-rf` - chặn xóa tệp đệ quy
+- `block-force-push` - chặn `git push --force`
+- `block-curl-pipe-sh` - chặn ống dẫn các tập lệnh từ xa đến shell
+
+---
+
+## Ngăn chặn rò rỉ bí mật
+
+Dừng agents nhìn thấy hoặc rò rỉ thông tin xác thực trong kết quả đầu ra công cụ.
+
+```bash
+failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
+```
+
+Những cái này kích hoạt trên `PostToolUse` - sau khi một công cụ chạy, chúng sẽ làm sạch kết quả đầu ra trước khi agent nhìn thấy.
+
+---
+
+## Nhận cảnh báo Slack khi agents cần chú ý
+
+Sử dụng hook thông báo để chuyển tiếp cảnh báo nhàn rỗi đến Slack.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "slack-on-idle",
+  description: "Cảnh báo Slack khi agent đang chờ đầu vào",
+  match: { events: ["Notification"] },
+  fn: async (ctx) => {
+    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
+    if (!webhookUrl) return allow();
+
+    const message = String(ctx.payload?.message ?? "Agent đang chờ");
+    const project = ctx.session?.cwd ?? "không xác định";
+
+    try {
+      await fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          text: `*${message}*\nProject: \`${project}\``,
+        }),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch {
+      // không bao giờ chặn agent nếu Slack không thể truy cập
+    }
+
+    return allow();
+  },
+});
+```
+
+Cài đặt nó:
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
+```
+
+---
+
+## Giữ agents trên một nhánh
+
+Ngăn chặn agents từ việc chuyển đổi nhánh hoặc đẩy đến các nhánh được bảo vệ.
+
+```javascript
+import { customPolicies, allow, deny } from "failproofai";
+
+customPolicies.add({
+  name: "stay-on-branch",
+  description: "Ngăn chặn agent kiểm tra các nhánh khác",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
+      return deny("Giữ trên nhánh hiện tại. Tạo một nhánh mới bằng -b nếu cần.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## Yêu cầu kiểm tra trước khi commit
+
+Nhắc nhở agents chạy các kiểm tra trước khi commit.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "test-before-commit",
+  description: "Nhắc nhở agent chạy các kiểm tra trước khi 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("Chạy các kiểm tra trước khi commit. Sử dụng `npm test` hoặc `bun test` trước tiên.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## Khóa kho lưu trữ sản xuất
+
+Commit một cấu hình ở cấp độ dự án để mỗi nhà phát triển trong đội của bạn nhận được các chính sách tương tự.
+
+Tạo `.failproofai/policies-config.json` trong kho lưu trữ của bạn:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-force-push",
+    "block-push-master",
+    "block-env-files",
+    "sanitize-api-keys",
+    "sanitize-jwt"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "production"]
+    }
+  }
+}
+```
+
+Sau đó commit nó:
+
+```bash
+git add .failproofai/policies-config.json
+git commit -m "Add failproofai team policies"
+```
+
+Mỗi thành viên trong đội có failproofai được cài đặt sẽ tự động áp dụng các quy tắc này.
+
+---
+
+## Thêm ví dụ
+
+Thư mục [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) trong kho lưu trữ chứa:
+
+| Tệp | Những gì nó cho thấy |
+|------|---------------|
+| `policies-basic.js` | Các chính sách khởi động - chặn ghi sản xuất, force-push, tập lệnh ống dẫn |
+| `policies-notification.js` | Cảnh báo Slack cho thông báo nhàn rỗi và kết thúc phiên |
+| `policies-advanced/index.js` | Nhập cũng từ các tệp khác, hooks không đồng bộ, làm sạch kết quả đầu ra PostToolUse, xử lý sự kiện Stop |

package/.next/standalone/docs/vi/for-agents.mdx

@@ -0,0 +1,38 @@
+---
+title: "Cho các agent"
+description: "Thêm kiến thức Failproof AI vào coding agent của bạn chỉ trong một lệnh. Hoạt động với Claude Code, Cursor, Windsurf và nhiều hơn nữa."
+---
+
+Thêm tham chiếu đầy đủ Failproof AI vào coding agent của bạn chỉ trong một lệnh. Hoạt động với Claude Code, Cursor, Windsurf và bất kỳ agent nào khác hỗ trợ skills.
+
+```bash
+npx skills add https://docs.befailproof.ai
+```
+
+`npx skills` phát hiện các agent bạn đã cài đặt và tự động thêm skill ở định dạng phù hợp cho từng agent.
+
+## Skill bao gồm những gì
+
+| Lĩnh vực | Nội dung bao gồm |
+|------|----------------|
+| Policies | Tên policy có sẵn, các loại sự kiện, tham số, bật/tắt |
+| Custom policies | `customPolicies.add()`, match filters, API `allow`/`deny`/`instruct` |
+| Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` |
+| Configuration | Cấu trúc `policies-config.json`, scope merging, `policyParams` |
+| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scopes |
+| Dashboard | Session viewer, policy activity, environment variables |
+| Architecture | Hook handler flow, exit codes, stdin/stdout contract |
+
+## Skill có đầy đủ không?
+
+Mintlify tạo `llms.txt` từ tất cả các trang trong navigation. Tài liệu Failproof AI bao gồm toàn bộ API - mọi policy, option và ví dụ đều có. Nếu bạn phát hiện điều gì bị thiếu, nguồn gốc nằm ở `https://docs.befailproof.ai/llms-full.txt`.
+
+Để có ngữ cảnh cụ thể, liên kết trực tiếp đến một trang cụ thể:
+
+```bash
+# Chỉ custom policies API
+npx skills add https://docs.befailproof.ai/custom-policies
+
+# Chỉ built-in policies
+npx skills add https://docs.befailproof.ai/built-in-policies
+```

package/.next/standalone/docs/vi/getting-started.mdx

@@ -0,0 +1,134 @@
+---
+title: Bắt đầu
+description: "Cài đặt failproofai, bật các chính sách và cho phép các agent của bạn chạy một cách đáng tin cậy"
+icon: rocket
+---
+
+## Yêu cầu
+
+- **Node.js** >= 20.9.0
+- **Bun** >= 1.3.0 (tùy chọn - chỉ cần thiết khi xây dựng từ nguồn)
+
+---
+
+## Cài đặt
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+---
+
+## Bắt đầu nhanh
+
+<Steps>
+  <Step title="Bật các chính sách">
+    Các chính sách là những quy tắc chạy trước và sau mỗi lời gọi công cụ của agent. Chúng bắt các lệnh có tính phá hủy, rò rỉ thông tin bí mật và các kiểu lỗi khác trước khi gây hại.
+
+    ```bash
+    failproofai policies --install
+    ```
+
+    Điều này ghi các mục hook vào `settings.json` của Claude Code. Bạn cũng có thể cài đặt cho một dự án duy nhất hoặc chọn các chính sách cụ thể:
+
+    ```bash
+    failproofai policies --install --scope project
+    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
+    ```
+  </Step>
+  <Step title="Xác minh">
+    ```bash
+    failproofai policies
+    ```
+
+    Hiển thị mọi chính sách, liệu nó có được bật hay không và bất kỳ tham số nào được cấu hình.
+  </Step>
+  <Step title="Khởi chạy bảng điều khiển">
+    ```bash
+    failproofai
+    ```
+
+    Mở bảng điều khiển cục bộ tại `http://localhost:8020` nơi bạn có thể duyệt phiên, kiểm tra các lời gọi công cụ và quản lý các chính sách.
+  </Step>
+  <Step title="Chạy agent của bạn">
+    Khởi động Claude Code như bình thường. Nếu agent cố gắng làm điều gì đó rủi ro, failproofai sẽ chặn nó tự động. Hãy để nó chạy không giám sát và xem xét những gì đã xảy ra trong bảng điều khiển.
+  </Step>
+</Steps>
+
+---
+
+## Cách các chính sách hoạt động
+
+Mỗi khi một agent chạy một công cụ, Claude Code gọi failproofai như một tiến trình con:
+
+```text
+Claude Code  →  failproofai --hook PreToolUse  →  đọc JSON từ stdin
+                                                 đánh giá các chính sách
+                                                 ghi quyết định vào stdout
+```
+
+Mỗi chính sách trả về một trong ba quyết định:
+
+- **allow** - agent tiếp tục bình thường
+- **deny** - hành động bị chặn, agent được thông báo lý do
+- **instruct** - bối cảnh bổ sung được thêm vào lời nhắc của agent
+
+<Note>
+Các chính sách chạy trong quy trình cục bộ của bạn. Không có gì được gửi đến một dịch vụ từ xa.
+</Note>
+
+---
+
+## Lưu trữ dữ liệu
+
+Tất cả cấu hình và nhật ký nằm trên máy của bạn:
+
+| Đường dẫn | Những gì nó lưu trữ |
+|------|----------------|
+| `~/.failproofai/policies-config.json` | Cấu hình chính sách toàn cục |
+| `~/.failproofai/hook-activity.jsonl` | Lịch sử thực thi hook |
+| `~/.failproofai/hook.log` | Nhật ký gỡ lỗi cho các lỗi hook tùy chỉnh |
+| `.failproofai/policies-config.json` | Cấu hình cho từng dự án (được cam kết) |
+| `.failproofai/policies-config.local.json` | Ghi đè cá nhân (gitignored) |
+
+---
+
+## Gỡ cài đặt
+
+```bash
+failproofai policies --uninstall
+```
+
+Xóa các mục hook khỏi `~/.claude/settings.json`. Các tệp cấu hình trong `~/.failproofai/` được giữ lại.
+
+---
+
+## Các bước tiếp theo
+
+<CardGroup cols={2}>
+
+<Card title="Cấu hình" icon="gear" href="/vi/configuration">
+  Phạm vi và định dạng tệp cấu hình
+</Card>
+
+<Card title="Chính sách tích hợp" icon="shield" href="/vi/built-in-policies">
+  Tất cả 26 chính sách với tham số
+</Card>
+
+<Card title="Chính sách tùy chỉnh" icon="code" href="/vi/custom-policies">
+  Viết các chính sách của riêng bạn bằng JavaScript
+</Card>
+
+<Card title="Trình giám sát agent" icon="chart-line" href="/vi/dashboard">
+  Giám sát phiên và xem xét hoạt động của chính sách
+</Card>
+
+</CardGroup>

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

@@ -0,0 +1,57 @@
+---
+title:  Failproof AI
+description: "Quản lý hooks và policies giúp các AI agents của bạn hoạt động tin cậy và tự động"
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+Hooks và policies giúp các AI agents của bạn hoạt động tin cậy và tự động - cho **Claude Code** và **Agents SDK**.
+
+AI agents thất bại theo những cách có thể dự đoán được. Chúng chạy các lệnh phá hủy, rò rỉ bí mật, lệch khỏi nhiệm vụ, bị mắc kẹt trong vòng lặp, hoặc đẩy trực tiếp sang nhánh main. Nếu không được giám sát, những lỗi nhỏ sẽ phát triển thành vấn đề lớn.
+
+Failproof AI giải quyết vấn đề này bằng **policies** - các quy tắc được kích hoạt ở mỗi lệnh gọi công cụ của agent và có thể **phát hiện lỗi**, **giảm nhẹ chúng** (chặn, hướng dẫn, làm sạch), và **cảnh báo bạn** khi có vấn đề cần được chú ý. Bảng điều khiển cục bộ cho phép bạn xem xét mọi thứ sau đó.
+
+Mọi thứ chạy cục bộ. Không có dữ liệu nào rời khỏi máy của bạn.
+
+## Bắt đầu
+
+<CardGroup cols={2}>
+
+<Card title="26 policies tích hợp sẵn" icon="shield" href="/vi/built-in-policies">
+  Chặn các lệnh phá hủy, ngăn chặn rò rỉ bí mật, giữ agents trong phạm vi dự án, và nhiều hơn nữa - sẵn sàng sử dụng.
+</Card>
+
+<Card title="Custom policies" icon="code" href="/vi/custom-policies">
+  Viết các quy tắc của riêng bạn bằng JavaScript với API allow / deny / instruct đơn giản.
+</Card>
+
+<Card title="Agent monitor" icon="chart-line" href="/vi/dashboard">
+  Xem những gì các agents của bạn đã làm khi bạn vắng mặt. Duyệt các phiên, kiểm tra các lệnh gọi công cụ, xem xét nơi policies được kích hoạt.
+</Card>
+
+<Card title="Cấu hình dễ dàng" icon="gear" href="/vi/configuration">
+  Điều chỉnh bất kỳ policy nào mà không cần mã. Đặt danh sách cho phép, nhánh được bảo vệ, hoặc ngưỡng cho từng dự án hoặc toàn cục.
+</Card>
+
+</CardGroup>
+
+## Khởi động nhanh
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # enable policies
+failproofai                      # launch the dashboard
+```
+
+Xem hướng dẫn [Getting started](/vi/getting-started) để có hướng dẫn chi tiết đầy đủ.

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

@@ -0,0 +1,82 @@
+---
+title: Bí Danh Gói
+description: "Các bí danh phòng chống typosquat đã đăng ký và cách chúng hoạt động"
+icon: copy
+---
+
+## Gói chính thức
+
+Gói npm canonical là **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# hoặc
+bun add -g failproofai
+```
+
+---
+
+## Tại sao chúng tôi sở hữu các tên bí danh
+
+Typosquatting là một cuộc tấn công chuỗi cung ứng phổ biến trong đó kẻ tấn công đăng ký một tên gói cách một phím bàn phím so với gói phổ biến. Những người dùng vô tình gõ sai lệnh cài đặt sẽ chạy mã do kẻ tấn công kiểm soát với toàn quyền truy cập hệ thống - chính xác là loại mối đe dọa mà Failproof AI được thiết kế để bảo vệ.
+
+Để loại bỏ bề mặt tấn công này, **chúng tôi chủ động sở hữu tất cả các lỗi chính tả và biến thể định dạng phổ biến** của `failproofai` trên npm. Không có tên nào trong số này có thể được đăng ký bởi bên thứ ba. Mỗi tên là một proxy mỏng cài đặt và ủy quyền cho gói `failproofai` thực tế.
+
+---
+
+## Các bí danh đã đăng ký
+
+**Biến thể định dạng** - những cách khác nhau để viết "failproof ai":
+
+| Gói | Trạng thái |
+|---------|--------|
+| `failproof` | ✅ Đã xuất bản |
+| `failproof-ai` | ⏳ Chờ hỗ trợ npm |
+| `fail-proof-ai` | ⏳ Chờ hỗ trợ npm |
+| `failproof_ai` | ⏳ Chờ hỗ trợ npm |
+| `fail_proof_ai` | ⏳ Chờ hỗ trợ npm |
+| `fail-proofai` | ⏳ Chờ hỗ trợ npm |
+
+**Lỗi typo `failprof*`** - thiếu một `o` từ "proof":
+
+| Gói | Trạng thái |
+|---------|--------|
+| `failprof` | ✅ Đã xuất bản |
+| `failprof-ai` | ✅ Đã xuất bản |
+| `failprofai` | ⏳ Chờ hỗ trợ npm |
+| `fail-prof-ai` | ⏳ Chờ hỗ trợ npm |
+| `failprof_ai` | ⏳ Chờ hỗ trợ npm |
+
+**Lỗi typo `faliproof*`** - `a` và `i` bị hoán đổi:
+
+| Gói | Trạng thái |
+|---------|--------|
+| `faliproof` | ✅ Đã xuất bản |
+| `faliproof-ai` | ✅ Đã xuất bản |
+| `faliproofai` | ⏳ Chờ hỗ trợ npm |
+
+> **Tại sao chờ?** Chính sách phòng chống spam của npm chặn những tên normalize thành chuỗi giống như một gói hiện có sau khi loại bỏ dấu chấm câu và chạy kiểm tra tương tự. Chúng tôi đã liên hệ với hỗ trợ npm để bảo lưu những tên này nhằm mục đích chống typosquat. Chúng sẽ được kích hoạt sau khi được phê duyệt.
+
+Bạn có thể xác minh bất kỳ bí danh nào được xuất bản được sở hữu bởi chúng tôi:
+
+```bash
+npm info failproof
+# Tìm: "ExosphereHost Inc." trong trường maintainers
+```
+
+---
+
+## Cách các bí danh hoạt động
+
+Mỗi gói bí danh:
+
+1. Liệt kê `failproofai` làm phụ thuộc - vì vậy gói thực tế (bao gồm cả thiết lập hook `postinstall`) chạy khi cài đặt
+2. Cung cấp một binary khớp với tên của nó (ví dụ: `failprof-ai`) mà ủy quyền tất cả các đối số cho binary `failproofai`
+
+Proxy là một script Node hai dòng; không có logic, không có cuộc gọi mạng và không có thu thập dữ liệu ngoài những gì `failproofai` tự làm.
+
+---
+
+## Nếu bạn tìm thấy một tên chúng tôi bỏ lỡ
+
+Mở một issue tại [exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues) và chúng tôi sẽ đăng ký nó.