failproofai 1.0.1-beta.1 → 1.0.1

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

@@ -0,0 +1,199 @@
+---
+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 في CLIs الوكيل المثبتة لديك (ملف `~/.claude/settings.json` الخاص بـ Claude Code، و `~/.codex/hooks.json` الخاص بـ OpenAI Codex، و `~/.copilot/hooks/failproofai.json` الخاص بـ GitHub Copilot CLI، و `~/.cursor/hooks.json` الخاص بـ Cursor Agent، و plugin shim المُنتج بـ `~/.config/opencode/plugins/failproofai.mjs` لـ OpenCode مع إدخال تسجيل في مصفوفة `plugin` في `~/.config/opencode/opencode.json`، و `~/.pi/agent/settings.json` الخاص بـ Pi، و `~/.hermes/config.yaml` الخاص بـ Hermes، و `~/.openclaw/openclaw.json` الخاص بـ OpenClaw، و `~/.factory/hooks.json` الخاص بـ Factory Droid، و `~/.config/devin/config.json` الخاص بـ Devin CLI، و `~/.gemini/config/hooks.json` الخاص بـ Antigravity CLI، أو دليل plugin المكتشف تلقائياً لـ Goose في `~/.agents/plugins/failproofai/hooks/hooks.json`). عند وجود أكثر من واحد ستُطالب؛ مرر `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (أي مجموعة فرعية) لتخطي الرسالة.
+
+    GitHub Copilot CLI و Cursor Agent و OpenCode و Pi مدعومة بـ **beta** — ثبّت باستخدام `--cli copilot` أو `--cli cursor` أو `--cli opencode` أو `--cli pi`. Hermes (hermes-agent، بوابة Slack/Telegram) يثبّت برطاق مستخدم مع `--cli hermes` وهو **أيضاً** مصدر تدقيق غير متصل. OpenClaw (بوابة openclaw، مساعد متعدد القنوات مستضاف ذاتياً) يثبّت برطاق مستخدم مع `--cli openclaw` — الإنفاذ يعمل من خلال hooks plugin معالجته (`before_agent_finalize` هو بوابة نهاية دور حقيقية، لذا builtins `require-*-before-stop` ينفذ) — وهو **أيضاً** مصدر تدقيق غير متصل. Factory Droid (`droid`) يثبّت مع `--cli factory` (رطاق مستخدم + مشروع) وهو **أيضاً** مصدر تدقيق غير متصل. Devin CLI (`devin`، Cognition) يثبّت مع `--cli devin` (رطاق مستخدم + مشروع) وهو **أيضاً** مصدر تدقيق غير متصل. Antigravity CLI (`agy`) يثبّت مع `--cli antigravity` (رطاق مستخدم + مشروع) وهو **أيضاً** مصدر تدقيق غير متصل. Goose (codename goose، Block) يثبّت مع `--cli goose` (رطاق مستخدم + مشروع) — المثبّت يضع دليل plugin في `~/.agents/plugins/failproofai/` الذي يكتشفه Goose تلقائياً، وهو **أيضاً** مصدر تدقيق غير متصل.
+
+    ```bash
+    failproofai policies --install --scope project
+    failproofai policies --install --cli codex --scope project
+    failproofai policies --install --cli copilot --scope project
+    failproofai policies --install --cli cursor --scope project
+    failproofai policies --install --cli opencode --scope project
+    failproofai policies --install --cli pi --scope project
+    failproofai policies --install --cli hermes --scope user
+    failproofai policies --install --cli openclaw --scope user
+    failproofai policies --install --cli factory --scope project
+    failproofai policies --install --cli devin --scope project
+    failproofai policies --install --cli antigravity --scope project
+    failproofai policies --install --cli goose --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/`. أسقط ملفات السياسات في هذا الدليل وسيتم تحميلها تلقائياً — بدون أعلام، بدون تغييرات في الإعدادات، بدون أوامر تثبيت.
+
+<Steps>
+  <Step title="أنشئ دليل السياسات">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+  </Step>
+  <Step title="أضف ملفات السياسات">
+    انسخ أمثلة المبتدئين أو اكتب الخاصة بك:
+
+    ```bash
+    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
+    ```
+
+    أو أنشئ واحداً جديداً:
+
+    ```js
+    // .failproofai/policies/team-policies.mjs
+    import { customPolicies, allow, deny, instruct } from "failproofai";
+
+    customPolicies.add({
+      name: "test-before-commit",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
+          return instruct("Run tests before committing.");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="التزم بـ git">
+    ```bash
+    git add .failproofai/policies/
+    git commit -m "Add team quality policies"
+    ```
+
+    كل عضو في الفريق لديه failproofai مثبتاً يختار هذه السياسات تلقائياً. لا توجد حاجة إلى إعداد لكل مطور.
+  </Step>
+</Steps>
+
+<Tip>
+التزم بـ `.failproofai/policies/` لمستودعك حتى يشارك الفريق بأكمله نفس المعايير. مع اكتشاف فريقك لأنماط فشل جديدة، أضف سياسات وادفع — يحصل الجميع على التحديث في `git pull` التالي لهم. بمرور الوقت، تصبح هذه السياسات معياراً جودة حياً يستمر في التحسن.
+</Tip>
+
+---
+
+## تخزين البيانات
+
+تبقى جميع الإعدادات والسجلات على جهازك:
+
+| المسار | ما يخزنه |
+|------|----------|
+| `~/.failproofai/policies/local-policies/policies-config.json` | إعداد السياسة العام |
+| `~/.failproofai/hook-activity/` | سجل تنفيذ Hook (JSONL مقسّم) |
+| `~/.failproofai/logs/` | سجلات تصحيح لأخطاء hook المخصصة |
+| `.failproofai/policies-config.json` | إعداد لكل مشروع (ملتزم) |
+| `.failproofai/policies-config.local.json` | التجاوزات الشخصية (مُدرج في gitignore) |
+
+---
+
+## إلغاء التثبيت
+
+```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-old/ar/introduction.mdx

@@ -0,0 +1,58 @@
+---
+---
+title: "Failproof AI"
+description: "FailproofAI يعطي وكلاء الذكاء الاصطناعي 39 سياسة فشل مدمجة تمسك الحلقات والتسريبات السرية واستدعاءات الأدوات المدمرة والمزيد في تثبيت واحد."
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+خطاطيف وسياسات لـ **معالجة فشل الذكاء الاصطناعي** و **استرجاع الأخطاء** و **موثوقية نموذج اللغة الكبير**. حافظ على موثوقية وكلاء الذكاء الاصطناعي لديك وتشغيلهم بشكل مستقل عبر **Claude Code** و **OpenAI Codex** و **GitHub Copilot** و **Cursor Agent** و **OpenCode** و **Pi** و **Hermes** و **OpenClaw** و **Factory Droid** و **Devin CLI** و **Antigravity CLI** و **Agents SDK**.
+
+وكلاء الذكاء الاصطناعي يفشلون بطرق يمكن التنبؤ بها. يقومون بتشغيل أوامر مدمرة وتسريب الأسرار والانجراف خارج المهمة والعلق في حلقات أو الدفع مباشرة إلى الفرع الرئيسي. إذا تركت دون مراقبة، فإن الأعطال الصغيرة تتسبب في انقطاعات وتسريب بيانات الاعتماد وفقدان العمل.
+
+يحل FailproofAI هذه المشكلة باستخدام **السياسات**. هذه القواعد تتصل بكل استدعاء أداة وكيل لـ **كشف الأعطال** و **تخفيفها** (الحجب أو التعليم أو التنظيف) و **تنبيهك** عند الحاجة إلى الاهتمام. يسمح لك لوحة تحكم محلية بمراجعة كل استدعاء أداة وعطل وكيل وإجراء استرجاع لاحقاً.
+
+النصوص وتقييم السياسة يبقى على جهازك. يتم إرسال البيانات فقط عند استخدامك صراحة لميزة متصلة بالإنترنت، مثل تذكيرات التدقيق المصرح بها أو الدعوات.
+
+## ابدأ الآن
+
+<CardGroup cols={2}>
+
+<Card title="39 سياسة مدمجة" icon="shield" href="/ar/built-in-policies">
+  احجب الأوامر المدمرة ومنع تسريب الأسرار وأبقِ الوكلاء داخل حدود المشروع والمزيد. كل شيء جاهز للاستخدام.
+</Card>
+
+<Card title="سياسات مخصصة" icon="code" href="/ar/custom-policies">
+  اكتب قواعدك الخاصة في JavaScript باستخدام واجهة برمجية سهلة allow / deny / instruct.
+</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   # فعّل السياسات (أو تخطَّ — `failproofai` سيعرض عليك الإعداد عند التشغيل الأول)
+failproofai                      # شغّل لوحة التحكم
+```
+
+انظر إلى دليل [ابدأ الآن](/ar/getting-started) للحصول على المسار الكامل.

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

@@ -0,0 +1,83 @@
+---
+---
+title: اسم الحزم المستعارة
+description: "الأسماء المستعارة المسجلة لمنع محاولات الاستيلاء على الأسماء وكيفية عملها"
+icon: copy
+---
+
+## الحزمة الرسمية
+
+حزمة npm الأساسية هي **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# أو
+bun add -g failproofai
+```
+
+---
+
+## لماذا نملك أسماء الاستعارات
+
+محاولات الاستيلاء على الأسماء هي هجوم شائع على سلسلة التوريد، حيث يسجل ممثل خطر اسم حزمة يبعد ضغطة واحدة فقط عن حزمة شهيرة. المستخدمون غير المتنبهون الذين يخطئون في كتابة أمر التثبيت ينتهي بهم الحال بتشغيل كود يسيطر عليه المهاجم بصلاحيات وصول كاملة للنظام - تماماً نوع التهديد الذي صُمم Failproof AI للدفاع ضده.
+
+لإزالة هذا الثغرة، **نملك مسبقاً جميع الأخطاء الإملائية والمتغيرات الشكلية الشائعة** لـ `failproofai` على npm. لا يمكن لأي طرف ثالث تسجيل أي من هذه الأسماء. كل واحد منها هو وكيل بسيط يثبت ويفوض إلى حزمة `failproofai` الحقيقية.
+
+---
+
+## الأسماء المستعارة المسجلة
+
+**متغيرات الصيغة** - طرق مختلفة لكتابة "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` كاعتماد - لذا يتم تثبيت الحزمة الحقيقية وتصبح ملفاتها التنفيذية متاحة
+2. تعرض ملف تنفيذي يطابق اسمها الخاص (مثل `failprof-ai`) يوكل جميع المعاملات إلى ملف `failproofai` التنفيذي
+
+الوكيل هو سكريبت Node من سطرين؛ لا توجد منطق، لا توجد استدعاءات شبكية، ولا جمع بيانات بخلاف ما يقوم به `failproofai` نفسه.
+
+---
+
+## إذا وجدت اسماً لم نسجله
+
+افتح مشكلة في [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) وسنقوم بتسجيله.

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

@@ -0,0 +1,260 @@
+---
+title: الاختبار
+description: "اختبارات الوحدة واختبارات end-to-end ومساعدات الاختبار"
+icon: flask-vial
+---
+
+failproofai يحتوي على مجموعتي اختبار: **اختبارات الوحدة** (سريعة، محاكاة) و**اختبارات end-to-end** (استدعاءات عمليات فعلية).
+
+---
+
+## تشغيل الاختبارات
+
+```bash
+# تشغيل جميع اختبارات الوحدة مرة واحدة
+bun run test:run
+
+# تشغيل اختبارات الوحدة في وضع المراقبة
+bun run test
+
+# تشغيل اختبارات E2E (يتطلب إعداد - انظر أدناه)
+bun run test:e2e
+
+# التحقق من النوع دون البناء
+bunx tsc --noEmit
+
+# فحص الكود
+bun run lint
+```
+
+---
+
+## اختبارات الوحدة
+
+تقع اختبارات الوحدة في `__tests__/` وتستخدم [Vitest](https://vitest.dev) مع `jsdom`.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # منطق السياسة لكل سياسة مدمجة
+    hooks-config.test.ts          # تحميل الإعدادات ودمج النطاق
+    policy-evaluator.test.ts      # حقن المعاملات وترتيب التقييم
+    custom-hooks-registry.test.ts # إضافة/الحصول/مسح السجل العام
+    custom-hooks-loader.test.ts   # محمل ESM، الاستيراد المتعدي، معالجة الأخطاء
+    manager.test.ts               # عمليات التثبيت/الإزالة/القائمة
+  components/
+    sessions-list.test.tsx        # مكون قائمة الجلسات
+    project-list.test.tsx         # مكون قائمة المشاريع
+    ...
+  lib/
+    logger.test.ts
+    paths.test.ts
+    date-filters.test.ts
+    telemetry.test.ts
+    ...
+  actions/
+    get-hooks-config.test.ts
+    get-hook-activity.test.ts
+    ...
+  contexts/
+    ThemeContext.test.tsx
+    AutoRefreshContext.test.tsx
+```
+
+### كتابة اختبار وحدة سياسة
+
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { getBuiltinPolicies } from "../../src/hooks/builtin-policies";
+import { allow, deny } from "../../src/hooks/policy-types";
+
+describe("block-sudo", () => {
+  const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!;
+
+  it("denies sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo apt install nodejs" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai"));
+  });
+
+  it("allows non-sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "ls -la" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+
+  it("allows patterns in allowPatterns", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo systemctl status nginx" },
+      params: { allowPatterns: ["sudo systemctl status"] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+});
+```
+
+---
+
+## اختبارات end-to-end
+
+تستدعي اختبارات E2E الثنائي الحقيقي `failproofai` كعملية فرعية، وتوجه حمولة JSON إلى stdin، وتؤكد على مخرجات stdout وكود الخروج. يختبر هذا مسار التكامل الكامل الذي يستخدمه Claude Code.
+
+### الإعداد
+
+تشغل اختبارات E2E الثنائي مباشرة من مصدر المستودع. قبل التشغيل الأول، قم بناء حزمة CJS التي تستخدمها ملفات الخطاف المخصص عند استيرادها من `'failproofai'`:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+ثم شغل الاختبارات:
+
+```bash
+bun run test:e2e
+```
+
+أعد بناء `dist/` في أي وقت تغير فيه API خطاف عام (`src/hooks/custom-hooks-registry.ts`، `src/hooks/policy-helpers.ts`، أو `src/hooks/policy-types.ts`).
+
+### هيكل اختبار E2E
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # توليد الثنائي، توجيه JSON الحمولة، التقاط كود الخروج + stdout + stderr
+    fixture-env.ts      # بيئات مؤقتة معزولة لكل اختبار مع ملفات الإعدادات
+    payloads.ts         # مصانع حمولة دقيقة Claude لكل نوع حدث
+  hooks/
+    builtin-policies.e2e.test.ts   # كل سياسة مدمجة مع عملية فرعية حقيقية
+    custom-hooks.e2e.test.ts       # تحميل ودمج الخطاف المخصص
+    config-scopes.e2e.test.ts      # دمج الإعدادات عبر المشروع/المحلي/العام
+    policy-params.e2e.test.ts      # حقن المعاملات لكل سياسة ذات معاملات
+```
+
+### استخدام مساعدات E2E
+
+**`FixtureEnv`** - بيئة معزولة لكل اختبار:
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - مجلد مؤقت؛ مرره كـ payload.cwd لالتقاط .failproofai/policies-config.json
+// env.home   - مجلد منزل معزول؛ لا توجد تسريبات حقيقية من ~/.failproofai
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` يسجل تنظيف `afterEach` تلقائيًا.
+
+**`runHook`** - استدع الثنائي:
+
+```typescript
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+const result = await runHook(
+  "PreToolUse",
+  Payloads.preToolUse.bash("sudo apt install nodejs", env.cwd),
+  { homeDir: env.home }
+);
+
+expect(result.exitCode).toBe(0);
+expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+```
+
+**`Payloads`** - مصانع حمولة جاهزة:
+
+```typescript
+Payloads.preToolUse.bash(command, cwd)
+Payloads.preToolUse.write(filePath, content, cwd)
+Payloads.preToolUse.read(filePath, cwd)
+Payloads.postToolUse.bash(command, output, cwd)
+Payloads.postToolUse.read(filePath, content, cwd)
+Payloads.notification(message, cwd)
+Payloads.stop(cwd)
+```
+
+### كتابة اختبار E2E
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { createFixtureEnv } from "../helpers/fixture-env";
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+describe("block-rm-rf (E2E)", () => {
+  it("denies rm -rf", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm -rf /", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+  });
+
+  it("allows non-recursive rm", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm /tmp/file.txt", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("");  // السماح → stdout فارغ
+  });
+});
+```
+
+### أشكال استجابة E2E
+
+| القرار | كود الخروج | stdout |
+|----------|-----------|--------|
+| `PreToolUse` رفض | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` رفض | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| تعليمات (غير Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| تعليمات Stop | `2` | stdout فارغ؛ السبب في stderr |
+| السماح | `0` | سلسلة فارغة |
+
+### إعدادات Vitest
+
+تستخدم اختبارات E2E `vitest.config.e2e.mts` مع:
+
+- `environment: "node"` - لا توجد متغيرات عام المتصفح المطلوبة
+- `pool: "forks"` - عزل عملية حقيقي (توليد الاختبارات للعمليات الفرعية)
+- `testTimeout: 20_000` - 20ث لكل اختبار (بدء الثنائي + تقييم الخطاف)
+
+حزمة `forks` مهمة: العاملين القائمين على الخيوط يشاركون `globalThis`، مما قد يتداخل مع اختبارات التوليد الفرعي. عمليات forks تتجنب هذا.
+
+---
+
+## CI
+
+يتطلب التشغيل الكامل للـ CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) أن يمر قبل الدمج. تشغل مجموعة E2E كمهمة CI منفصلة بالتوازي.
+
+انظر [المساهمة](../CONTRIBUTING.md) للحصول على قائمة التحقق الكاملة قبل الدمج.