failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,359 @@
+---
+
+---
+title: السياسات المخصصة
+description: "اكتب سياساتك الخاصة في JavaScript - فرض الاتفاقيات، منع الانجراف، الكشف عن الأعطال، التكامل مع الأنظمة الخارجية"
+icon: code
+---
+
+تتيح لك السياسات المخصصة كتابة قواعد لأي سلوك وكيل: فرض اتفاقيات المشروع، منع الانجراف، التحكم في العمليات الضارة، الكشف عن الوكلاء المعلقة، أو التكامل مع Slack وسير العمل الموافقات والمزيد. تستخدم نفس نظام حدث الخطاف وقرارات `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: أسقط ملفاً، وهو يعمل فقط.
+
+```
+# 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
+```
+
+**كيفية عمله:**
+- يتم فحص كلا المجلدات (المشروع والمستخدم) (الاتحاد - وليس 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`. يتم تحميل الملف بشكل جديد في كل حدث خطاف - لا يوجد تخزين مؤقت بين الأحداث.
+
+### استخدام كليهما معاً
+
+يمكن لسياسات الاتفاقية والملف الصريح `--custom` أن يتعايشا. ترتيب التحميل:
+
+1. ملف `customPoliciesPath` الصريح (إذا تم تكوينه)
+2. ملفات اتفاقية المشروع (`{cwd}/.failproofai/policies/`، أبجدياً)
+3. ملفات اتفاقية المستخدم (`~/.failproofai/policies/`، أبجدياً)
+
+---
+
+## واجهة برمجية التطبيقات
+
+### الاستيراد
+
+```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/`). انظر [التكوين → hint](/ar/configuration#hint-cross-cutting) للتفاصيل.
+</Tip>
+
+### رسائل السماح المعلوماتية (بيتا)
+
+<Note>
+`allow(message)` هي ميزة بيتا متاحة منذ v0.0.2-beta.3. قد تتغير واجهة برمجية التطبيقات في الإصدارات المستقبلية. الإصدارات السابقة تدعم فقط `allow()` بدون وسائط.
+</Note>
+
+`allow(message)` يسمح بالعملية **و** يرسل رسالة معلومات مرة أخرى إلى Claude. يتم تسليم الرسالة كـ `additionalContext` في استجابة stdout لمعالج الخطاف - نفس الآلية المستخدمة من قبل `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>` | حمل الحدث الخام الكامل من 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" \| ... }` - يجب أن تعيد الخطافات دائماً `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**: الأخطاء لا تحظر السياسات المدمجة أو تعطل معالج الخطاف.
+
+| الفشل | السلوك |
+|---------|----------|
+| `customPoliciesPath` لم تُعيّن | لا تعمل السياسات المخصصة الصريحة؛ سياسات الاتفاقية والمدمجة تستمر بشكل طبيعي |
+| ملف غير موجود | تم تسجيل تحذير في `~/.failproofai/hook.log`؛ المدمجة تستمر |
+| خطأ في الصيغة/الاستيراد (صريح) | تم تسجيل الخطأ في `~/.failproofai/hook.log`؛ سياسات مخصصة صريحة تم تخطيها |
+| خطأ في الصيغة/الاستيراد (اتفاقية) | تم تسجيل الخطأ؛ هذا الملف تم تخطيه، ملفات اتفاقية أخرى لا تزال تحمل |
+| `fn` رمي في وقت التشغيل | تم تسجيل الخطأ؛ تم التعامل مع الخطاف كـ `allow`؛ الخطافات الأخرى تستمر |
+| `fn` يستغرق أكثر من 10 ثوان | تم تسجيل المهلة الزمنية؛ تم التعامل معها كـ `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` | أنماط متقدمة: واردات متعدية، استدعاءات غير متزامنة، تنقية الإخراج، وخطافات نهاية الجلسة |
+| `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/
+```
+
+لا حاجة لأمر التثبيت - يتم اختيار الملفات تلقائياً عند حدث الخطاف التالي.

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

@@ -0,0 +1,142 @@
+---
+title: لوحة التحكم
+description: "مراقبة جلسات الوكيل ومراجعة استدعاءات الأدوات وإدارة السياسات"
+icon: chart-line
+---
+
+لوحة التحكم failproofai هي تطبيق ويب محلي لمراقبة جلسات وكيل الذكاء الاصطناعي الخاص بك وإدارة السياسات. اطلع على ما فعله وكلاؤك أثناء غيابك.
+
+---
+
+## بدء لوحة التحكم
+
+```bash
+failproofai
+```
+
+يفتح في `http://localhost:8020`.
+
+تقرأ لوحة التحكم مباشرة من نظام الملفات - مشاريع Claude Code والملفات الإعدادات الخاصة بـ failproofai. لا يتم كتابة أي شيء إلى خدمة بعيدة.
+
+---
+
+## الصفحات
+
+### المشاريع
+
+يسرد جميع مشاريع Claude Code الموجودة على جهازك. يتم اكتشاف المشاريع من `~/.claude/projects/` (أو المسار المحدد بواسطة `CLAUDE_PROJECTS_PATH`).
+
+يعرض كل مشروع:
+- اسم المشروع (مشتق من مسار المجلد)
+- عدد الجلسات
+- تاريخ أحدث نشاط للجلسة
+
+انقر على مشروع لمشاهدة جلساته.
+
+### الجلسات
+
+يسرد جميع الجلسات داخل مشروع. تعرض كل جلسة:
+- معرّف الجلسة
+- طوابع زمنية البدء والانتهاء
+- عدد استدعاءات الأدوات
+- عدد أنشطة الخطاف (السياسات التي تم تفعيلها)
+
+استخدم مرشح نطاق التاريخ والبحث عن معرّف الجلسة لتضييق القائمة. يتم ترقيم الجلسات.
+
+انقر على جلسة لفتح عارض الجلسة.
+
+### عارض الجلسة
+
+يجيب عارض الجلسة على السؤال الرئيسي للوكلاء المستقلين: ماذا فعل الوكيل، وهل ظل على المسار الصحيح؟ يعرض خط زمني لكل ما حدث في الجلسة:
+
+- **الرسائل** - الردود النصية من Claude وطلبات المستخدم
+- **استدعاءات الأدوات** - كل أداة استدعاها Claude، مع مدخلاتها ومخرجاتها
+- **نشاط السياسة** - لكل استدعاء أداة، السياسات التي تم تفعيلها والقرار الذي أرجعته
+
+يعرض شريط الإحصائيات في الأعلى مدة الجلسة وإجمالي استدعاءات الأدوات وملخص قرارات الخطاف (عدد السماح / الرفض / التعليمات).
+
+يمكنك تصدير الجلسة كملف ZIP أو JSONL باستخدام زر التحميل.
+
+### السياسات
+
+صفحة بتبويبين لإدارة السياسات ومراجعة النشاط.
+
+<Tabs>
+  <Tab title="تبويب السياسات">
+  - تبديل السياسات الفردية بنقرة واحدة (الكتابة إلى `~/.failproofai/policies-config.json`)
+  - قم بتوسيع سياسة لتكوين معاملات بها (بالنسبة للسياسات التي تدعم `policyParams`)
+  - تثبيت أو إزالة الخطافات لنطاق معين
+  - تعيين مسار ملف سياسات مخصص
+  </Tab>
+  <Tab title="تبويب النشاط">
+  - السجل المرقّم الكامل لكل حدث خطاف تم تفعيله عبر جميع الجلسات
+  - البحث حسب اسم السياسة أو معرّف الجلسة أو اسم الأداة أو القرار
+  - يعرض كل صف: الطابع الزمني واسم السياسة والقرار واسم الأداة ومعرّف الجلسة والسبب لقرارات الرفض / التعليمات
+  </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
+
+عند تشغيل لوحة التحكم في **وضع التطوير** (`npm run dev`) والوصول إليها من اسم مضيف بخلاف `localhost` - على سبيل المثال، مجال مخصص أو عنوان IP بعيد أو عنوان URL محفور - قد ترى تحذيراً مثل:
+
+```text
+⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
+```
+
+هذا هو Next.js يحظر الوصول عبر الأصول إلى موارد HMR (إعادة تحميل الوحدة الساخنة)، وهي ميزة تطوير فقط. للسماح بمضيفك، استخدم علم `--allowed-origins`:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com
+```
+
+لعدة مضيفات أو عناوين IP، مرر قائمة مفصولة بفواصل:
+
+```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>
+ينطبق هذا فقط على وضع التطوير. عند تشغيل `failproofai` (وضع الإنتاج)، لا توجد مقبس ويب HMR ولا توجد مشكلة موارد تطوير عبر الأصول.
+</Note>