failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,357 @@
+---
+title: מדיניויות מותאמות
+description: "כתוב את הכללים שלך ב-JavaScript - אכוף קונבנציות, עצור drift, גלה כשלים, התחבר למערכות חיצוניות"
+icon: code
+---
+
+מדיניויות מותאמות מאפשרות לך לכתוב כללים לכל התנהגות agent: אכוף קונבנציות פרויקט, עצור drift, שער פעולות הורסות, גלה agents תקועות, או התחבר ל-Slack, תהליכי אישור, ועוד. הם משתמשים באותה מערכת hook event ובהחלטות `allow`, `deny`, `instruct` כמו מדיניויות מובנות.
+
+---
+
+## דוגמה מהירה
+
+```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();
+  },
+});
+```
+
+התקן אותה:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## שתי דרכים לטעון מדיניויות מותאמות
+
+### אפשרות 1: מבוססת קונבנציה (מומלצת, v0.0.2-beta.7+)
+
+שים קבצים `*policies.{js,mjs,ts}` בתיקייה `.failproofai/policies/` והם יוטענו באופן אוטומטי — ללא דגלים או שינויי קונפיגורציה. זה עובד כמו git hooks: שים קובץ, זה פשוט עובד.
+
+```
+# Project level — committed to git, shared with the team
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# User level — personal, applies to all projects
+~/.failproofai/policies/my-policies.mjs
+```
+
+**איך זה עובד:**
+- שתי התיקיות של פרויקט ומשתמש סורקות (union — לא first-scope-wins)
+- קבצים נטענים בסדר אלפביתי בתוך כל תיקייה. קידומת עם `01-`, `02-` לשליטה בסדר
+- רק קבצים התואמים `*policies.{js,mjs,ts}` נטענים; קבצים אחרים מתעלמים
+- כל קובץ טוען באופן עצמאי (fail-open לכל קובץ)
+- עובד לצד מדיניויות `--custom` מפורשות ומובנות
+
+<Tip>
+מדיניויות קונבנציה הן הדרך הקלה ביותר לשתף מדיניויות על פני הצוות. התחייב `.failproofai/policies/` ל-git וכל חבר בצוות יקבל אותם באופן אוטומטי.
+</Tip>
+
+### אפשרות 2: נתיב קובץ מפורש
+
+```bash
+# Install with a custom policies file
+failproofai policies --install --custom ./my-policies.js
+
+# Replace the policies file path
+failproofai policies --install --custom ./new-policies.js
+
+# Remove the custom policies path from config
+failproofai policies --uninstall --custom
+```
+
+הנתיב המוחלט שנפתר מאוחסן ב-`policies-config.json` בתור `customPoliciesPath`. הקובץ נטען מחדש בכל hook event - אין cache בין events.
+
+### שימוש בשניהם ביחד
+
+מדיניויות קונבנציה והקובץ `--custom` המפורש יכולים להתקיים. סדר הטעינה:
+
+1. קובץ `customPoliciesPath` מפורש (אם מוגדר)
+2. קבצי קונבנציה של פרויקט (`{cwd}/.failproofai/policies/`, אלפביתי)
+3. קבצי קונבנציה של משתמש (`~/.failproofai/policies/`, אלפביתי)
+
+---
+
+## API
+
+### Import
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+רושם מדיניות. קרא לפונקציה זו כמה פעמים שנדרש עבור מדיניויות מרובות באותו קובץ.
+
+```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>;
+});
+```
+
+### עוזרי החלטה
+
+| פונקציה | השפעה | השתמש כאשר |
+|----------|--------|----------|
+| `allow()` | התר את הפעולה בשקט | הפעולה בטוחה, לא נדרשת הודעה |
+| `deny(message)` | חסום את הפעולה | ל-agent אין לבצע פעולה זו |
+| `instruct(message)` | הוסף הקשר ללא חסימה | תן ל-agent הקשר נוסף להישאר בעקבות |
+
+`deny(message)` - ההודעה מופיעה ל-Claude בתחילית `"Blocked by failproofai:"`. `deny` אחד בודד מקצר את כל ההערכה הנוספת.
+
+`instruct(message)` - ההודעה מצורפת להקשר של Claude לקריאת הכלי הנוכחית. כל הודעות `instruct` מצטברות ומועברות יחד.
+
+<Tip>
+אתה יכול להצמיד הנחיות נוספות לכל הודעת `deny` או `instruct` על ידי הוספת שדה `hint` ב-`policyParams` — ללא צורך בשינוי קוד. זה עובד גם על מדיניויות custom (`custom/`), קונבנציה של פרויקט (`.failproofai-project/`), וקונבנציה של משתמש (`.failproofai-user/`). ראה [Configuration → hint](/he/configuration#hint-cross-cutting) לפרטים.
+</Tip>
+
+### הודעות allow מידע (beta)
+
+<Note>
+`allow(message)` היא תכונת beta זמינה מ-v0.0.2-beta.3. ה-API עשוי להשתנות בגרסאות עתידיות. גרסאות קודמות תומכות רק ב-`allow()` ללא טיעונים.
+</Note>
+
+`allow(message)` מתיר את הפעולה **ו**שולח הודעה מידע בחזרה ל-Claude. ההודעה מועברת כ-`additionalContext` בתגובת stdout של hook handler — אותה מנגנון שבו משתמשים `instruct`, אך שונה מבחינה סמנטית: זה עדכון סטטוס, לא אזהרה.
+
+| פונקציה | השפעה | השתמש כאשר |
+|----------|--------|----------|
+| `allow(message)` | התר ושלח הקשר ל-Claude | אשר שצ'ק עבר, או הסבר למה צ'ק דולג |
+
+מקרי שימוש:
+- **אישורי סטטוס:** `allow("All CI checks passed.")` — אומר ל-Claude שהכל ירוק
+- **הסברי fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — אומר ל-Claude למה צ'ק דולג כך שיש לו הקשר מלא
+- **הודעות מרובות מצטברות:** אם מספר מדיניויות כל אחת מחזירה `allow(message)`, כל ההודעות מחוברות עם שורות חדשות ומועברות יחד
+
+```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.");
+  },
+});
+```
+
+### שדות `PolicyContext`
+
+| שדה | סוג | תיאור |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | הכלי שנקרא (למשל `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | פרמטרי הקלט של הכלי |
+| `payload` | `Record<string, unknown>` | payload אירוע גולמי מלא מ-Claude Code |
+| `session` | `SessionMetadata \| undefined` | הקשר סשן (ראה למטה) |
+
+### שדות `SessionMetadata`
+
+| שדה | סוג | תיאור |
+|-------|------|-------------|
+| `sessionId` | `string` | מזהה סשן Claude Code |
+| `cwd` | `string` | ספריית עבודה של סשן Claude Code |
+| `transcriptPath` | `string` | נתיב לקובץ תמליל JSONL של הסשן |
+
+### סוגי אירוע
+
+| אירוע | מתי הוא משדר | תוכן `toolInput` |
+|-------|--------------|----------------------|
+| `PreToolUse` | לפני ש-Claude מריץ כלי | קלט הכלי (למשל `{ command: "..." }` עבור Bash) |
+| `PostToolUse` | לאחר סיום כלי | קלט הכלי + `tool_result` (הפלט) |
+| `Notification` | כאשר Claude שולח הודעה | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks חייבים תמיד להחזיר `allow()`, הם לא יכולים לחסום הודעות |
+| `Stop` | כאשר סשן Claude מסתיים | ריק |
+
+---
+
+## סדר הערכה
+
+מדיניויות מוערכות בסדר זה:
+
+1. מדיניויות מובנות (בסדר הגדרה)
+2. מדיניויות custom מפורשות מ-`customPoliciesPath` (בסדר `.add()`)
+3. מדיניויות קונבנציה מ-`.failproofai/policies/` של פרויקט (קבצים אלפביתיים, סדר `.add()` בתוך)
+4. מדיניויות קונבנציה מ-`~/.failproofai/policies/` של משתמש (קבצים אלפביתיים, סדר `.add()` בתוך)
+
+<Note>
+`deny` הראשון מקצר את כל המדיניויות הבאות. כל הודעות `instruct` מצטברות ומועברות יחד.
+</Note>
+
+---
+
+## ייבואים טרנזיטיביים
+
+קבצי מדיניות מותאמות יכולים לייבא מודולים מקומיים באמצעות נתיבים יחסיים:
+
+```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");
+  },
+});
+```
+
+כל הייבואים היחסיים שניתן להגיע אליהם מקובץ הכניסה מופתרים. זה מיושם על ידי כתיבה מחדש של ייבואים `from "failproofai"` לנתיב dist בפועל ויצירת קבצים זמניים `.mjs` כדי להבטיח תאימות ESM.
+
+---
+
+## סינון סוג אירוע
+
+השתמש ב-`match.events` להגבלת מתי מדיניות משדרת:
+
+```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();
+  },
+});
+```
+
+השמט `match` לחלוטין לשדר בכל סוג אירוע.
+
+---
+
+## טיפול בשגיאות ומצבי כשל
+
+מדיניויות מותאמות הן **fail-open**: שגיאות לעולם לא חוסמות מדיניויות מובנות או מקרסות hook handler.
+
+| כשל | התנהגות |
+|---------|----------|
+| `customPoliciesPath` לא מוגדר | אין מדיניויות custom מפורשות פועלות; מדיניויות קונבנציה ומובנות ממשיכות בדרך כלל |
+| קובץ לא נמצא | אזהרה מתועדת ל-`~/.failproofai/hook.log`; מובנים ממשיכים |
+| שגיאת Syntax/import (מפורשת) | שגיאה מתועדת ל-`~/.failproofai/hook.log`; מדיניויות custom מפורשות דולגות |
+| שגיאת Syntax/import (קונבנציה) | שגיאה מתועדת; קובץ זה דולג, קבצי קונבנציה אחרים עדיין נטענים |
+| `fn` זורק בזמן ריצה | שגיאה מתועדת; hook זה מטופל כ-`allow`; hooks אחרים ממשיכים |
+| `fn` לוקח יותר מ-10 שניות | timeout מתועדת; מטופל כ-`allow` |
+| ספריית קונבנציה חסרה | אין מדיניויות קונבנציה פועלות; לא שגיאה |
+
+<Tip>
+כדי לבדוק שגיאות של מדיניות מותאמת, צפה בקובץ היומן:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## דוגמה מלאה: מדיניויות מרובות
+
+```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 };
+```
+
+---
+
+## דוגמאות
+
+ספריית `examples/` מכילה קבצי מדיניות מוכנים להפעלה:
+
+| קובץ | תוכן |
+|------|----------|
+| `examples/policies-basic.js` | חמש מדיניויות קלפי סטרטר המכסות מצבי כשל נפוצים של agent |
+| `examples/policies-advanced/index.js` | דפוסים מתקדמים: ייבואים טרנזיטיביים, קריאות async, ניקוי פלט, hooks של סוף סשן |
+| `examples/convention-policies/security-policies.mjs` | מדיניויות אבטחה מבוססות קונבנציה (חסום כתיבות .env, מנע כתיבה מחדש של היסטוריית git) |
+| `examples/convention-policies/workflow-policies.mjs` | מדיניויות זרימת עבודה מבוססות קונבנציה (תזכורות בדיקה, קובץ כתיבה ביקורת) |
+
+### שימוש בדוגמאות קובץ מפורש
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### שימוש בדוגמאות מבוססות קונבנציה
+
+```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/
+```
+
+לא נדרש פקודת התקנה — הקבצים נקטפים באופן אוטומטי בהאירוע hook הבא.

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

@@ -0,0 +1,142 @@
+---
+title: לוח בקרה
+description: "ניטור סשנים של סוכנים, בדיקת קריאות כלים וניהול מדיניות"
+icon: chart-line
+---
+
+לוח הבקרה של failproofai היא אפליקציית ווב מקומית לניטור סשנים של סוכנים AI שלך וניהול מדיניות. ראה מה עשו הסוכנים שלך בזמן שלא היית.
+
+---
+
+## הפעלת לוח הבקרה
+
+```bash
+failproofai
+```
+
+נפתח ב-`http://localhost:8020`.
+
+לוח הבקרה קורא ישירות מקובץ המערכת - תיקיות פרויקטי Claude Code שלך וקבצי הקונפיגורציה של failproofai. לא נכתב כלום לשירות מרחוק.
+
+---
+
+## עמודים
+
+### Projects
+
+מוצג רשימה של כל פרויקטי Claude Code שנמצאו במכונה שלך. פרויקטים מגוקלים מ-`~/.claude/projects/` (או הנתיב שהוגדר על ידי `CLAUDE_PROJECTS_PATH`).
+
+כל פרויקט מוצג עם:
+- שם הפרויקט (נגזר מנתיב התיקייה)
+- מספר סשנים
+- תאריך של פעילות הסשן הקודם
+
+לחץ על פרויקט כדי לראות את הסשנים שלו.
+
+### Sessions
+
+מוצג רשימה של כל הסשנים בתוך פרויקט. כל סשן מוצג עם:
+- מזהה סשן
+- חותמות זמן של התחלה וסיום
+- מספר קריאות כלים
+- ספירת פעילות hook (מדיניות שהופעלו)
+
+השתמש בסינון טווח התאריכים וחיפוש מזהה סשן כדי לצמצם את הרשימה. סשנים מחולקים לעמודים.
+
+לחץ על סשן כדי לפתוח את מציג הסשן.
+
+### Session viewer
+
+מציג הסשן עונה על השאלה המרכזית עבור סוכנים עצמאיים: מה עשה הסוכן, והאם הוא נשאר בנתיב? הוא מוצג בציר הזמן של כל מה שקרה בסשן:
+
+- **Messages** - תגובות הטקסט של Claude והנושאים של המשתמש
+- **Tool calls** - כל כלי שClaude הפעיל, עם הקלט והפלט שלו
+- **Policy activity** - לכל קריאת כלים, איזו מדיניות הופעלה ואיזה החלטה היא החזירה
+
+פס הסטטיסטיקה בחלק העליון מציג משך הסשן, סה"כ קריאות כלים וסיכום של החלטות hook (מספרי allow / deny / instruct).
+
+אתה יכול לייצא את הסשן כקובץ ZIP או JSONL באמצעות כפתור ההורדה.
+
+### Policies
+
+עמוד דו-לשוני לניהול מדיניות ובדיקת פעילות.
+
+<Tabs>
+  <Tab title="Policies tab">
+  - הפוך מדיניות בודדות או כבויה בלחיצה יחידה (כותב ל-`~/.failproofai/policies-config.json`)
+  - הרחב מדיניות כדי להגדיר את הפרמטרים שלה (עבור מדיניות התומכת ב-`policyParams`)
+  - התקן או הסר hook עבור scope מסוים
+  - הגדר נתיב קובץ מדיניות מותאם אישית
+  </Tab>
+  <Tab title="Activity tab">
+  - היסטוריה מחולקת לעמודים מלאה של כל אירוע hook שהופעל על פני כל הסשנים
+  - חיפוש לפי שם מדיניות, מזהה סשן, שם כלי או החלטה
+  - כל שורה מציגה: חותמת זמן, שם מדיניות, החלטה, שם כלי, מזהה סשן והסיבה להחלטות deny/instruct
+  </Tab>
+</Tabs>
+
+---
+
+## רענון אוטומטי
+
+לוח הבקרה יש כפתור רענון אוטומטי בניווט העליון. כאשר הוא מופעל, הדף הנוכחי מרענן בתדירות קבועה כדי להציג סשנים חדשים ופעילות מדיניות כפי שהם מופיעים. חיוני לניטור סשנים של סוכן עצמאי שרץ לפי זמן.
+
+---
+
+## השבתת עמודים
+
+אם אתה צריך רק חלקים מסוימים של לוח הבקרה, הגדר את `FAILPROOFAI_DISABLE_PAGES` לרשימה מופרדת בפסיקים של שמות עמודים:
+
+```bash
+FAILPROOFAI_DISABLE_PAGES=policies failproofai
+```
+
+ערכים חוקיים: `policies`, `projects`.
+
+---
+
+## ערכת נושאים
+
+לוח הבקרה תומך במצב בהיר וכהה. הפוך דרך הכפתור בסרגל הניווט. ההעדפה מאוחסנת בפחיות האחסון המקומי של הדפדפן שלך.
+
+---
+
+## הגדרת נתיב הפרויקטים
+
+כברירת מחדל, לוח הבקרה קורא מספרייה הפרויקטים הסטנדרטית של Claude Code. עקוף אותו להגדרות מותאמות אישית:
+
+```bash
+CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
+```
+
+---
+
+## גישה מחשב יחידה שלא localhost
+
+כאשר מפעילים את לוח הבקרה ב-**dev mode** (`npm run dev`) וגישה אליו מ-hostname שאינו `localhost` - לדוגמה, דומיין מותאם אישית, IP מרחוק או URL מנהור - ייתכן שתראה אזהרה כמו:
+
+```text
+⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
+```
+
+זה Next.js חוסם גישה חוצה-origin ל-websocket HMR (hot module reload) שלו, שהיא תכונה dev-only. כדי לאפשר את ה-host שלך, השתמש בדגל `--allowed-origins`:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com
+```
+
+עבור מספר hosts או IPs, העבר רשימה מופרדת בפסיקים:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
+```
+
+אתה יכול גם להגדיר את משתנה הסביבה `FAILPROOFAI_ALLOWED_DEV_ORIGINS` במקום:
+
+```bash
+FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
+```
+
+<Note>
+זה חל רק על dev mode. כאשר מפעילים `failproofai` (production mode), אין websocket HMR ואין בעיית משאב dev cross-origin.
+</Note>