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

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

@@ -1,333 +0,0 @@
----
----
-title: ארכיטקטורה
-description: "כיצד מטפל ה-hook, טעינת התצורה והערכת המדיניות עובדים באופן פנימי"
-icon: sitemap
----
-
-מסמך זה מסביר כיצד failproofai עובד באופן פנימי: כיצד מערכת ה-hook חוצצת קריאות כלי סוכן, כיצד התצורה נטענת ומוזגת, כיצד מדיניות מוערכת, וכיצד לוח המחוונים מנטר פעילות סוכן.
-
----
-
-## סקירה כללית
-
-ל-failproofai יש שתי תת-מערכות עצמאיות:
-
-1. **מטפל ה-Hook** - תהליך CLI מהיר שהוא Claude Code משדר בכל קריאת כלי סוכן. מעריך מדיניות והחזר החלטה.
-2. **Agent Monitor (Dashboard)** - אפליקציית Next.js לניטור מושבי סוכן וניהול מדיניות.
-
-שתי התת-מערכות חולקות קבצי תצורה ב-`~/.failproofai/` ובתיקייה `~/.failproofai/` של הפרויקט, אך הם פועלים כתהליכים נפרדים ותקשורתם היא רק דרך מערכת הקבצים.
-
----
-
-## מטפל ה-Hook
-
-### אינטגרציה עם Claude Code
-
-כאשר אתה מריץ `failproofai policies --install`, הוא כותב ערכים כמו זה ב-`~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "failproofai --hook PreToolUse"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [ ... ]
-  }
-}
-```
-
-Claude Code לאחר מכן משדר `failproofai --hook PreToolUse` כתת-תהליך לפני כל קריאת כלי, והעברת עומס JSON על stdin.
-
-### פורמט עומס
-
-```json
-{
-  "session_id": "abc123",
-  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
-  "cwd": "/home/user/myproject",
-  "permission_mode": "default",
-  "hook_event_name": "PreToolUse",
-  "tool_name": "Bash",
-  "tool_input": { "command": "sudo apt install nodejs" }
-}
-```
-
-עבור אירועי `PostToolUse`, העומס מכיל גם `tool_result` עם הפלט של הכלי.
-
-המטפל כופה גבול של 1 MB ל-stdin. עומסים החוצים זאת מושלכים וכל המדיניות משתמעת להרשות.
-
-### פורמט תגובה
-
-**Deny (PreToolUse):**
-```json
-{
-  "hookSpecificOutput": {
-    "permissionDecision": "deny",
-    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
-  }
-}
-```
-
-**Deny (PostToolUse):**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Blocked by failproofai because: API key detected in output"
-  }
-}
-```
-
-**Instruct (any event except Stop):**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
-  }
-}
-```
-
-**Stop event instruct:**
-- קוד יציאה: `2`
-- הנמקה כתובה ל-stderr (לא stdout)
-
-**Allow:**
-- קוד יציאה: `0`
-- stdout ריק
-
-**Allow עם הודעה:**
-
-`allow(message)` מאפשר למדיניות לשלוח הקשר מידע חזרה ל-Claude גם כאשר הפעולה מורשית. מטפל ה-Hook כותב את ה-JSON הבא ל-**stdout** (לא קובץ תצורה — זו התגובה של המטפל ל-Claude Code, בדיוק כמו תגובות deny ו-instruct למעלה):
-
-```json
-// Written to stdout by the hook handler process
-{
-  "hookSpecificOutput": {
-    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
-  }
-}
-```
-- קוד יציאה: `0` (הפעולה מורשית)
-- כאשר מדיניות מרובות החוזרות `allow` עם הודעה, ההודעות שלהן מחוברות עם שורות חדשות למחרוזת `additionalContext` יחידה
-- אם אין מדיניות המספקת הודעה, stdout הוא ריק (כמו קודם)
-
-### צינור עיבוד
-
-`src/hooks/handler.ts` מיישם את המסלול המלא:
-
-```text
-stdin JSON
-  → parse payload (max 1 MB)
-  → extract session metadata (session_id, cwd, tool_name, tool_input, etc.)
-  → readMergedHooksConfig(cwd)    ← merges project + local + global config
-  → register enabled builtin policies with resolved params
-  → load custom policies from customPoliciesPath (if set)
-  → register custom policies into policy registry
-  → evaluate all policies (builtins first, then custom)
-      → first deny short-circuits
-      → instruct decisions accumulate
-      → allow messages accumulate
-  → write JSON decision to stdout
-  → persist event to ~/.failproofai/hook-activity.jsonl
-  → exit
-```
-
-התהליך כולו פועל בפחות מ-100ms עבור עומסים טיפוסיים ללא קריאות LLM.
-
----
-
-## טעינת תצורה
-
-`src/hooks/hooks-config.ts` מיישם טעינת תצורה בתחום שלוש.
-
-```text
-[1] {cwd}/.failproofai/policies-config.json        ← project  (highest priority)
-[2] {cwd}/.failproofai/policies-config.local.json  ← local
-[3] ~/.failproofai/policies-config.json             ← global   (lowest priority)
-```
-
-ההיגיון של המיזוג:
-- `enabledPolicies` - איחוד לא משוכפל בכל שלוש הקבצים
-- `policyParams` - per-policy key, הקובץ הראשון שמגדיר את זה מנצח לחלוטין
-- `customPoliciesPath` - הקובץ הראשון שמגדיר את זה מנצח
-- `llm` - הקובץ הראשון שמגדיר את זה מנצח
-
-לוח המחוונים ברשת משתמש ב-`readHooksConfig()` (global only) לקריאה וכתיבה, מכיוון שהוא לא משדר עם cwd של פרויקט.
-
----
-
-## הערכת מדיניות
-
-`src/hooks/policy-evaluator.ts` מריץ מדיניות בסדר.
-
-עבור כל מדיניות:
-
-1. חפש את סכימת `params` של המדיניות (אם יש לה).
-2. קרא את `policyParams[policy.name]` מהתצורה המוזגת.
-3. זיזוג ערכים המסופקים על ידי המשתמש מעל ברירות ברירת המחדל בסכימה כדי לייצר `ctx.params`.
-4. התקשר ל-`policy.fn(ctx)` עם ההקשר המסולק.
-5. אם התוצאה היא `deny`, עצור מיד והחזר החלטה זו.
-6. אם התוצאה היא `instruct`, צבור את ההודעה והמשך.
-7. אם התוצאה היא `allow`, המשך למדיניות הבאה.
-
-לאחר שכל המדיניות תרוץ:
-- אם אחת כלשהי `deny` הוחזרה, פלוט את תגובת deny.
-- אם תשובות `instruct` כלשהן אוספות, פלוט תגובת instruct אחת עם כל ההודעות מחוברות.
-- אחרת, פלוט תגובת allow (stdout ריק, יציאה 0).
-
----
-
-## מדיניות בנויה
-
-`src/hooks/builtin-policies.ts` מגדיר את כל 26 המדיניות המובנות כ-`BuiltinPolicyDefinition` אובייקטים:
-
-```typescript
-interface BuiltinPolicyDefinition {
-  name: string;
-  description: string;
-  fn: (ctx: PolicyContext) => PolicyResult;
-  match: {
-    events: HookEventType[];
-    tools?: string[];
-  };
-  defaultEnabled: boolean;
-  category: string;
-  beta?: boolean;
-  params?: PolicyParamsSchema;
-}
-```
-
-מדיניות המקבלת `params` מצהירה `PolicyParamsSchema` עם סוגים וברירות ברירת מחדל עבור כל פרמטר. מעריך המדיניות מזריק ערכים מסולקים ל-`ctx.params` לפני קריאה ל-`fn`. פונקציות מדיניות קוראות ל-`ctx.params` ללא guard null מכיוון שברירות ברירת מחדל תמיד מיושמות תחילה.
-
-התאמת דפוסים בתוך מדיניות משתמשת בקלקולי פקודה מנותחים (argv), לא התאמה של מחרוזות גולמיות. זה מונע עקיפה דרך הזרקת אופרטור מעטפת (למשל דפוס עבור `sudo systemctl status *` לא יכול להיות מעוקף על ידי הוספת `; rm -rf /` לפקודה).
-
----
-
-## מדיניות מותאמת
-
-`src/hooks/custom-hooks-registry.ts` מיישם רישום מסגרת `globalThis`:
-
-```typescript
-const REGISTRY_KEY = "__failproofai_custom_hooks__";
-
-export const customPolicies = {
-  add(hook: CustomHook): void { ... }
-};
-
-export function getCustomHooks(): CustomHook[] { ... }
-export function clearCustomHooks(): void { ... }  // used in tests
-```
-
-`src/hooks/custom-hooks-loader.ts` טוען את קובץ המדיניות של המשתמש:
-
-1. קרא את `customPoliciesPath` מהתצורה; דלג אם חסר.
-2. פתור לנתיב מוחלט; בדוק קובץ קיים.
-3. כתוב מחדש את כל `from "failproofai"` ייבוא לנתיב ה-dist בפועל כדי `customPolicies` יתבררו לרישום `globalThis` זהה.
-4. כתוב מחדש ייבוא מקומי חולף רקורסיבי כדי להבטיח התאימות ESM.
-5. כתוב קבצי `.mjs` זמניים ו-`import()` קובץ הכניסה.
-6. התקשר ל-`getCustomHooks()` כדי לשלוח קטגוריות מחדש.
-7. נקה את כל הקבצים הזמניים בבלוק `finally`.
-
-בכל שגיאה (קובץ לא נמצא, שגיאת תחביר, כישלון ייבוא), השגיאה מתועדת ב-`~/.failproofai/hook.log` והטוען מחזיר מערך ריק. מדיניות מובנית לא מושפעת.
-
-מדיניות מותאמת מוערכת לאחר כל המדיניות המובנות. `deny` מדיניות מותאמת עדיין מעיל קצר מדיניות מותאמת נוספת (אך כל הבנוי כבר רץ בנקודה זו).
-
----
-
-## רישום פעילות
-
-לאחר כל אירוע hook, המטפל מוסיף שורת JSONL ל-`~/.failproofai/hook-activity.jsonl`:
-
-```json
-{
-  "timestamp": "2026-04-06T12:34:56.789Z",
-  "sessionId": "abc123",
-  "eventType": "PreToolUse",
-  "toolName": "Bash",
-  "policyName": "block-sudo",
-  "decision": "deny",
-  "reason": "sudo command blocked by failproofai",
-  "durationMs": 12
-}
-```
-
-שורה אחת לכל מדיניות שנתנה החלטה שאינה מאפשרת. החלטות Allow לא מתועדות (כדי לשמור את הקובץ קטן).
-
----
-
-## ארכיטקטורת לוח המחוונים
-
-לוח המחוונים הוא אפליקציית **Next.js 16** באמצעות App Router עם React Server Components ו-Server Actions.
-
-```text
-app/
-  layout.tsx                  ← Root layout (theme, telemetry, nav)
-  projects/page.tsx           ← Server component: list all Claude projects
-  project/[name]/page.tsx     ← Server component: list sessions in a project
-  project/[name]/session/
-    [sessionId]/page.tsx      ← Server component: render session viewer
-  policies/page.tsx           ← Client component: policy management + activity log
-  actions/
-    get-hooks-config.ts       ← Read config + policy list
-    update-hooks-config.ts    ← Toggle policy on/off
-    update-policy-params.ts   ← Update policy parameters
-    get-hook-activity.ts      ← Paginate/search activity log
-    install-hooks-web.ts      ← Install/remove hooks from the browser
-  api/
-    download/[project]/[session]/route.ts   ← Export session as ZIP/JSONL
-```
-
-**זרימת נתונים:**
-
-- רכיבי עמוד קוראים ל-`lib/projects.ts` ו-`lib/log-entries.ts` כדי לקרוא נתוני פרויקט/מושב ישירות מ-filesystem (ללא שכבת API לקריאות).
-- עמוד המדיניות משתמש בשרת Actions עבור כל מוטציות (החלפה, עדכון params, התקנה/הסרה).
-- צופה המושב מנתח פורמט תוליד JSONL של Claude ומרחיב ציר זמן של הודעות וקריאות כלים.
-
-**החלטות עיצוב מרכזיות:**
-
-- אין מסד נתונים - כל המצב קבוע נמצא בקבצים רגילים (`~/.failproofai/`, `~/.claude/projects/`).
-- Server Actions למוטציות - אין צורך ב-REST API לפעולות CRUD.
-- React Server Components עבור עמודי קריאה - קריאה ראשונית מהירה יותר, אין צרור לקוח לאחזור נתונים.
-- רכיבי לקוח רק בו זה דרוש אינטראקטיביות (החלפות מדיניות, חיפוש פעילות, צופה יומן).
-
----
-
-## פריסת קבצים
-
-```text
-failproofai/
-├── bin/
-│   └── failproofai.mjs           # CLI router (hook / dashboard / install / etc.)
-├── src/hooks/
-│   ├── handler.ts                # Hook event pipeline
-│   ├── builtin-policies.ts       # 26 policy definitions
-│   ├── policy-evaluator.ts       # Policy execution engine
-│   ├── policy-registry.ts        # Policy registration and lookup
-│   ├── policy-types.ts           # TypeScript interfaces
-│   ├── hooks-config.ts           # Multi-scope config loading
-│   ├── custom-hooks-registry.ts  # globalThis-backed hook registry
-│   ├── custom-hooks-loader.ts    # ESM loader for user JS hooks
-│   ├── manager.ts                # install / remove / list operations
-│   ├── install-prompt.ts         # Interactive policy selection prompt
-│   ├── hook-logger.ts            # Logging to hook.log
-│   ├── hook-activity-store.ts    # Persist activity to hook-activity.jsonl
-│   └── llm-client.ts             # LLM API client (for AI-powered policies)
-├── app/                          # Next.js dashboard (pages + server actions)
-├── lib/                          # Shared utilities
-│   ├── projects.ts               # Enumerate Claude projects from filesystem
-│   ├── log-entries.ts            # Parse Claude transcript JSONL format
-│   ├── paths.ts                  # Resolve system paths
-│   └── ...
-├── components/                   # Shared React UI components
-├── contexts/                     # React context providers (theme, auto-refresh, telemetry)
-├── examples/                     # Example custom hook files
-└── __tests__/                    # Unit and E2E tests
-```