failproofai 0.0.5 → 0.0.6-beta.1

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

@@ -1,12 +1,11 @@
 ---
-
 ---
 title: السياسات المخصصة
-description: "اكتب سياساتك الخاصة في JavaScript - فرض الاتفاقيات، منع الانجراف، الكشف عن الأعطال، التكامل مع الأنظمة الخارجية"
+description: "اكتب سياساتك الخاصة بلغة JavaScript - فرض الاتفاقيات، منع الانجراف، اكتشاف الأعطال، التكامل مع الأنظمة الخارجية"
 icon: code
 ---
 
-تتيح لك السياسات المخصصة كتابة قواعد لأي سلوك وكيل: فرض اتفاقيات المشروع، منع الانجراف، التحكم في العمليات الضارة، الكشف عن الوكلاء المعلقة، أو التكامل مع Slack وسير العمل الموافقات والمزيد. تستخدم نفس نظام حدث الخطاف وقرارات `allow` و `deny` و `instruct` كما هو الحال في السياسات المدمجة.
+تتيح لك السياسات المخصصة كتابة قواعد لأي سلوك وكيل: فرض اتفاقيات المشروع، منع الانجراف، حماية العمليات المدمرة، كشف الوكلاء العالقين، أو التكامل مع Slack وسير العمل الموافقة والمزيد. تستخدم نفس نظام أحداث الخطاف وقرارات `allow` و `deny` و `instruct` مثل السياسات المدمجة.
 
 ---
 
@@ -31,7 +30,7 @@ customPolicies.add({
 });
 ```
 
-تثبيتها:
+قم بتثبيته:
 
 ```bash
 failproofai policies --install --custom ./my-policies.js
@@ -41,56 +40,56 @@ failproofai policies --install --custom ./my-policies.js
 
 ## طريقتان لتحميل السياسات المخصصة
 
-### الخيار 1: المبنية على الاتفاقية (موصى به)
+### الخيار 1: قائم على الاتفاقية (موصى به)
 
-أسقط ملفات `*policies.{js,mjs,ts}` في `.failproofai/policies/` وسيتم تحميلها تلقائياً - لا تحتاج إلى أعلام أو تغييرات في الإعدادات. يعمل هذا مثل خطافات git: أسقط ملفاً، وهو يعمل فقط.
+ضع ملفات `*policies.{js,mjs,ts}` في `.failproofai/policies/` وسيتم تحميلها تلقائياً — لا توجد علامات أو تغييرات في الإعدادات المطلوبة. يعمل هذا مثل خطافات git: ضع ملفاً، وسيعمل فقط.
 
 ```
-# Project level — committed to git, shared with the team
+# مستوى المشروع — يتم الالتزام به في git، مشترك مع الفريق
 .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 لكل ملف)
+**كيف يعمل:**
+- يتم فحص كل من مجلدات المشروع والمستخدم (الاتحاد — وليس السيطرة الأولى)
+- يتم تحميل الملفات أبجدياً داخل كل مجلد. البادئة مع `01-`، `02-` للتحكم في الترتيب
+- يتم تحميل الملفات المطابقة فقط `*policies.{js,mjs,ts}`؛ يتم تجاهل الملفات الأخرى
+- يتم تحميل كل ملف بشكل مستقل (فتح بفشل لكل ملف)
 - يعمل جنباً إلى جنب مع السياسات الصريحة `--custom` والمدمجة
 
 <Tip>
-سياسات الاتفاقية هي أسهل طريقة لمشاركة السياسات عبر الفريق. التزم `.failproofai/policies/` بـ git ويحصل كل عضو في الفريق عليها تلقائياً.
+سياسات الاتفاقية هي أسهل طريقة لمشاركة السياسات عبر الفريق. التزم بـ `.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`. يتم تحميل الملف بشكل جديد في كل حدث خطاف - لا يوجد تخزين مؤقت بين الأحداث.
+يتم تخزين المسار المطلق المحل في `policies-config.json` كـ `customPoliciesPath`. يتم تحميل الملف بشكل جديد في كل حدث خطاف - لا يوجد تخزين مؤقت بين الأحداث.
 
 ### استخدام كليهما معاً
 
-يمكن لسياسات الاتفاقية والملف الصريح `--custom` أن يتعايشا. ترتيب التحميل:
+يمكن أن تتعايش سياسات الاتفاقية وملف `--custom` الصريح. ترتيب التحميل:
 
 1. ملف `customPoliciesPath` الصريح (إذا تم تكوينه)
-2. ملفات اتفاقية المشروع (`{cwd}/.failproofai/policies/`، أبجدياً)
-3. ملفات اتفاقية المستخدم (`~/.failproofai/policies/`، أبجدياً)
+2. ملفات الاتفاقية للمشروع (`{cwd}/.failproofai/policies/`، أبجدياً)
+3. ملفات الاتفاقية للمستخدم (`~/.failproofai/policies/`، أبجدياً)
 
 ---
 
-## واجهة برمجية التطبيقات
+## API
 
 ### الاستيراد
 
@@ -100,7 +99,7 @@ import { customPolicies, allow, deny, instruct } from "failproofai";
 
 ### `customPolicies.add(hook)`
 
-تسجيل سياسة. اتصل بها عدة مرات حسب الحاجة لسياسات متعددة في نفس الملف.
+تسجيل سياسة. استدعِ هذا عدة مرات حسب الحاجة لسياسات متعددة في نفس الملف.
 
 ```ts
 customPolicies.add({
@@ -116,30 +115,29 @@ customPolicies.add({
 | الدالة | التأثير | استخدم عندما |
 |----------|--------|----------|
 | `allow()` | السماح بالعملية بصمت | الإجراء آمن، لا توجد رسالة مطلوبة |
-| `deny(message)` | حظر العملية | يجب ألا يتخذ الوكيل هذا الإجراء |
-| `instruct(message)` | إضافة سياق دون حظر | إعطاء الوكيل سياق إضافي للبقاء على المسار |
+| `deny(message)` | منع العملية | لا يجب أن يقوم الوكيل بهذا الإجراء |
+| `instruct(message)` | إضافة سياق بدون حجب | أعط الوكيل سياق إضافي للبقاء على المسار |
 
-`deny(message)` - تظهر الرسالة إلى Claude بسابقة `"Blocked by failproofai:"`. يقطع `deny` واحد كل تقييم آخر.
+`deny(message)` - تظهر الرسالة لـ Claude مع البادئة `"Blocked by failproofai:"`. يؤدي `deny` واحد إلى اختصار جميع التقييمات الإضافية.
 
-`instruct(message)` - يتم إلحاق الرسالة بسياق Claude لاستدعاء الأداة الحالي. يتم تجميع جميع رسائل `instruct` وتسليمها معاً.
+`instruct(message)` - يتم إلحاق الرسالة بسياق Claude للاستدعاء الحالي للأداة. يتم تجميع جميع رسائل `instruct` وتسليمها معاً.
 
 <Tip>
-يمكنك إلحاق إرشادات إضافية بأي رسالة `deny` أو `instruct` بإضافة حقل `hint` في `policyParams` - لا حاجة لتغيير الرمز. يعمل هذا أيضاً للسياسات المخصصة (`custom/`)، واتفاقية المشروع (`.failproofai-project/`)، واتفاقية المستخدم (`.failproofai-user/`). انظر [التكوين → hint](/ar/configuration#hint-cross-cutting) للتفاصيل.
+يمكنك إلحاق إرشادات إضافية بأي رسالة `deny` أو `instruct` بإضافة حقل `hint` في `policyParams` — لا يلزم تغيير الكود. يعمل هذا أيضاً مع السياسات المخصصة (`custom/`) وسياسات اتفاقية المشروع (`.failproofai-project/`) وسياسات اتفاقية المستخدم (`.failproofai-user/`). راجع [التكوين → hint](/ar/configuration#hint-cross-cutting) للتفاصيل.
 </Tip>
 
 ### رسائل السماح المعلوماتية
 
-
-`allow(message)` يسمح بالعملية **و** يرسل رسالة معلومات مرة أخرى إلى Claude. يتم تسليم الرسالة كـ `additionalContext` في استجابة stdout لمعالج الخطاف - نفس الآلية المستخدمة من قبل `instruct`، لكن مختلفة من الناحية الدلالية: إنها تحديث حالة وليست تحذير.
+`allow(message)` يسمح بالعملية **و** يرسل رسالة معلوماتية مرة أخرى إلى Claude. يتم تسليم الرسالة كـ `additionalContext` في استجابة stdout معالج الخطاف — نفس الآلية المستخدمة بواسطة `instruct`، لكن بمعنى مختلف: إنها تحديث الحالة، وليست تحذيراً.
 
 | الدالة | التأثير | استخدم عندما |
 |----------|--------|----------|
-| `allow(message)` | السماح وإرسال السياق إلى Claude | تأكيد نجاح الفحص، أو شرح سبب تخطي الفحص |
+| `allow(message)` | السماح وإرسال السياق إلى Claude | تأكيد اجتياز الفحص، أو شرح سبب تخطي الفحص |
 
 حالات الاستخدام:
-- **تأكيدات الحالة:** `allow("All CI checks passed.")` - يخبر Claude أن كل شيء أخضر
-- **شروحات fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` - يخبر Claude سبب تخطي الفحص حتى يكون لديه السياق الكامل
-- **تراكم الرسائل المتعددة:** إذا أرجعت عدة سياسات `allow(message)`، يتم ربط جميع الرسائل بخطوط جديدة وتسليمها معاً
+- **تأكيدات الحالة:** `allow("All CI checks passed.")` — يخبر Claude بأن كل شيء أخضر
+- **شرح الفتح الفاشل:** `allow("GitHub CLI not installed, skipping CI check.")` — يخبر Claude لماذا تم تخطي الفحص حتى يكون لديه سياق كامل
+- **تراكم رسائل متعددة:** إذا أرجعت عدة سياسات `allow(message)`، يتم ربط جميع الرسائل بأسطر جديدة وتسليمها معاً
 
 ```js
 customPolicies.add({
@@ -165,25 +163,25 @@ customPolicies.add({
 | `eventType` | `string` | `"PreToolUse"`، `"PostToolUse"`، `"Notification"`، `"Stop"` |
 | `toolName` | `string \| undefined` | الأداة التي يتم استدعاؤها (مثل `"Bash"`، `"Write"`، `"Read"`) |
 | `toolInput` | `Record<string, unknown> \| undefined` | معاملات إدخال الأداة |
-| `payload` | `Record<string, unknown>` | حمل الحدث الخام الكامل من Claude Code |
+| `payload` | `Record<string, unknown>` | حمل الحدث الكامل الخام من Claude Code |
 | `session` | `SessionMetadata \| undefined` | سياق الجلسة (انظر أدناه) |
 
 ### حقول `SessionMetadata`
 
 | الحقل | النوع | الوصف |
 |-------|------|-------------|
-| `sessionId` | `string` | معرّف جلسة Claude Code |
+| `sessionId` | `string` | معرف جلسة Claude Code |
 | `cwd` | `string` | دليل العمل لجلسة Claude Code |
-| `transcriptPath` | `string` | المسار إلى ملف النسخة JSONL الخاص بالجلسة |
+| `transcriptPath` | `string` | المسار إلى ملف النسخة المكتوبة JSONL للجلسة |
 
 ### أنواع الأحداث
 
-| الحدث | متى يتم تشغيله | محتويات `toolInput` |
-|-------|--------------|----------------------|
+| الحدث | متى يطلق | محتويات `toolInput` |
+|------|--------------|----------------------|
 | `PreToolUse` | قبل تشغيل Claude لأداة | إدخال الأداة (مثل `{ command: "..." }` لـ Bash) |
 | `PostToolUse` | بعد اكتمال الأداة | إدخال الأداة + `tool_result` (الإخراج) |
-| `Notification` | عندما يرسل Claude إشعاراً | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - يجب أن تعيد الخطافات دائماً `allow()`، فلا يمكنها حظر الإشعارات |
-| `Stop` | عند انتهاء جلسة Claude | فارغة |
+| `Notification` | عندما يرسل Claude إشعاراً | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - يجب أن تعيد الخطافات دائماً `allow()`، لا يمكنها حجب الإشعارات |
+| `Stop` | عند انتهاء جلسة Claude | فارغ |
 
 ---
 
@@ -193,18 +191,18 @@ customPolicies.add({
 
 1. السياسات المدمجة (بترتيب التعريف)
 2. السياسات المخصصة الصريحة من `customPoliciesPath` (بترتيب `.add()`)
-3. سياسات الاتفاقية من `.failproofai/policies/` للمشروع (ملفات أبجدياً، ترتيب `.add()` بداخلها)
-4. سياسات الاتفاقية من `~/.failproofai/policies/` للمستخدم (ملفات أبجدياً، ترتيب `.add()` بداخلها)
+3. سياسات الاتفاقية من مشروع `.failproofai/policies/` (الملفات أبجدياً، ترتيب `.add()` بداخلها)
+4. سياسات الاتفاقية من مستخدم `~/.failproofai/policies/` (الملفات أبجدياً، ترتيب `.add()` بداخلها)
 
 <Note>
-يقطع أول `deny` جميع السياسات اللاحقة. يتم تجميع جميع رسائل `instruct` وتسليمها معاً.
+يؤدي أول `deny` إلى اختصار جميع السياسات اللاحقة. يتم تجميع جميع رسائل `instruct` وتسليمها معاً.
 </Note>
 
 ---
 
 ## الواردات المتعدية
 
-يمكن لملفات السياسة المخصصة استيراد الوحدات المحلية باستخدام المسارات النسبية:
+يمكن لملفات السياسات المخصصة استيراد الوحدات المحلية باستخدام المسارات النسبية:
 
 ```js
 // my-policies.js
@@ -221,13 +219,13 @@ customPolicies.add({
 });
 ```
 
-يتم حل جميع الواردات النسبية الممكنة من ملف الإدخال. يتم تطبيق هذا بإعادة كتابة واردات `from "failproofai"` إلى مسار dist الفعلي وإنشاء ملفات `.mjs` مؤقتة لضمان توافق ESM.
+يتم حل جميع الواردات النسبية التي يمكن الوصول إليها من ملف الإدخال. يتم تنفيذ هذا بإعادة كتابة استيراد `from "failproofai"` إلى مسار dist الفعلي وإنشاء ملفات `.mjs` مؤقتة لضمان توافق ESM.
 
 ---
 
 ## تصفية نوع الحدث
 
-استخدم `match.events` لتحديد متى يتم تشغيل سياسة:
+استخدم `match.events` لتحديد متى تطلق السياسة:
 
 ```js
 customPolicies.add({
@@ -241,26 +239,26 @@ customPolicies.add({
 });
 ```
 
-حذف `match` بالكامل للتشغيل في كل نوع حدث.
+احذف `match` تماماً لتطلق على كل نوع حدث.
 
 ---
 
 ## معالجة الأخطاء وأوضاع الفشل
 
-السياسات المخصصة هي **fail-open**: الأخطاء لا تحظر السياسات المدمجة أو تعطل معالج الخطاف.
+السياسات المخصصة **تفتح الفشل**: لا تحجب الأخطاء أبداً السياسات المدمجة أو تحطم معالج الخطاف.
 
 | الفشل | السلوك |
 |---------|----------|
-| `customPoliciesPath` لم تُعيّن | لا تعمل السياسات المخصصة الصريحة؛ سياسات الاتفاقية والمدمجة تستمر بشكل طبيعي |
-| ملف غير موجود | تم تسجيل تحذير في `~/.failproofai/hook.log`؛ المدمجة تستمر |
-| خطأ في الصيغة/الاستيراد (صريح) | تم تسجيل الخطأ في `~/.failproofai/hook.log`؛ سياسات مخصصة صريحة تم تخطيها |
-| خطأ في الصيغة/الاستيراد (اتفاقية) | تم تسجيل الخطأ؛ هذا الملف تم تخطيه، ملفات اتفاقية أخرى لا تزال تحمل |
-| `fn` رمي في وقت التشغيل | تم تسجيل الخطأ؛ تم التعامل مع الخطاف كـ `allow`؛ الخطافات الأخرى تستمر |
-| `fn` يستغرق أكثر من 10 ثوان | تم تسجيل المهلة الزمنية؛ تم التعامل معها كـ `allow` |
+| `customPoliciesPath` لم يتم تعيينه | لا تعمل سياسات مخصصة صريحة؛ تستمر السياسات والمدمجات الاتفاقية بشكل طبيعي |
+| لم يتم العثور على الملف | تحذير مسجل في `~/.failproofai/hook.log`؛ تستمر المدمجات |
+| خطأ الصيغة/الاستيراد (صريح) | خطأ مسجل في `~/.failproofai/hook.log`؛ تم تخطي السياسات المخصصة الصريحة |
+| خطأ الصيغة/الاستيراد (الاتفاقية) | خطأ مسجل؛ هذا الملف مخطي، لكن ملفات الاتفاقية الأخرى تحمل لا تزال |
+| `fn` يرمي في وقت التشغيل | خطأ مسجل؛ يتم التعامل مع الخطاف كـ `allow`؛ تستمر الخطافات الأخرى |
+| `fn` يستغرق أطول من 10 ثوانٍ | انتهاء المهلة الزمنية المسجلة؛ يتم التعامل معها كـ `allow` |
 | مجلد الاتفاقية مفقود | لا تعمل سياسات الاتفاقية؛ لا خطأ |
 
 <Tip>
-لتصحيح أخطاء السياسة المخصصة، راقب ملف السجل:
+لتصحيح أخطاء السياسات المخصصة، شاهد ملف السجل:
 
 ```bash
 tail -f ~/.failproofai/hook.log
@@ -326,14 +324,14 @@ export { customPolicies };
 
 ## أمثلة
 
-يحتوي دليل `examples/` على ملفات السياسات الجاهزة للتشغيل:
+يحتوي مجلد `examples/` على ملفات السياسات الجاهزة للتشغيل:
 
-| الملف | المحتوى |
+| الملف | المحتويات |
 |------|----------|
-| `examples/policies-basic.js` | خمس سياسات للمبتدئين تغطي أوضاع فشل الوكيل الشائعة |
-| `examples/policies-advanced/index.js` | أنماط متقدمة: واردات متعدية، استدعاءات غير متزامنة، تنقية الإخراج، وخطافات نهاية الجلسة |
-| `examples/convention-policies/security-policies.mjs` | سياسات الأمان المبنية على الاتفاقية (حظر كتابة .env، منع إعادة كتابة سجل git) |
-| `examples/convention-policies/workflow-policies.mjs` | سياسات سير العمل المبنية على الاتفاقية (تذكيرات الاختبار، ملفات التدقيق) |
+| `examples/policies-basic.js` | خمس سياسات للمبتدئين تغطي أنماط أعطال الوكيل الشائعة |
+| `examples/policies-advanced/index.js` | أنماط متقدمة: واردات متعدية، استدعاءات غير متزامنة، كشط الإخراج، خطافات نهاية الجلسة |
+| `examples/convention-policies/security-policies.mjs` | سياسات الأمان القائمة على الاتفاقية (منع كتابات .env، منع إعادة كتابة سجل git) |
+| `examples/convention-policies/workflow-policies.mjs` | سياسات سير العمل القائمة على الاتفاقية (تذكيرات الاختبار، ملفات الكتابة بالتدقيق) |
 
 ### استخدام أمثلة الملفات الصريحة
 
@@ -341,7 +339,7 @@ export { customPolicies };
 failproofai policies --install --custom ./examples/policies-basic.js
 ```
 
-### استخدام أمثلة الاتفاقية
+### استخدام أمثلة قائمة على الاتفاقية
 
 ```bash
 # Copy to project level
@@ -353,4 +351,4 @@ mkdir -p ~/.failproofai/policies
 cp examples/convention-policies/*.mjs ~/.failproofai/policies/
 ```
 
-لا حاجة لأمر التثبيت - يتم اختيار الملفات تلقائياً عند حدث الخطاف التالي.
+لا يلزم أمر التثبيت — يتم التقاط الملفات تلقائياً في حدث الخطاف التالي.

package/.next/standalone/docs/built-in-policies.mdx

@@ -21,6 +21,7 @@ Policies are grouped into categories:
 | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse |
 | [Database](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse |
 | [Warnings](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse |
+| [Package managers](#package-managers) | prefer-package-manager | PreToolUse |
 | [Workflow](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-ci-green-before-stop | Stop |
 
 - **`block-`** — stop the agent from proceeding.
@@ -436,6 +437,42 @@ No parameters.
 
 ---
 
+## Package managers
+
+Enforce which package managers the agent is allowed to use.
+
+### `prefer-package-manager`
+
+**Event:** PreToolUse (Bash)  
+**Default:** Disabled. When enabled, blocks any package manager command not in the `allowed` list and tells Claude to rewrite the command using an allowed manager.
+
+Detects: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `allowed` | string[] | `[]` | Allowed package manager names. Any detected manager not in this list is blocked. When empty, the policy is a no-op. |
+| `blocked` | string[] | `[]` | Additional manager names to block beyond the built-in list (e.g. `['pdm', 'pipx']`). |
+
+The built-in block list covers: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Use `blocked` to append managers not in this list.
+
+**Example configuration:**
+
+```json
+{
+  "enabledPolicies": ["prefer-package-manager"],
+  "policyParams": {
+    "prefer-package-manager": {
+      "allowed": ["uv", "bun"],
+      "blocked": ["pdm", "pipx"]
+    }
+  }
+}
+```
+
+With this config, `pip install flask` and `pdm install flask` are both denied with a message telling Claude to use `uv` or `bun` instead. Commands like `uv pip install flask` are allowed because `uv` is in the allowlist and is checked first.
+
+---
+
 ## AI behavior
 
 Detect when agents get stuck or behave unexpectedly.

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

@@ -60,7 +60,7 @@ Drop `*policies.{js,mjs,ts}` files into `.failproofai/policies/` and they're aut
 - Works alongside explicit `--custom` and built-in policies
 
 <Tip>
-Convention policies are the easiest way to share policies across a team. Commit `.failproofai/policies/` to git and every team member gets them automatically.
+Convention policies are the easiest way to build a quality standard for your org. Commit `.failproofai/policies/` to git and every team member gets the same rules automatically — no per-developer setup needed. As your team discovers new failure modes, add a policy and push. Over time these become a living quality standard that keeps improving with every contribution.
 </Tip>
 
 ### Option 2: Explicit file path