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

package/.next/standalone/dist/index.js

@@ -1,80 +0,0 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-function __accessProp(key) {
-  return this[key];
-}
-var __toCommonJS = (from) => {
-  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (var key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(entry, key))
-        __defProp(entry, key, {
-          get: __accessProp.bind(from, key),
-          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-        });
-  }
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __moduleCache;
-var __returnValue = (v) => v;
-function __exportSetter(name, newValue) {
-  this[name] = __returnValue.bind(null, newValue);
-}
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: __exportSetter.bind(all, name)
-    });
-};
-
-// src/index.ts
-var exports_src = {};
-__export(exports_src, {
-  instruct: () => instruct,
-  getCustomHooks: () => getCustomHooks,
-  deny: () => deny,
-  customPolicies: () => customPolicies,
-  clearCustomHooks: () => clearCustomHooks,
-  allow: () => allow
-});
-module.exports = __toCommonJS(exports_src);
-
-// src/hooks/custom-hooks-registry.ts
-var REGISTRY_KEY = "__failproofai_custom_hooks__";
-function getRegistry() {
-  const g = globalThis;
-  if (!Array.isArray(g[REGISTRY_KEY]))
-    g[REGISTRY_KEY] = [];
-  return g[REGISTRY_KEY];
-}
-var customPolicies = {
-  add(hook) {
-    getRegistry().push(hook);
-  }
-};
-function getCustomHooks() {
-  return getRegistry();
-}
-function clearCustomHooks() {
-  const g = globalThis;
-  g[REGISTRY_KEY] = [];
-}
-// src/hooks/policy-helpers.ts
-function allow(reason) {
-  return reason ? { decision: "allow", reason } : { decision: "allow" };
-}
-function deny(reason) {
-  return { decision: "deny", reason };
-}
-function instruct(reason) {
-  return { decision: "instruct", reason };
-}

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

@@ -1,334 +0,0 @@
----
-
----
-title: المعمارية
-description: "كيفية عمل معالج الخطاف وتحميل الإعدادات وتقييم السياسات داخلياً"
-icon: sitemap
----
-
-توضح هذه الوثيقة كيفية عمل failproofai داخلياً: كيف يعترض نظام الخطاف استدعاءات أداة الوكيل، وكيف يتم تحميل ودمج الإعدادات، وكيف يتم تقييم السياسات، وكيف تراقب لوحة التحكم نشاط الوكيل.
-
----
-
-## نظرة عامة
-
-يتكون failproofai من نظامين فرعيين مستقلين:
-
-1. **معالج الخطاف** - عملية CLI سريعة يستدعيها Claude Code على كل استدعاء أداة وكيل. يقيّم السياسات ويرجع قراراً.
-2. **مراقب الوكيل (لوحة التحكم)** - تطبيق ويب Next.js لمراقبة جلسات الوكيل وإدارة السياسات.
-
-يشترك كلا النظامين الفرعيين في ملفات الإعدادات في `~/.failproofai/` ومجلد المشروع `.failproofai/`، لكنهما يعملان كعمليات منفصلة ويتواصلان فقط عبر نظام الملفات.
-
----
-
-## معالج الخطاف
-
-### التكامل مع Claude Code
-
-عند تشغيل `failproofai policies --install`، فإنه يكتب إدخالات مثل هذه في `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "failproofai --hook PreToolUse"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [ ... ]
-  }
-}
-```
-
-بعد ذلك يستدعي Claude Code `failproofai --hook PreToolUse` كعملية فرعية قبل كل استدعاء أداة، مع تمرير حمولة JSON على stdin.
-
-### صيغة الحمولة
-
-```json
-{
-  "session_id": "abc123",
-  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
-  "cwd": "/home/user/myproject",
-  "permission_mode": "default",
-  "hook_event_name": "PreToolUse",
-  "tool_name": "Bash",
-  "tool_input": { "command": "sudo apt install nodejs" }
-}
-```
-
-بالنسبة لأحداث `PostToolUse`، تحتوي الحمولة أيضاً على `tool_result` مع مخرجات الأداة.
-
-يفرض المعالج حد أقصى بحجم 1 ميجابايت لـ stdin. يتم تجاهل الحمولات التي تتجاوز هذا الحد وجميع السياسات تسمح بشكل ضمني.
-
-### صيغة الاستجابة
-
-**الرفض (PreToolUse):**
-```json
-{
-  "hookSpecificOutput": {
-    "permissionDecision": "deny",
-    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
-  }
-}
-```
-
-**الرفض (PostToolUse):**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Blocked by failproofai because: API key detected in output"
-  }
-}
-```
-
-**التعليمات (أي حدث باستثناء Stop):**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
-  }
-}
-```
-
-**حدث التعليمات Stop:**
-- رمز الخروج: `2`
-- السبب مكتوب على stderr (وليس stdout)
-
-**السماح:**
-- رمز الخروج: `0`
-- stdout فارغ
-
-**السماح مع رسالة:**
-
-`allow(message)` تسمح لسياسة ما بإرسال سياق معلوماتي مرة أخرى إلى Claude حتى عندما تكون العملية مسموحة. يكتب معالج الخطاف JSON التالي إلى **stdout** (وليس ملف إعدادات — هذه استجابة المعالج لـ Claude Code، تماماً مثل استجابات الرفض والتعليمات أعلاه):
-
-```json
-// Written to stdout by the hook handler process
-{
-  "hookSpecificOutput": {
-    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
-  }
-}
-```
-- رمز الخروج: `0` (العملية مسموحة)
-- عندما تعيد عدة سياسات `allow` مع رسالة، يتم دمج رسائلها بفواصل أسطر في سلسلة واحدة `additionalContext`
-- إذا لم تقدم أي سياسة رسالة، فإن stdout فارغ (كما كان من قبل)
-
-### خط معالجة الأنابيب
-
-يطبق `src/hooks/handler.ts` خط الأنابيب الكامل:
-
-```text
-stdin JSON
-  → parse payload (max 1 MB)
-  → extract session metadata (session_id, cwd, tool_name, tool_input, etc.)
-  → readMergedHooksConfig(cwd)    ← merges project + local + global config
-  → register enabled builtin policies with resolved params
-  → load custom policies from customPoliciesPath (if set)
-  → register custom policies into policy registry
-  → evaluate all policies (builtins first, then custom)
-      → first deny short-circuits
-      → instruct decisions accumulate
-      → allow messages accumulate
-  → write JSON decision to stdout
-  → persist event to ~/.failproofai/hook-activity.jsonl
-  → exit
-```
-
-تعمل العملية بأكملها في أقل من 100 ميلي ثانية للحمولات النموذجية بدون استدعاءات LLM.
-
----
-
-## تحميل الإعدادات
-
-يطبق `src/hooks/hooks-config.ts` تحميل الإعدادات بثلاث نطاقات.
-
-```text
-[1] {cwd}/.failproofai/policies-config.json        ← project  (highest priority)
-[2] {cwd}/.failproofai/policies-config.local.json  ← local
-[3] ~/.failproofai/policies-config.json             ← global   (lowest priority)
-```
-
-منطق الدمج:
-- `enabledPolicies` - اتحاد مخصص عبر جميع الملفات الثلاثة
-- `policyParams` - لكل سياسة، الملف الأول الذي يحددها يفوز تماماً
-- `customPoliciesPath` - الملف الأول الذي يحددها يفوز
-- `llm` - الملف الأول الذي يحددها يفوز
-
-تستخدم لوحة تحكم الويب `readHooksConfig()` (عام فقط) للقراءة والكتابة، لأنها لا تُستدعى مع cwd مشروع.
-
----
-
-## تقييم السياسة
-
-يشغل `src/hooks/policy-evaluator.ts` السياسات بالترتيب.
-
-لكل سياسة:
-
-1. ابحث عن مخطط `params` الخاص بالسياسة (إن كان لديها واحدة).
-2. اقرأ `policyParams[policy.name]` من الإعدادات المدمجة.
-3. دمج القيم المعطاة من قبل المستخدم على القيم الافتراضية للمخطط لإنتاج `ctx.params`.
-4. استدع `policy.fn(ctx)` مع السياق المحل.
-5. إذا كانت النتيجة `deny`، توقف فوراً وأرجع هذا القرار.
-6. إذا كانت النتيجة `instruct`، اجمع الرسالة وتابع.
-7. إذا كانت النتيجة `allow`، انتقل إلى السياسة التالية.
-
-بعد تشغيل جميع السياسات:
-- إذا تم إرجاع أي `deny`، أصدر استجابة الرفض.
-- إذا تم جمع أي إرجاعات `instruct`، أصدر استجابة تعليمات واحدة مع جميع الرسائل المدمجة.
-- وإلا، أصدر استجابة السماح (stdout فارغ، خروج 0).
-
----
-
-## السياسات المدمجة
-
-يحدد `src/hooks/builtin-policies.ts` جميع السياسات المدمجة الـ 26 ك `BuiltinPolicyDefinition` كائنات:
-
-```typescript
-interface BuiltinPolicyDefinition {
-  name: string;
-  description: string;
-  fn: (ctx: PolicyContext) => PolicyResult;
-  match: {
-    events: HookEventType[];
-    tools?: string[];
-  };
-  defaultEnabled: boolean;
-  category: string;
-  beta?: boolean;
-  params?: PolicyParamsSchema;
-}
-```
-
-السياسات التي تقبل `params` تعلن عن `PolicyParamsSchema` مع الأنواع والقيم الافتراضية لكل معامل. يحقن محيّم السياسة القيم المحلولة في `ctx.params` قبل استدعاء `fn`. تقرأ وظائف السياسة `ctx.params` بدون حماية فارغة لأن القيم الافتراضية تُطبق دائماً أولاً.
-
-يستخدم مطابقة الأنماط داخل السياسات رموز الأوامر المحللة (argv)، وليس مطابقة السلسلة الخام. يمنع هذا التجاوز عبر حقن مشغل الأصداف (على سبيل المثال، نمط لـ `sudo systemctl status *` لا يمكن تجاوزه بإضافة `; rm -rf /` إلى الأمر).
-
----
-
-## السياسات المخصصة
-
-يطبق `src/hooks/custom-hooks-registry.ts` سجل مدعوم `globalThis`:
-
-```typescript
-const REGISTRY_KEY = "__failproofai_custom_hooks__";
-
-export const customPolicies = {
-  add(hook: CustomHook): void { ... }
-};
-
-export function getCustomHooks(): CustomHook[] { ... }
-export function clearCustomHooks(): void { ... }  // used in tests
-```
-
-يحمل `src/hooks/custom-hooks-loader.ts` ملف السياسة الخاص بالمستخدم:
-
-1. اقرأ `customPoliciesPath` من الإعدادات؛ تخطي إذا كانت غائبة.
-2. أعد حل المسار المطلق؛ تحقق من وجود الملف.
-3. أعد كتابة جميع استيرادات `from "failproofai"` إلى مسار dist الفعلي بحيث يتم حل `customPolicies` إلى نفس سجل `globalThis`.
-4. أعد كتابة واردات الملفات المحلية المتعدية بشكل متكرر لضمان توافق ESM.
-5. اكتب ملفات `.mjs` مؤقتة و `import()` ملف الإدخال.
-6. استدع `getCustomHooks()` لاسترجاع الخطاف المسجلة.
-7. انظف جميع الملفات المؤقتة في كتلة `finally`.
-
-عند حدوث أي خطأ (الملف غير موجود، خطأ في بناء الجملة، فشل الاستيراد)، يتم تسجيل الخطأ إلى `~/.failproofai/hook.log` ويرجع المحمل مصفوفة فارغة. السياسات المدمجة لم تتأثر.
-
-يتم تقييم السياسات المخصصة بعد جميع السياسات المدمجة. الرفض من سياسة مخصصة لا يزال يختصر السياسات المخصصة الأخرى (لكن جميع السياسات المدمجة قد تم تشغيلها بالفعل في تلك النقطة).
-
----
-
-## تسجيل النشاط
-
-بعد كل حدث خطاف، يلحق المعالج سطر JSONL بـ `~/.failproofai/hook-activity.jsonl`:
-
-```json
-{
-  "timestamp": "2026-04-06T12:34:56.789Z",
-  "sessionId": "abc123",
-  "eventType": "PreToolUse",
-  "toolName": "Bash",
-  "policyName": "block-sudo",
-  "decision": "deny",
-  "reason": "sudo command blocked by failproofai",
-  "durationMs": 12
-}
-```
-
-سطر واحد لكل سياسة اتخذت قرار غير سماح. قرارات السماح لا تسجل (للحفاظ على الملف صغيراً).
-
----
-
-## معمارية لوحة التحكم
-
-لوحة التحكم هي تطبيق **Next.js 16** يستخدم App Router مع React Server Components و Server Actions.
-
-```text
-app/
-  layout.tsx                  ← Root layout (theme, telemetry, nav)
-  projects/page.tsx           ← Server component: list all Claude projects
-  project/[name]/page.tsx     ← Server component: list sessions in a project
-  project/[name]/session/
-    [sessionId]/page.tsx      ← Server component: render session viewer
-  policies/page.tsx           ← Client component: policy management + activity log
-  actions/
-    get-hooks-config.ts       ← Read config + policy list
-    update-hooks-config.ts    ← Toggle policy on/off
-    update-policy-params.ts   ← Update policy parameters
-    get-hook-activity.ts      ← Paginate/search activity log
-    install-hooks-web.ts      ← Install/remove hooks from the browser
-  api/
-    download/[project]/[session]/route.ts   ← Export session as ZIP/JSONL
-```
-
-**تدفق البيانات:**
-
-- مكونات الصفحة تستدعي `lib/projects.ts` و `lib/log-entries.ts` لقراءة بيانات المشروع/الجلسة مباشرة من نظام الملفات (لا توجد طبقة API للقراءات).
-- تستخدم صفحة السياسات Server Actions لجميع التغييرات (تبديل، تحديث المعاملات، التثبيت/الإزالة).
-- يحلل عارض الجلسة صيغة نسخ Claude JSONL وينقل جدول زمني للرسائل واستدعاءات الأداة.
-
-**قرارات التصميم الرئيسية:**
-
-- لا توجد قاعدة بيانات - جميع الحالة الدائمة موجودة في ملفات عادية (`~/.failproofai/`, `~/.claude/projects/`).
-- Server Actions للتغييرات - لا توجد حاجة لـ REST API لعمليات CRUD.
-- React Server Components لصفحات القراءة - تحميل أولي أسرع، لا حزمة عميل لجلب البيانات.
-- مكونات العميل فقط حيث تكون التفاعل مطلوباً (تبديل السياسة، بحث النشاط، عارض السجل).
-
----
-
-## تخطيط الملف
-
-```text
-failproofai/
-├── bin/
-│   └── failproofai.mjs           # CLI router (hook / dashboard / install / etc.)
-├── src/hooks/
-│   ├── handler.ts                # Hook event pipeline
-│   ├── builtin-policies.ts       # 26 policy definitions
-│   ├── policy-evaluator.ts       # Policy execution engine
-│   ├── policy-registry.ts        # Policy registration and lookup
-│   ├── policy-types.ts           # TypeScript interfaces
-│   ├── hooks-config.ts           # Multi-scope config loading
-│   ├── custom-hooks-registry.ts  # globalThis-backed hook registry
-│   ├── custom-hooks-loader.ts    # ESM loader for user JS hooks
-│   ├── manager.ts                # install / remove / list operations
-│   ├── install-prompt.ts         # Interactive policy selection prompt
-│   ├── hook-logger.ts            # Logging to hook.log
-│   ├── hook-activity-store.ts    # Persist activity to hook-activity.jsonl
-│   └── llm-client.ts             # LLM API client (for AI-powered policies)
-├── app/                          # Next.js dashboard (pages + server actions)
-├── lib/                          # Shared utilities
-│   ├── projects.ts               # Enumerate Claude projects from filesystem
-│   ├── log-entries.ts            # Parse Claude transcript JSONL format
-│   ├── paths.ts                  # Resolve system paths
-│   └── ...
-├── components/                   # Shared React UI components
-├── contexts/                     # React context providers (theme, auto-refresh, telemetry)
-├── examples/                     # Example custom hook files
-└── __tests__/                    # Unit and E2E tests
-```