failproofai 0.0.2-beta.8 → 0.0.2-beta.9

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

@@ -0,0 +1,254 @@
+---
+---
+title: أمثلة
+description: "كيفية إعداد hooks لـ Claude Code و Agents SDK"
+icon: book-open
+---
+
+أمثلة جاهزة للاستخدام للسيناريوهات الشائعة. يوضح كل منها كيفية التثبيت وما يجب توقعه.
+
+---
+
+## إعداد hooks لـ Claude Code
+
+يتكامل Failproof AI مع Claude Code عبر [نظام hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) الخاص به. عند تشغيل `failproofai policies --install`، يسجل أوامر hook في ملف `settings.json` الخاص بـ Claude Code والتي تعمل على كل استدعاء أداة.
+
+<Steps>
+  <Step title="تثبيت failproofai">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="تفعيل جميع السياسات المدمجة">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="التحقق من تسجيل hooks">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    يجب أن تشاهد إدخالات hook لأحداث `PreToolUse` و `PostToolUse` و `Notification` و `Stop`.
+  </Step>
+  <Step title="تشغيل Claude Code">
+    ```bash
+    claude
+    ```
+
+    تعمل السياسات الآن تلقائياً على كل استدعاء أداة. حاول أن تطلب من Claude تشغيل `sudo rm -rf /` - سيتم حظره.
+  </Step>
+</Steps>
+
+---
+
+## إعداد hooks لـ Agents SDK
+
+إذا كنت تبني باستخدام [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk)، يمكنك استخدام نفس نظام hooks بشكل برمجي.
+
+<Steps>
+  <Step title="تثبيت failproofai في مشروعك">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="تكوين hooks في وكيلك">
+    مرر أوامر hook عند إنشاء عملية الوكيل الخاصة بك. تعمل hooks بنفس الطريقة كما هي في Claude Code - عبر JSON على stdin/stdout:
+
+    ```bash
+    failproofai --hook PreToolUse   # يتم استدعاؤها قبل كل أداة
+    failproofai --hook PostToolUse  # يتم استدعاؤها بعد كل أداة
+    ```
+  </Step>
+  <Step title="اكتب سياسة مخصصة لوكيلك">
+    ```javascript
+    import { customPolicies, allow, deny } from "failproofai";
+
+    customPolicies.add({
+      name: "limit-to-project-dir",
+      description: "Keep the agent inside the project directory",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        const path = String(ctx.toolInput?.file_path ?? "");
+        if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
+          return deny("Agent is restricted to the project directory");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="تثبيت السياسة المخصصة">
+    ```bash
+    failproofai policies --install --custom ./my-agent-policies.js
+    ```
+  </Step>
+</Steps>
+
+---
+
+## حظر الأوامر المدمرة
+
+الإعداد الأكثر شيوعاً - منع الوكلاء من إلحاق أضرار لا يمكن إصلاحها.
+
+```bash
+failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
+```
+
+ما الذي يفعله:
+- `block-sudo` - يحظر جميع أوامر `sudo`
+- `block-rm-rf` - يحظر حذف الملفات بشكل متكرر
+- `block-force-push` - يحظر `git push --force`
+- `block-curl-pipe-sh` - يحظر نقل البرامج النصية البعيدة إلى shell
+
+---
+
+## منع تسرب الأسرار
+
+منع الوكلاء من رؤية أو تسريب بيانات الاعتماد في مخرجات الأداة.
+
+```bash
+failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
+```
+
+تعمل هذه على `PostToolUse` - بعد تشغيل أداة، تقوم بتنقية المخرجات قبل أن يراها الوكيل.
+
+---
+
+## الحصول على تنبيهات Slack عندما يحتاج الوكلاء إلى الاهتمام
+
+استخدم hook الإشعارات لإعادة توجيه تنبيهات السكون إلى Slack.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "slack-on-idle",
+  description: "Alert Slack when the agent is waiting for input",
+  match: { events: ["Notification"] },
+  fn: async (ctx) => {
+    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
+    if (!webhookUrl) return allow();
+
+    const message = String(ctx.payload?.message ?? "Agent is waiting");
+    const project = ctx.session?.cwd ?? "unknown";
+
+    try {
+      await fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          text: `*${message}*\nProject: \`${project}\``,
+        }),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch {
+      // never block the agent if Slack is unreachable
+    }
+
+    return allow();
+  },
+});
+```
+
+ثبته:
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
+```
+
+---
+
+## اجعل الوكلاء على فرع
+
+منع الوكلاء من تبديل الفروع أو الدفع إلى الفروع المحمية.
+
+```javascript
+import { customPolicies, allow, deny } from "failproofai";
+
+customPolicies.add({
+  name: "stay-on-branch",
+  description: "Prevent the agent from checking out other branches",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
+      return deny("Stay on the current branch. Create a new branch with -b if needed.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## طلب اختبارات قبل الالتزام
+
+ذكّر الوكلاء بتشغيل الاختبارات قبل الالتزام.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "test-before-commit",
+  description: "Remind the agent to run tests before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## قفل مستودع الإنتاج
+
+التزم بتكوين على مستوى المشروع بحيث يحصل كل مطور في فريقك على نفس السياسات.
+
+أنشئ `.failproofai/policies-config.json` في مستودعك:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-force-push",
+    "block-push-master",
+    "block-env-files",
+    "sanitize-api-keys",
+    "sanitize-jwt"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "production"]
+    }
+  }
+}
+```
+
+ثم التزم به:
+
+```bash
+git add .failproofai/policies-config.json
+git commit -m "Add failproofai team policies"
+```
+
+سيلتقط كل عضو في الفريق لديه failproofai مثبتاً هذه القواعد تلقائياً.
+
+---
+
+## المزيد من الأمثلة
+
+يحتوي دليل [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) في المستودع على:
+
+| الملف | ما يعرضه |
+|------|----------|
+| `policies-basic.js` | السياسات الأساسية - منع عمليات الكتابة في الإنتاج والدفع القسري والبرامج النصية المنقولة |
+| `policies-notification.js` | تنبيهات Slack لإشعارات السكون ونهاية الجلسة |
+| `policies-advanced/index.js` | الاستيرادات المتعددة والخطافات غير المتزامنة وتنقية مخرجات PostToolUse ومعالجة حدث Stop |

package/.next/standalone/docs/ar/for-agents.mdx

@@ -0,0 +1,39 @@
+---
+---
+title: "للوكلاء"
+description: "أضف معرفة Failproof AI إلى وكيلك البرمجي بأمر واحد. يعمل مع Claude Code و Cursor و Windsurf وغيرها."
+---
+
+أضف مرجع Failproof AI الكامل إلى وكيلك البرمجي بأمر واحد. يعمل مع Claude Code و Cursor و Windsurf وأي وكيل آخر يدعم المهارات.
+
+```bash
+npx skills add https://docs.befailproof.ai
+```
+
+يكتشف `npx skills` الوكلاء المثبتة لديك ويضيف المهارة بالصيغة الصحيحة لكل واحد منها تلقائياً.
+
+## ما تغطيه المهارة
+
+| المجال | ما يشمل |
+|------|----------------|
+| السياسات | أسماء السياسات المدمجة وأنواع الأحداث والمعاملات والتفعيل/التعطيل |
+| السياسات المخصصة | `customPolicies.add()`وفلاتر المطابقة و API `allow`/`deny`/`instruct` |
+| كائن السياق | `ctx.eventType` و `ctx.toolName` و `ctx.toolInput` و `ctx.session` |
+| الإعدادات | بنية `policies-config.json` ودمج النطاق و `policyParams` |
+| واجهة سطر الأوامر | `failproofai policies --install` و `--uninstall` و `--custom` والنطاقات |
+| لوحة التحكم | عارض الجلسات ونشاط السياسة والمتغيرات البيئية |
+| البنية المعمارية | تدفق معالج الخطاف وأكواد الخروج و عقد stdin/stdout |
+
+## هل المهارة كاملة؟
+
+يولد Mintlify `llms.txt` من جميع الصفحات في التنقل. توثيقات Failproof AI تغطي الواجهة البرمجية الكاملة - كل سياسة وخيار ومثال مضمن. إذا وجدت شيء مفقود، فالمصدر موجود في `https://docs.befailproof.ai/llms-full.txt`.
+
+للحصول على سياق موجه، قم بالربط مباشرة إلى صفحة محددة:
+
+```bash
+# فقط API السياسات المخصصة
+npx skills add https://docs.befailproof.ai/custom-policies
+
+# فقط السياسات المدمجة
+npx skills add https://docs.befailproof.ai/built-in-policies
+```

package/.next/standalone/docs/ar/getting-started.mdx

@@ -0,0 +1,134 @@
+---
+title: البدء السريع
+description: "ثبّت failproofai، فعّل السياسات، واترك وكلاءك يعملون بموثوقية"
+icon: rocket
+---
+
+## المتطلبات
+
+- **Node.js** >= 20.9.0
+- **Bun** >= 1.3.0 (اختياري - مطلوب فقط للبناء من المصدر)
+
+---
+
+## التثبيت
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+---
+
+## البدء السريع
+
+<Steps>
+  <Step title="تفعيل السياسات">
+    السياسات هي قواعد تعمل قبل وبعد كل استدعاء أداة من الوكيل. فهي تقبض على الأوامر المدمرة، تسرب الأسرار، وأوجه الفشل الأخرى قبل أن تسبب الضرر.
+
+    ```bash
+    failproofai policies --install
+    ```
+
+    يكتب هذا مدخلات hook في `settings.json` الخاص بـ Claude Code. يمكنك أيضاً التثبيت لمشروع واحد أو اختيار سياسات محددة:
+
+    ```bash
+    failproofai policies --install --scope project
+    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
+    ```
+  </Step>
+  <Step title="التحقق">
+    ```bash
+    failproofai policies
+    ```
+
+    يعرض كل سياسة، ما إذا كانت مفعلة، وأي معاملات مكونة.
+  </Step>
+  <Step title="تشغيل لوحة المعلومات">
+    ```bash
+    failproofai
+    ```
+
+    يفتح لوحة معلومات محلية على `http://localhost:8020` حيث يمكنك تصفح الجلسات، فحص استدعاءات الأدوات، وإدارة السياسات.
+  </Step>
+  <Step title="تشغيل وكيلك">
+    شغّل Claude Code كالمعتاد. إذا حاول الوكيل شيئاً محفوفاً بالمخاطر، فإن failproofai يقاطعه تلقائياً. اتركه يعمل دون مراقبة وراجع ما حدث في لوحة المعلومات.
+  </Step>
+</Steps>
+
+---
+
+## كيفية عمل السياسات
+
+في كل مرة يشغل فيها الوكيل أداة، يستدعي Claude Code failproofai كعملية فرعية:
+
+```text
+Claude Code  →  failproofai --hook PreToolUse  →  قراءة JSON من stdin
+                                                 تقييم السياسات
+                                                 كتابة القرار إلى stdout
+```
+
+كل سياسة ترجع أحد ثلاثة قرارات:
+
+- **allow** - يستمر الوكيل بشكل طبيعي
+- **deny** - يتم حظر الإجراء، ويُخبر الوكيل عن السبب
+- **instruct** - يُضاف سياق إضافي إلى فوری الوكيل
+
+<Note>
+تعمل السياسات في عمليتك المحلية. لا يتم إرسال أي شيء إلى خدمة بعيدة.
+</Note>
+
+---
+
+## تخزين البيانات
+
+جميع الإعدادات والسجلات تبقى على جهازك:
+
+| المسار | ما يخزنه |
+|------|----------------|
+| `~/.failproofai/policies-config.json` | إعدادات السياسة العامة |
+| `~/.failproofai/hook-activity.jsonl` | سجل تنفيذ Hook |
+| `~/.failproofai/hook.log` | سجل تصحيح الأخطاء لأخطاء hook المخصصة |
+| `.failproofai/policies-config.json` | إعدادات لكل مشروع (مرتكبة) |
+| `.failproofai/policies-config.local.json` | التجاوزات الشخصية (مستثناة من git) |
+
+---
+
+## الإلغاء
+
+```bash
+failproofai policies --uninstall
+```
+
+يزيل مدخلات hook من `~/.claude/settings.json`. يتم الاحتفاظ بملفات الإعدادات في `~/.failproofai/`.
+
+---
+
+## الخطوات التالية
+
+<CardGroup cols={2}>
+
+<Card title="الإعدادات" icon="gear" href="/ar/configuration">
+  النطاقات وصيغة ملف الإعدادات
+</Card>
+
+<Card title="السياسات المدمجة" icon="shield" href="/ar/built-in-policies">
+  جميع 26 سياسة مع المعاملات
+</Card>
+
+<Card title="السياسات المخصصة" icon="code" href="/ar/custom-policies">
+  اكتب سياساتك الخاصة بلغة JavaScript
+</Card>
+
+<Card title="مراقب الوكيل" icon="chart-line" href="/ar/dashboard">
+  راقب الجلسات واستعرض نشاط السياسة
+</Card>
+
+</CardGroup>

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

@@ -0,0 +1,58 @@
+---
+---
+title: Failproof AI
+description: "إدارة الخطافات والسياسات التي تحافظ على موثوقية وكالاتك الذكية وتشغيلها بشكل مستقل"
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+خطافات وسياسات تحافظ على موثوقية وكلاءك الذكيين وتشغيلهم بشكل مستقل - لـ **Claude Code** و **Agents SDK**.
+
+تفشل الوكلاء الذكيون بطرق متوقعة. فهم يقومون بتشغيل أوامر مدمرة، ويسربون الأسرار، ويبتعدون عن المهمة المطلوبة، ويعلقون في حلقات، أو يدفعون مباشرة إلى الفرع الرئيسي. إذا تركت دون مراقبة، فإن الأخطاء الصغيرة تتراكم وتسبب مشاكل كبيرة.
+
+يحل Failproof AI هذه المشكلة باستخدام **السياسات** - قواعد تتكامل مع كل استدعاء أداة للوكيل ويمكنها **اكتشاف الأخطاء** و**تخفيفها** (الحجب والتعليمات والتنظيف) و**تنبيهك** عندما تحتاج شيء ما إلى الانتباه. لوحة معلومات محلية تتيح لك مراجعة كل شيء بعد الانتهاء.
+
+كل شيء يعمل محليًا. لا تغادر البيانات جهازك.
+
+## ابدأ الآن
+
+<CardGroup cols={2}>
+
+<Card title="26 سياسة مدمجة" icon="shield" href="/ar/built-in-policies">
+  احجب الأوامر المدمرة، ومنع تسرب الأسرار، وأبقِ الوكلاء داخل حدود المشروع، والمزيد - خارج الصندوق.
+</Card>
+
+<Card title="سياسات مخصصة" icon="code" href="/ar/custom-policies">
+  اكتب قواعدك الخاصة في JavaScript باستخدام واجهة برمجية بسيطة للسماح أو الرفض أو التعليمات.
+</Card>
+
+<Card title="مراقب الوكيل" icon="chart-line" href="/ar/dashboard">
+  انظر إلى ما فعله وكلاؤك أثناء غيابك. استعرض الجلسات، وفحص استدعاءات الأدوات، وراجع مكان تفعيل السياسات.
+</Card>
+
+<Card title="تكوين سهل" icon="gear" href="/ar/configuration">
+  ضبط أي سياسة بدون كود. قم بتعيين قوائم السماح والفروع المحمية أو الحدود لكل مشروع أو عام.
+</Card>
+
+</CardGroup>
+
+## البدء السريع
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # enable policies
+failproofai                      # launch the dashboard
+```
+
+انظر إلى دليل [البدء السريع](/ar/getting-started) للحصول على الشرح الكامل.

package/.next/standalone/docs/ar/package-aliases.mdx

@@ -0,0 +1,82 @@
+---
+title: اسماء الحزم البديلة
+description: "الأسماء البديلة المسجلة لمنع الأخطاء الإملائية وكيفية عملها"
+icon: copy
+---
+
+## الحزمة الرسمية
+
+حزمة npm الأساسية هي **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# أو
+bun add -g failproofai
+```
+
+---
+
+## لماذا نملك أسماء البدائل
+
+تسجيل النطاقات المشابهة (Typosquatting) هو هجوم شائع على سلسلة التوريد حيث يقوم عامل خبيث بتسجيل اسم حزمة يختلف بضغطة زر واحدة عن حزمة شهيرة. المستخدمون الذين يخطئون في كتابة أمر التثبيت ينتهي بهم الحال لتشغيل كود يتحكم به المهاجم مع وصول كامل للنظام - وهذا هو النوع من التهديدات التي تم تصميم Failproof AI للدفاع ضده.
+
+لإزالة هذا السطح الهجومي، **نملك مسبقاً جميع الأخطاء الإملائية الشائعة والمتغيرات الصيغية** لـ `failproofai` على npm. لا يمكن لأي طرف ثالث تسجيل أي من هذه الأسماء. كل واحد منها هو وكيل بسيط يثبت الحزمة الحقيقية ويفوّض إليها.
+
+---
+
+## الأسماء البديلة المسجلة
+
+**متغيرات الصيغة** - طرق مختلفة لكتابة "failproof ai":
+
+| الحزمة | الحالة |
+|---------|--------|
+| `failproof` | ✅ منشورة |
+| `failproof-ai` | ⏳ قيد انتظار دعم npm |
+| `fail-proof-ai` | ⏳ قيد انتظار دعم npm |
+| `failproof_ai` | ⏳ قيد انتظار دعم npm |
+| `fail_proof_ai` | ⏳ قيد انتظار دعم npm |
+| `fail-proofai` | ⏳ قيد انتظار دعم npm |
+
+**أخطاء `failprof*`** - حرف `o` ناقص من "proof":
+
+| الحزمة | الحالة |
+|---------|--------|
+| `failprof` | ✅ منشورة |
+| `failprof-ai` | ✅ منشورة |
+| `failprofai` | ⏳ قيد انتظار دعم npm |
+| `fail-prof-ai` | ⏳ قيد انتظار دعم npm |
+| `failprof_ai` | ⏳ قيد انتظار دعم npm |
+
+**أخطاء `faliproof*`** - الأحرف `a` و `i` معكوسة:
+
+| الحزمة | الحالة |
+|---------|--------|
+| `faliproof` | ✅ منشورة |
+| `faliproof-ai` | ✅ منشورة |
+| `faliproofai` | ⏳ قيد انتظار دعم npm |
+
+> **لماذا قيد الانتظار؟** سياسة منع البريد العشوائي في npm تحظر الأسماء التي تتطابق مع حزمة موجودة بعد إزالة الترقيم وإجراء فحوصات التشابه. لقد تواصلنا مع فريق دعم npm لحجز هذه الأسماء لأغراض منع التسجيل غير المشروع. سيتم تفعيلها بمجرد الموافقة عليها.
+
+يمكنك التحقق من أن أي اسم بديل منشور مملوك لنا:
+
+```bash
+npm info failproof
+# ابحث عن: "ExosphereHost Inc." في حقل المشرفين
+```
+
+---
+
+## كيفية عمل الأسماء البديلة
+
+كل حزمة بديلة:
+
+1. تضع `failproofai` كتبعية - بحيث تعمل الحزمة الحقيقية (بما في ذلك خطاف `postinstall` الخاص بها) عند التثبيت
+2. تعرض ملف تنفيذي يطابق اسمها الخاص (مثل `failprof-ai`) يفوّض جميع المعاملات إلى ملف `failproofai` التنفيذي
+
+الوكيل هو نص Node بسيط من سطرين؛ لا توجد منطقية، لا استدعاءات شبكية، ولا جمع بيانات بخلاف ما تقوم به `failproofai` بنفسها.
+
+---
+
+## إذا وجدت اسماً فاتنا
+
+افتح مشكلة على [exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues) وسنقوم بتسجيلها.