failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/ar/agenteye/telemetry.mdx

@@ -0,0 +1,52 @@
+---
+title: "مقاييس الأداء"
+description: "اكتشف اللحظة التي تبطئ فيها نماذجك أو أدواتك أو خطافاتك أو تزيد الفواتير، واعترض قفزة الكمون النهائي قبل أن يشعر بها مستخدموك."
+---
+
+
+اكتشف اللحظة التي تبطئ فيها نماذجك أو أدواتك أو خطافاتك أو تزيد الفواتير، واعترض قفزة الكمون النهائي قبل أن يشعر بها مستخدموك. ثلاث صفحات مخصصة تحول التوقيتات الخام إلى p50 و p95 و p99 يمكنك قراءتها في لمحة.
+
+![صفحة النماذج تعرض خريطة حرارية للكمون، وشريط مئوي، وأرقام التوكن والتكلفة والنافذة السياقية لكل نموذج](/agenteye/images/models.png)
+*صفحة النماذج: خريطة حرارية للكمون، وشريط مئوي، وأرقام التوكن والتكلفة المقدرة ومؤشر امتلاء النافذة السياقية لكل نموذج.*
+
+## توقف عن السماح للمتوسطات بإخفاء أسوأ عملياتك
+
+رقم متوسط الكمون مريح وعديم الفائدة: فهو يمسح على ما يحدث في واحدة من كل خمسين استدعاء تتعطل وتنبهك في الساعة الثانية صباحًا. صفحات النماذج والأدوات والخطافات ترفض أن تفعل ذلك. كل منها تشترك في نفس الشكل، لذلك تتعلمها مرة واحدة:
+
+- **رسم بياني صغير بـ 24 فئة** للاتجاه في لمحة: هل يزداد سوءًا؟
+- **شريط الحيويات** مع كمون p50 و p95 و p99، بحيث تجلس العملية النموذجية والنهاية جنبًا إلى جنب.
+- **خريطة حرارية للكمون**، 24 فئة زمنية حسب فئات الكمون، التي تظهر *متى* تجمعت الاستدعاءات البطيئة.
+- **شريط مئوي**: خط p50 مع شرائط مظللة p25 إلى p75 و p10 إلى p90 ونقاط p99، بحيث يبقى الانتشار مرئيًا بدلاً من أن يتم حساب متوسطه.
+
+مؤشر تحرك مشترك يربط الخريطة الحرارية والشريط، بحيث يتم توصيل قفزة النهاية في الوقت عبر كليهما بدلاً من الاختباء خلف خط متوسط واحد. ابحث عن الصفحات الثلاث جميعها في قسم **المراقبة** في لوحة معلوماتك، كل منها محدد نطاق لمؤسستك وقابل للتصفية حسب نطاق التاريخ والبيئة والوكيل والجلسة.
+
+## النماذج: اكتشف بالضبط تكلفة كل نموذج
+
+صفحة النماذج (كما هو موضح أعلاه) تجيب على السؤالين اللذين تطرحهما الفاتورة دائمًا: أي نموذج وكم التكلفة. بالإضافة إلى عرض الكمون المشترك، فإنها تضيف **استهلاك التوكن لكل نموذج** و **التكلفة المقدرة** و **مؤشر امتلاء النافذة السياقية**، بحيث يكون نمو الطلب الجامح واقتراب الضغط مرئيًا قبل أن يفاجئك.
+
+يتعرف Failproof AI Observability على معرّفات النماذج الشائعة تلقائيًا. إذا بدت نافذة غير صحيحة، أو كنت تشغل نموذجك الخاص، قم بتصحيحها أو أضف واحدة ضمن **الإعدادات** في **نوافذ السياق للنموذج** والقراءات المتعلقة بالامتلاء تتبع.
+
+## الأدوات: ميز البطيء عن المكسور
+
+يمكن أن تكون استدعاءة الأداة بطيئة، أو قد تفشل بهدوء، وتريد أن تعرف أيهما في ثوانٍ، وليس بعد البحث في السجلات.
+
+![صفحة الأدوات تعرض خريطة الكمون الحرارية المشتركة وشريط المئويات بجانب تفصيل النجاح والفشل وشريط توزيع الأدوات](/agenteye/images/tools.png)
+*صفحة الأدوات: نفس الخريطة الحرارية والشريط المئوي، بالإضافة إلى تفصيل النجاح والفشل وشريط توزيع الأدوات.*
+
+إلى جانب عرض الكمون المشترك، تضيف صفحة الأدوات **تفصيل النجاح والفشل** و **شريط توزيع الأدوات**، بحيث ترى في لمحة الأدوات التي تعتمد عليها أكثر والتي تستنزف ميزانية الخطأ الخاصة بك.
+
+## الخطافات: حدد الخطاف المحدد وحدث التفعيل
+
+عندما يبطئ خطاف دورة حياة عملية ما، "الخطافات بطيئة" ليس شيئًا يمكنك العمل عليه. تأخذك صفحة الخطافات إلى الواحد الذي يهمك.
+
+![صفحة الخطافات تعرض الكمون مقسم حسب اسم الخطاف وحدث التفعيل على خريطة الكمون الحرارية المشتركة والشريط المئوي](/agenteye/images/hooks.png)
+*صفحة الخطافات: الكمون مقسم حسب اسم الخطاف وحدث التفعيل.*
+
+فوق نفس خريطة الكمون الحرارية والشريط المئوي، تقسم صفحة الخطافات النشاط حسب **اسم الخطاف** و **حدث التفعيل**، بحيث تهبط على الخطاف الواحد وحدث التفعيل الواحد اللذين يحتاجان إلى انتباه.
+
+## ذات صلة
+
+- [دفق الأحداث](/ar/agenteye/event-stream): المسار الفوري الملون لكل حدث.
+- [الجلسات](/ar/agenteye/sessions): قم بتجميع الأحداث في صف واحد لكل تشغيل وافتح رسم البياني الخاص به.
+- [تتبع الأخطاء](/ar/agenteye/error-tracking): سطح تريج واحد لكل شيء يرسمه لوحة المعلومات باللون الأحمر.
+- [لوحات المعلومات](/ar/agenteye/dashboards): طرق التجميع عبر أسطولك.

package/.next/standalone/docs-old/ar/architecture.mdx

@@ -0,0 +1,333 @@
+---
+---
+title: المعمارية
+description: "كيف يعمل معالج الخطاف وتحميل الإعدادات وتقييم السياسات داخليًا"
+icon: sitemap
+---
+
+تشرح هذه الوثيقة كيف يعمل failproofai داخليًا: كيف يعترض نظام الخطاف استدعاءات أدوات الوكيل، وكيف يتم تحميل ودمج الإعدادات، وكيف يتم تقييم السياسات، وكيف تراقب لوحة المعلومات نشاط الوكيل.
+
+---
+
+## نظرة عامة
+
+يحتوي failproofai على نظامين فرعيين مستقلين:
+
+1. **معالج الخطاف** - عملية CLI سريعة يستدعيها Claude Code عند كل استدعاء لأداة الوكيل. يقيّم السياسات ويعيد قرارًا.
+2. **مراقب الوكيل (لوحة المعلومات)** - تطبيق ويب Next.js لمراقبة جلسات الوكيل وإدارة السياسات.
+
+يشترك كلا النظام الفرعي في ملفات الإعدادات في `~/.failproofai/` وفي مجلد `.failproofai/` للمشروع، لكنهما يعملان كعمليتين منفصلتين ولا يتواصلان إلا من خلال نظام الملفات.
+
+---
+
+## معالج الخطاف
+
+### التكامل مع 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 ميجابايت لـ stdin. الحمولات التي تتجاوز هذا الحد يتم تجاهلها وجميع السياسات تسمح ضمنيًا.
+
+### تنسيق الاستجابة
+
+**الرفض (PreToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
+  }
+}
+```
+
+**الرفض (PostToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Blocked by failproofai because: API key detected in output"
+  }
+}
+```
+
+**التعليمات (أي حدث باستثناء Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**حدث التعليمات من النوع Stop:**
+- رمز الخروج: `2`
+- السبب مكتوب على stderr (وليس stdout)
+
+**السماح:**
+- رمز الخروج: `0`
+- stdout فارغ
+
+**السماح مع رسالة:**
+
+`allow(message)` تتيح لسياسة ما إرسال سياق معلوماتي إلى Claude حتى عندما تكون العملية مسموحة. يكتب معالج الخطاف JSON التالي إلى **stdout** (وليس ملف إعدادات — هذه استجابة المعالج لـ Claude Code، تمامًا مثل استجابات الرفض والتعليمات أعلاه):
+
+```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/current.jsonl
+  → exit
+```
+
+تعمل العملية بأكملها في أقل من 100 ميلي ثانية للحمولات النموذجية بدون استدعاءات 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` - لكل سياسة، الملف الأول الذي يعرّفها يفوز بالكامل
+- `customPoliciesPath` - الملف الأول الذي يعرّفه يفوز
+- `llm` - الملف الأول الذي يعرّفه يفوز
+
+تستخدم لوحة معلومات الويب `readHooksConfig()` (عام فقط) للقراءة والكتابة، لأنها لا تُستدعى مع 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`، أصدر استجابة الرفض.
+- إذا تم جمع أي إرجاعات `instruct`، أصدر استجابة تعليمات واحدة مع دمج جميع الرسائل.
+- خلاف ذلك، أصدر استجابة سماح (stdout فارغ، الخروج 0).
+
+---
+
+## السياسات المدمجة
+
+يُعرّف `src/hooks/builtin-policies.ts` جميع 39 سياسة مدمجة كائنات `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` دون حماية 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` ويعيد المحمّل مصفوفة فارغة. السياسات المدمجة لا تتأثر.
+
+يتم تقييم السياسات المخصصة بعد جميع السياسات المدمجة. رفض سياسة مخصصة لا يزال يعطل السياسات المخصصة الإضافية (لكن جميع المدمجات قد عملت بالفعل في تلك النقطة).
+
+---
+
+## تسجيل النشاط
+
+بعد كل حدث خطاف، يضيف المعالج سطر JSONL إلى `~/.failproofai/hook-activity/current.jsonl`، والذي يدور إلى `page-<timestamp>-<seq>.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
+}
+```
+
+سطر واحد لكل سياسة أدت إلى قرار غير سماح. لا يتم تسجيل قرارات السماح (للحفاظ على صغر حجم الملف).
+
+---
+
+## معمارية لوحة المعلومات
+
+لوحة المعلومات هي تطبيق **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   ← Per-CLI session export (JSONL or JSON)
+```
+
+**تدفق البيانات:**
+
+- تستدعي مكونات الصفحة `lib/projects.ts` و `lib/log-entries.ts` لقراءة بيانات المشروع/الجلسة مباشرة من نظام الملفات (بدون طبقة API للقراءات).
+- تستخدم صفحة السياسات Server Actions لجميع التغييرات (تبديل، تحديث المعاملات، التثبيت/الإزالة).
+- يُحلّل عارض الجلسة تنسيق النسخة 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       # 39 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/
+│   └── 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
+```