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

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

@@ -1,354 +0,0 @@
----
----
-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: قائم على الاتفاقية (مُوصى به)
-
-أسقط ملفات `*policies.{js,mjs,ts}` في `.failproofai/policies/` وسيتم تحميلها تلقائياً - لا توجد علامات أو تغييرات إعدادات مطلوبة. يعمل هذا مثل خطافات git: أسقط ملف وسيعمل فحسب.
-
-```
-# المستوى المشروع — معهود إلى git ومشترك مع الفريق
-.failproofai/policies/security-policies.mjs
-.failproofai/policies/workflow-policies.mjs
-
-# مستوى المستخدم — شخصي، ينطبق على جميع المشاريع
-~/.failproofai/policies/my-policies.mjs
-```
-
-**كيف يعمل:**
-- يتم مسح كلا دليل المشروع والمستخدم (اتحاد - وليس أول نطاق يفوز)
-- يتم تحميل الملفات أبجدياً داخل كل دليل. استخدم البادئة `01-` و`02-` للتحكم في الترتيب
-- يتم تحميل الملفات المطابقة فقط لـ `*policies.{js,mjs,ts}`؛ تُتجاهل الملفات الأخرى
-- يتم تحميل كل ملف بشكل مستقل (فتح مفشول لكل ملف)
-- يعمل جنباً إلى جنب مع السياسات الصريحة `--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`. يتم تحميل الملف بشكل جديد في كل حدث خطاف - لا يوجد تخزين مؤقت بين الأحداث.
-
-### استخدام كليهما معاً
-
-يمكن أن توجد سياسات الاتفاقية وملف `--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;                         // مطلوب - معرّف فريد
-  description?: string;                 // معروض في إخراج `failproofai policies`
-  match?: { events?: HookEventType[] }; // تصفية حسب نوع الحدث؛ احذف للمطابقة مع الكل
-  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
-});
-```
-
-### مساعدات القرار
-
-| الدالة | التأثير | استخدم عندما |
-|----------|--------|----------|
-| `allow()` | السماح بالعملية بصمت | الإجراء آمن، لا توجد حاجة لرسالة |
-| `deny(message)` | حجب العملية | لا يجب على الوكيل اتخاذ هذا الإجراء |
-| `instruct(message)` | إضافة سياق بدون حجب | أعط الوكيل سياق إضافي للبقاء على المسار |
-
-`deny(message)` - تظهر الرسالة لـ Claude مع البادئة `"Blocked by failproofai:"`. يؤدي رفض واحد إلى قطع جميع التقييمات الإضافية.
-
-`instruct(message)` - يتم إلحاق الرسالة بسياق Claude لاستدعاء الأداة الحالي. يتم تجميع جميع رسائل `instruct` وتسليمها معاً.
-
-<Tip>
-يمكنك إضافة إرشادات إضافية إلى أي رسالة `deny` أو `instruct` بإضافة حقل `hint` في `policyParams` - لا حاجة لتغيير الكود. هذا يعمل مع السياسات المخصصة (`custom/`) واتفاقية المشروع (`.failproofai-project/`) واتفاقية المستخدم (`.failproofai-user/`) أيضاً. انظر [Configuration → hint](/ar/configuration#hint-cross-cutting) للتفاصيل.
-</Tip>
-
-### رسائل السماح المعلوماتية
-
-`allow(message)` يسمح بالعملية **و** يرسل رسالة معلوماتية مرة أخرى إلى Claude. يتم تسليم الرسالة كـ `additionalContext` في استجابة stdout لمعالج الخطاف - نفس الآلية المستخدمة بـ `instruct`، لكن مختلفة دلالياً: إنها تحديث حالة وليس تحذير.
-
-| الدالة | التأثير | استخدم عندما |
-|----------|--------|----------|
-| `allow(message)` | السماح وإرسال سياق إلى Claude | تأكيد اجتياز الفحص أو شرح السبب في تخطي الفحص |
-
-حالات الاستخدام:
-- **تأكيدات الحالة:** `allow("All CI checks passed.")` - يخبر Claude أن كل شيء أخضر
-- **شروحات الفتح المفشول:** `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.");
-
-    // ... تحقق من حالة الفرع ...
-    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) => {
-    // يتم التشغيل فقط عند انتهاء الجلسة
-    // ctx.session.transcriptPath يحتوي على سجل الجلسة الكامل
-    return allow();
-  },
-});
-```
-
-احذف `match` بالكامل للتشغيل على كل نوع حدث.
-
----
-
-## معالجة الأخطاء وأنماط الفشل
-
-السياسات المخصصة **فتح مفشول**: الأخطاء لا تحجب أبداً السياسات المدمجة أو تعطل معالج الخطاف.
-
-| الفشل | السلوك |
-|---------|----------|
-| `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";
-
-// منع الوكيل من الكتابة إلى دليل secrets/
-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();
-  },
-});
-
-// ابق الوكيل على المسار: تحقق من الاختبارات قبل الالتزام
-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();
-  },
-});
-
-// منع تغييرات المتعلقات غير المخطط لها أثناء التجميد
-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
-# انسخ إلى مستوى المشروع
-mkdir -p .failproofai/policies
-cp examples/convention-policies/*.mjs .failproofai/policies/
-
-# أو انسخ إلى مستوى المستخدم
-mkdir -p ~/.failproofai/policies
-cp examples/convention-policies/*.mjs ~/.failproofai/policies/
-```
-
-لا توجد حاجة لأمر التثبيت - يتم التقاط الملفات تلقائياً في حدث الخطاف التالي.

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

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