failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/vi/custom-policies.mdx

@@ -0,0 +1,357 @@
+---
+title: Chính sách Tùy chỉnh
+description: "Viết các quy tắc riêng của bạn bằng JavaScript - thực thi các quy ước, ngăn chặn sự trôi dạt, phát hiện các lỗi, tích hợp với các hệ thống bên ngoài"
+icon: code
+---
+
+Chính sách tùy chỉnh cho phép bạn viết các quy tắc cho bất kỳ hành động của agent nào: thực thi các quy ước dự án, ngăn chặn sự trôi dạt, chặn các hoạt động có tính hủy diệt, phát hiện các agent bị kẹt, hoặc tích hợp với Slack, quy trình phê duyệt, v.v. Chúng sử dụng cùng một hệ thống sự kiện hook và các quyết định `allow`, `deny`, `instruct` như các chính sách tích hợp.
+
+---
+
+## Ví dụ nhanh
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+Cài đặt nó:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Hai cách để tải chính sách tùy chỉnh
+
+### Lựa chọn 1: Dựa trên quy ước (được khuyến nghị, v0.0.2-beta.7+)
+
+Thả các tệp `*policies.{js,mjs,ts}` vào `.failproofai/policies/` và chúng sẽ được tải tự động — không cần cờ hoặc thay đổi cấu hình. Cách này hoạt động giống như git hooks: thả một tệp, nó sẽ hoạt động.
+
+```
+# Mức dự án — được cam kết với git, chia sẻ với đội
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Mức người dùng — cá nhân, áp dụng cho tất cả các dự án
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Cách hoạt động:**
+- Cả hai thư mục dự án và người dùng được quét (union — không phải first-scope-wins)
+- Các tệp được tải theo thứ tự bảng chữ cái trong mỗi thư mục. Thêm tiền tố `01-`, `02-` để kiểm soát thứ tự
+- Chỉ các tệp khớp với `*policies.{js,mjs,ts}` được tải; các tệp khác bị bỏ qua
+- Mỗi tệp được tải độc lập (fail-open cho mỗi tệp)
+- Hoạt động cùng với các chính sách `--custom` rõ ràng và tích hợp
+
+<Tip>
+Chính sách quy ước là cách dễ nhất để chia sẻ chính sách trên toàn đội. Cam kết `.failproofai/policies/` với git và mỗi thành viên đội sẽ tự động nhận được chúng.
+</Tip>
+
+### Lựa chọn 2: Đường dẫn tệp rõ ràng
+
+```bash
+# Cài đặt với tệp chính sách tùy chỉnh
+failproofai policies --install --custom ./my-policies.js
+
+# Thay thế đường dẫn tệp chính sách
+failproofai policies --install --custom ./new-policies.js
+
+# Xóa đường dẫn chính sách tùy chỉnh khỏi cấu hình
+failproofai policies --uninstall --custom
+```
+
+Đường dẫn tuyệt đối được phân giải được lưu trữ trong `policies-config.json` dưới dạng `customPoliciesPath`. Tệp được tải lại trên mỗi sự kiện hook - không có bộ nhớ cache giữa các sự kiện.
+
+### Sử dụng cả hai cùng nhau
+
+Chính sách quy ước và tệp `--custom` rõ ràng có thể cùng tồn tại. Thứ tự tải:
+
+1. Tệp `customPoliciesPath` rõ ràng (nếu được cấu hình)
+2. Tệp quy ước dự án (`{cwd}/.failproofai/policies/`, theo thứ tự bảng chữ cái)
+3. Tệp quy ước người dùng (`~/.failproofai/policies/`, theo thứ tự bảng chữ cái)
+
+---
+
+## API
+
+### Nhập
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Đăng ký một chính sách. Gọi hàm này bao nhiêu lần cần thiết cho nhiều chính sách trong cùng một tệp.
+
+```ts
+customPolicies.add({
+  name: string;                         // required - unique identifier
+  description?: string;                 // shown in `failproofai policies` output
+  match?: { events?: HookEventType[] }; // filter by event type; omit to match all
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Trợ giúp quyết định
+
+| Hàm | Tác động | Sử dụng khi |
+|-----|---------|-----------|
+| `allow()` | Cho phép hoạt động im lặng | Hành động an toàn, không cần tin nhắn |
+| `deny(message)` | Chặn hoạt động | Agent không nên thực hiện hành động này |
+| `instruct(message)` | Thêm bối cảnh mà không chặn | Cung cấp cho agent bối cảnh bổ sung để tiếp tục theo đúng hướng |
+
+`deny(message)` - thông báo sẽ xuất hiện cho Claude với tiền tố `"Blocked by failproofai:"`. Một `deny` duy nhất sẽ ngắt khoá tất cả các đánh giá tiếp theo.
+
+`instruct(message)` - thông báo được nối thêm vào bối cảnh của Claude cho lệnh gọi công cụ hiện tại. Tất cả các thông báo `instruct` được tích lũy và gửi cùng nhau.
+
+<Tip>
+Bạn có thể nối thêm hướng dẫn bổ sung vào bất kỳ thông báo `deny` hoặc `instruct` nào bằng cách thêm trường `hint` trong `policyParams` — không cần thay đổi mã. Điều này hoạt động cho các chính sách tùy chỉnh (`custom/`), quy ước dự án (`.failproofai-project/`), và quy ước người dùng (`.failproofai-user/`) cũng vậy. Xem [Cấu hình → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết.
+</Tip>
+
+### Thông báo allow thông tin (beta)
+
+<Note>
+`allow(message)` là tính năng beta có sẵn từ v0.0.2-beta.3. API có thể thay đổi trong các phiên bản tương lai. Các phiên bản trước chỉ hỗ trợ `allow()` mà không có đối số.
+</Note>
+
+`allow(message)` cho phép hoạt động **và** gửi một thông báo thông tin quay lại cho Claude. Thông báo được gửi dưới dạng `additionalContext` trong phản hồi stdout của trình xử lý hook — cơ chế tương tự được sử dụng bởi `instruct`, nhưng về mặt ngữ nghĩa khác: đó là một cập nhật trạng thái, không phải cảnh báo.
+
+| Hàm | Tác động | Sử dụng khi |
+|-----|---------|-----------|
+| `allow(message)` | Cho phép và gửi bối cảnh cho Claude | Xác nhận kiểm tra đã vượt qua, hoặc giải thích tại sao một kiểm tra bị bỏ qua |
+
+Các trường hợp sử dụng:
+- **Xác nhận trạng thái:** `allow("All CI checks passed.")` — cho Claude biết mọi thứ đang ổn
+- **Giải thích fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — cho Claude biết tại sao một kiểm tra bị bỏ qua để nó có đầy đủ bối cảnh
+- **Nhiều thông báo tích lũy:** nếu nhiều chính sách mỗi cái trả về `allow(message)`, tất cả các thông báo được nối lại bằng dòng mới và gửi cùng nhau
+
+```js
+customPolicies.add({
+  name: "confirm-branch-status",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const cwd = ctx.session?.cwd;
+    if (!cwd) return allow("No working directory, skipping branch check.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### Các trường `PolicyContext`
+
+| Trường | Loại | Mô tả |
+|--------|------|-------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | Công cụ được gọi (ví dụ: `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Các tham số đầu vào của công cụ |
+| `payload` | `Record<string, unknown>` | Toàn bộ tải trọng sự kiện thô từ Claude Code |
+| `session` | `SessionMetadata \| undefined` | Bối cảnh phiên (xem bên dưới) |
+
+### Các trường `SessionMetadata`
+
+| Trường | Loại | Mô tả |
+|--------|------|-------|
+| `sessionId` | `string` | Mã định danh phiên Claude Code |
+| `cwd` | `string` | Thư mục làm việc của phiên Claude Code |
+| `transcriptPath` | `string` | Đường dẫn đến tệp transcript JSONL của phiên |
+
+### Các loại sự kiện
+
+| Sự kiện | Khi nó kích hoạt | Nội dung `toolInput` |
+|--------|-----------------|-----------------|
+| `PreToolUse` | Trước khi Claude chạy một công cụ | Đầu vào của công cụ (ví dụ: `{ command: "..." }` cho Bash) |
+| `PostToolUse` | Sau khi một công cụ hoàn thành | Đầu vào của công cụ + `tool_result` (đầu ra) |
+| `Notification` | Khi Claude gửi thông báo | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks phải luôn trả về `allow()`, chúng không thể chặn thông báo |
+| `Stop` | Khi phiên Claude kết thúc | Trống |
+
+---
+
+## Thứ tự đánh giá
+
+Chính sách được đánh giá theo thứ tự này:
+
+1. Chính sách tích hợp (theo thứ tự định nghĩa)
+2. Chính sách tùy chỉnh rõ ràng từ `customPoliciesPath` (theo thứ tự `.add()`)
+3. Chính sách quy ước từ dự án `.failproofai/policies/` (tệp theo thứ tự bảng chữ cái, `.add()` theo thứ tự trong)
+4. Chính sách quy ước từ người dùng `~/.failproofai/policies/` (tệp theo thứ tự bảng chữ cái, `.add()` theo thứ tự trong)
+
+<Note>
+`deny` đầu tiên sẽ ngắt khoá tất cả các chính sách tiếp theo. Tất cả các thông báo `instruct` được tích lũy và gửi cùng nhau.
+</Note>
+
+---
+
+## Nhập transitive
+
+Các tệp chính sách tùy chỉnh có thể nhập các mô-đun cục bộ bằng cách sử dụng đường dẫn tương đối:
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+Tất cả các nhập tương đối có thể tiếp cận từ tệp nhập được phân giải. Điều này được triển khai bằng cách viết lại các nhập `from "failproofai"` thành đường dẫn dist thực tế và tạo các tệp `.mjs` tạm thời để đảm bảo tương thích ESM.
+
+---
+
+## Lọc loại sự kiện
+
+Sử dụng `match.events` để giới hạn khi một chính sách kích hoạt:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Only fires when the session ends
+    // ctx.session.transcriptPath contains the full session log
+    return allow();
+  },
+});
+```
+
+Bỏ qua `match` hoàn toàn để kích hoạt trên mọi loại sự kiện.
+
+---
+
+## Xử lý lỗi và chế độ lỗi
+
+Chính sách tùy chỉnh là **fail-open**: các lỗi không bao giờ chặn chính sách tích hợp hoặc làm hỏng trình xử lý hook.
+
+| Lỗi | Hành vi |
+|-----|--------|
+| `customPoliciesPath` không được đặt | Không có chính sách tùy chỉnh rõ ràng chạy; chính sách quy ước và tích hợp tiếp tục bình thường |
+| Tệp không tìm thấy | Cảnh báo được ghi vào `~/.failproofai/hook.log`; tích hợp tiếp tục |
+| Lỗi cú pháp/nhập (rõ ràng) | Lỗi được ghi vào `~/.failproofai/hook.log`; chính sách tùy chỉnh rõ ràng bị bỏ qua |
+| Lỗi cú pháp/nhập (quy ước) | Lỗi được ghi; tệp đó bị bỏ qua, các tệp quy ước khác vẫn tải |
+| `fn` ném tại thời gian chạy | Lỗi được ghi; hook đó được coi là `allow`; các hook khác tiếp tục |
+| `fn` mất lâu hơn 10 giây | Timeout được ghi; được coi là `allow` |
+| Thư mục quy ước bị thiếu | Không có chính sách quy ước chạy; không có lỗi |
+
+<Tip>
+Để gỡ lỗi các lỗi chính sách tùy chỉnh, hãy theo dõi tệp nhật ký:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Ví dụ đầy đủ: nhiều chính sách
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Prevent agent from writing to secrets/ directory
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Prevent agent from writing to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// Keep the agent on track: verify tests before committing
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Keep the agent on track: verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// Prevent unplanned dependency changes during freeze
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Prevent unplanned dependency changes during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## Ví dụ
+
+Thư mục `examples/` chứa các tệp chính sách sẵn sàng để chạy:
+
+| Tệp | Nội dung |
+|-----|---------|
+| `examples/policies-basic.js` | Năm chính sách khởi động bao gồm các chế độ lỗi agent phổ biến |
+| `examples/policies-advanced/index.js` | Mô hình nâng cao: nhập transitive, gọi không đồng bộ, làm sạch đầu ra, và hook kết thúc phiên |
+| `examples/convention-policies/security-policies.mjs` | Chính sách bảo mật dựa trên quy ước (chặn ghi .env, ngăn chặn viết lại lịch sử git) |
+| `examples/convention-policies/workflow-policies.mjs` | Chính sách quy trình làm việc dựa trên quy ước (nhắc nhở kiểm tra, tệp ghi kiểm toán) |
+
+### Sử dụng các ví dụ tệp rõ ràng
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Sử dụng các ví dụ dựa trên quy ước
+
+```bash
+# Copy to project level
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Or copy to user level
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Không cần lệnh cài đặt — các tệp sẽ được chọn tự động khi sự kiện hook tiếp theo.

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

@@ -0,0 +1,142 @@
+---
+title: Dashboard
+description: "Giám sát các phiên làm việc của agent, xem xét các lệnh gọi công cụ và quản lý chính sách"
+icon: chart-line
+---
+
+Dashboard failproofai là một ứng dụng web cục bộ để giám sát các phiên làm việc của agent AI và quản lý chính sách. Xem những gì các agent của bạn đã làm khi bạn vắng mặt.
+
+---
+
+## Khởi động dashboard
+
+```bash
+failproofai
+```
+
+Mở tại `http://localhost:8020`.
+
+Dashboard đọc trực tiếp từ hệ thống tập tin - các thư mục dự án Claude Code của bạn và các tệp cấu hình failproofai. Không có dữ liệu nào được ghi vào dịch vụ từ xa.
+
+---
+
+## Các trang
+
+### Projects
+
+Liệt kê tất cả các dự án Claude Code được tìm thấy trên máy của bạn. Các dự án được phát hiện từ `~/.claude/projects/` (hoặc đường dẫn được đặt bởi `CLAUDE_PROJECTS_PATH`).
+
+Mỗi dự án hiển thị:
+- Tên dự án (được lấy từ đường dẫn thư mục)
+- Số lượng phiên làm việc
+- Ngày hoạt động phiên làm việc gần nhất
+
+Nhấp vào một dự án để xem các phiên làm việc của nó.
+
+### Sessions
+
+Liệt kê tất cả các phiên làm việc trong một dự án. Mỗi phiên làm việc hiển thị:
+- ID phiên làm việc
+- Dấu thời gian bắt đầu và kết thúc
+- Số lượng lệnh gọi công cụ
+- Số lượng hoạt động hook (các chính sách đã được kích hoạt)
+
+Sử dụng bộ lọc phạm vi ngày và tìm kiếm ID phiên làm việc để thu hẹp danh sách. Các phiên làm việc được chia thành các trang.
+
+Nhấp vào một phiên làm việc để mở trình xem phiên làm việc.
+
+### Session viewer
+
+Trình xem phiên làm việc trả lời câu hỏi chính cho các agent tự động hóa: agent đã làm gì và có ở đúng hướng không? Nó hiển thị một dòng thời gian của mọi thứ đã xảy ra trong một phiên làm việc:
+
+- **Messages** - Các phản hồi văn bản của Claude và các lời nhắc từ người dùng
+- **Tool calls** - Mọi công cụ mà Claude đã gọi, kèm theo đầu vào và đầu ra của nó
+- **Policy activity** - Đối với mỗi lệnh gọi công cụ, các chính sách nào đã được kích hoạt và quyết định nào mà chúng trả về
+
+Thanh thống kê ở phía trên cùng hiển thị thời lượng phiên làm việc, tổng số lệnh gọi công cụ và tóm tắt quyết định hook (số lượng allow / deny / instruct).
+
+Bạn có thể xuất phiên làm việc dưới dạng tệp ZIP hoặc JSONL bằng nút tải xuống.
+
+### Policies
+
+Một trang có hai tab để quản lý chính sách và xem xét hoạt động.
+
+<Tabs>
+  <Tab title="Policies tab">
+  - Bật hoặc tắt các chính sách riêng lẻ bằng một cú nhấp chuột (ghi vào `~/.failproofai/policies-config.json`)
+  - Mở rộng một chính sách để cấu hình các tham số của nó (đối với các chính sách hỗ trợ `policyParams`)
+  - Cài đặt hoặc xóa hook cho một phạm vi nhất định
+  - Đặt đường dẫn tệp chính sách tùy chỉnh
+  </Tab>
+  <Tab title="Activity tab">
+  - Lịch sử đầy đủ được chia trang của mọi sự kiện hook đã được kích hoạt trên tất cả các phiên làm việc
+  - Tìm kiếm theo tên chính sách, ID phiên làm việc, tên công cụ hoặc quyết định
+  - Mỗi hàng hiển thị: dấu thời gian, tên chính sách, quyết định, tên công cụ, ID phiên làm việc và lý do cho các quyết định deny/instruct
+  </Tab>
+</Tabs>
+
+---
+
+## Tự động làm mới
+
+Dashboard có một công tắc tự động làm mới trong thanh điều hướng trên cùng. Khi được bật, trang hiện tại được làm mới định kỳ để hiển thị các phiên làm việc và hoạt động chính sách mới khi chúng xuất hiện. Thiết yếu để giám sát các phiên làm việc của agent tự động hóa chạy lâu dài.
+
+---
+
+## Vô hiệu hóa các trang
+
+Nếu bạn chỉ cần một số phần của dashboard, hãy đặt `FAILPROOFAI_DISABLE_PAGES` thành một danh sách tên trang được phân tách bằng dấu phẩy:
+
+```bash
+FAILPROOFAI_DISABLE_PAGES=policies failproofai
+```
+
+Các giá trị hợp lệ: `policies`, `projects`.
+
+---
+
+## Chủ đề
+
+Dashboard hỗ trợ chế độ sáng và chế độ tối. Chuyển đổi qua nút trong thanh điều hướng. Tùy chọn được lưu trữ trong bộ nhớ cục bộ của trình duyệt của bạn.
+
+---
+
+## Cấu hình đường dẫn dự án
+
+Theo mặc định, dashboard đọc từ thư mục dự án Claude Code tiêu chuẩn. Ghi đè nó cho các thiết lập tùy chỉnh:
+
+```bash
+CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
+```
+
+---
+
+## Truy cập từ máy chủ không phải localhost
+
+Khi chạy dashboard ở **chế độ phát triển** (`npm run dev`) và truy cập nó từ tên máy chủ khác ngoài `localhost` - ví dụ như một miền tùy chỉnh, IP từ xa hoặc URL được đường hầm - bạn có thể thấy cảnh báo như:
+
+```text
+⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
+```
+
+Đây là Next.js chặn quyền truy cập cross-origin vào websocket HMR (hot module reload) của nó, đây là một tính năng chỉ cho phát triển. Để cho phép máy chủ của bạn, hãy sử dụng cờ `--allowed-origins`:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com
+```
+
+Để có nhiều máy chủ hoặc IP, hãy chuyển một danh sách được phân tách bằng dấu phẩy:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
+```
+
+Bạn cũng có thể đặt biến môi trường `FAILPROOFAI_ALLOWED_DEV_ORIGINS`:
+
+```bash
+FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
+```
+
+<Note>
+Điều này chỉ áp dụng cho chế độ phát triển. Khi chạy `failproofai` (chế độ production), không có websocket HMR và không có vấn đề tài nguyên phát triển cross-origin.
+</Note>