failproofai 0.0.6-beta.2 → 0.0.6-beta.4

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

@@ -1,353 +0,0 @@
----
-title: מדיניויות מותאמות אישית
-description: "כתוב כללים משלך ב-JavaScript - אכוף קונבנציות, מנע סטיות, גלה כשלים, שלב עם מערכות חיצוניות"
-icon: code
----
-
-מדיניויות מותאמות אישית מאפשרות לך לכתוב כללים לכל התנהגות של סוכן: אכוף קונבנציות פרויקט, מנע סטיות, חסום פעולות הרסניות, גלה סוכנים תקועים, או שלב עם Slack, זרימות אישור ועוד. הם משתמשים באותה מערכת אירועי hook וקבלות החלטות `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: מבוססת קונבנציה (מומלץ)
-
-שם קבצי `*policies.{js,mjs,ts}` ב-`.failproofai/policies/` והם נטענים באופן אוטומטי — אין צורך בדגלים או שינויי תצורה. זה פועל כמו git hooks: שם קובץ, זה פשוט עובד.
-
-```
-# ברמת פרויקט — מחויב ב-git, משותף עם הצוות
-.failproofai/policies/security-policies.mjs
-.failproofai/policies/workflow-policies.mjs
-
-# ברמת משתמש — אישי, חל על כל הפרויקטים
-~/.failproofai/policies/my-policies.mjs
-```
-
-**איך זה עובד:**
-- שני הספריות של פרויקט ומשתמש סורקות (איחוד — לא first-scope-wins)
-- קבצים נטענים באופן אלפביתי בכל ספרייה. הוסף קידומת עם `01-`, `02-` כדי לשלוט בסדר
-- רק קבצים התואמים `*policies.{js,mjs,ts}` נטענים; קבצים אחרים מתעלמים
-- כל קובץ נטען בנפרד (fail-open לכל קובץ)
-- עובד לצד `--custom` מפורש ומדיניויות מובנות
-
-<Tip>
-מדיניויות קונבנציה הן הדרך הקלה ביותר לבנות תקן איכות עבור הארגון שלך. קבע `.failproofai/policies/` ל-git וכל חברי הצוות יקבלו את אותם כללים באופן אוטומטי — אין צורך בהתקנה לכל מפתח. כאשר הצוות שלך גוקל מצבי כשל חדשים, הוסף מדיניות ודחוף. עם הזמן אלה הופכים לתקן איכות חי המשתפר עם כל תרומה.
-</Tip>
-
-### אפשרות 2: נתיב קובץ מפורש
-
-```bash
-# התקן עם קובץ מדיניויות מותאם אישית
-failproofai policies --install --custom ./my-policies.js
-
-# החלף את נתיב קובץ המדיניויות
-failproofai policies --install --custom ./new-policies.js
-
-# הסר את נתיב המדיניויות המותאמות אישית מהתצורה
-failproofai policies --uninstall --custom
-```
-
-הנתיב המוחלט שנפתר מאוחסן ב-`policies-config.json` כ-`customPoliciesPath`. הקובץ נטען מחדש בכל אירוע hook - אין caching בין אירועים.
-
-### שימוש בשניהם יחד
-
-מדיניויות קונבנציה וקובץ `--custom` מפורש יכולים להתקיים. סדר הטעינה:
-
-1. קובץ `customPoliciesPath` מפורש (אם מוגדר)
-2. קבצי קונבנציה של פרויקט (`{cwd}/.failproofai/policies/`, אלפביתי)
-3. קבצי קונבנציה של משתמש (`~/.failproofai/policies/`, אלפביתי)
-
----
-
-## API
-
-### ייבוא
-
-```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)` | חסום את הפעולה | הסוכן לא צריך לבצע פעולה זו |
-| `instruct(message)` | הוסף הקשר ללא חסימה | תן לסוכן הקשר נוסף להישארות על המסלול |
-
-`deny(message)` - ההודעה מופיעה לClaude עם קידומת `"Blocked by failproofai:"`. `deny` יחיד מקצר את כל ההערכה הנוספת.
-
-`instruct(message)` - ההודעה מצורפת להקשר של Claude לקריאת הכלי הנוכחית. כל הודעות `instruct` מצטברות ומועברות ביחד.
-
-<Tip>
-אתה יכול להוסיף הנחיה נוספת לכל הודעת `deny` או `instruct` על ידי הוספת שדה `hint` ב-`policyParams` — אין צורך בשינוי קוד. זה עובד עבור מדיניויות מותאמות אישית (`custom/`), קונבנציה של פרויקט (`.failproofai-project/`), וקונבנציה של משתמש (`.failproofai-user/`) גם כן. ראה [Configuration → hint](/he/configuration#hint-cross-cutting) לפרטים.
-</Tip>
-
-### הודעות allow מידע
-
-`allow(message)` מאפשרת את הפעולה **וגם** שולחת הודעה מידע חזרה לClaude. ההודעה מועברת כ-`additionalContext` בתגובת stdout של מטפל ה-hook — אותה מנגנון המשמש `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. מדיניויות מותאמות אישית מפורשות מ-`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.
-
-| כשל | התנהגות |
-|---------|----------|
-| `customPoliciesPath` לא מוגדר | אין מדיניויות מותאמות אישית מפורשות פועלות; מדיניויות קונבנציה ומובנות ממשיכות כרגיל |
-| קובץ לא נמצא | אזהרה רשומה ל-`~/.failproofai/hook.log`; מובנות ממשיכות |
-| שגיאה syntax/import (מפורשת) | שגיאה רשומה ל-`~/.failproofai/hook.log`; מדיניויות מותאמות אישית מפורשות דלג |
-| שגיאה 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` | חמש מדיניויות הפעלה המכסות מצבי כשל סוכן נפוצים |
-| `examples/policies-advanced/index.js` | דפוסים מתקדמים: ייבואים טרנזיטיביים, קריאות אסינכרוניות, scrubbing פלט ו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

@@ -1,142 +0,0 @@
----
-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>