failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,261 @@
+---
+---
+title: الاختبارات
+description: "اختبارات الوحدات واختبارات الشامل (E2E) ومساعدات الاختبارات"
+icon: flask-vial
+---
+
+يتضمن failproofai مجموعتي اختبارات: **اختبارات الوحدات** (سريعة، محاكاة) و**اختبارات الشامل** (استدعاءات عملية فرعية حقيقية).
+
+---
+
+## تشغيل الاختبارات
+
+```bash
+# تشغيل جميع اختبارات الوحدات مرة واحدة
+bun run test:run
+
+# تشغيل اختبارات الوحدات في وضع المراقبة
+bun run test
+
+# تشغيل اختبارات الشامل (يتطلب إعدادًا - انظر أدناه)
+bun run test:e2e
+
+# فحص النوع بدون بناء
+bunx tsc --noEmit
+
+# فحص الكود
+bun run lint
+```
+
+---
+
+## اختبارات الوحدات
+
+تقع اختبارات الوحدات في `__tests__/` وتستخدم [Vitest](https://vitest.dev) مع `happy-dom`.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # منطق السياسة لكل سياسة مدمجة
+    hooks-config.test.ts          # تحميل الإعدادات ودمج النطاق
+    policy-evaluator.test.ts      # حقن المعاملات وترتيب التقييم
+    custom-hooks-registry.test.ts # سجل globalThis للإضافة والحصول والمسح
+    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());
+  });
+});
+```
+
+---
+
+## اختبارات الشامل (E2E)
+
+تستدعي اختبارات الشامل ملف failproofai الثنائي الفعلي كعملية فرعية، وترسل حمولة JSON إلى stdin، وتتحقق من مخرجات stdout وكود الخروج. يختبر هذا مسار التكامل الكامل الذي يستخدمه Claude Code.
+
+### الإعداد
+
+تشغل اختبارات الشامل الملف الثنائي مباشرة من مصدر المستودع. قبل التشغيل الأول، قم بناء حزمة CJS التي تستخدمها ملفات hook المخصصة عند الاستيراد من `'failproofai'`:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+ثم قم بتشغيل الاختبارات:
+
+```bash
+bun run test:e2e
+```
+
+أعد بناء `dist/` في أي وقت تغير فيه API hook العام (`src/hooks/custom-hooks-registry.ts` أو `src/hooks/policy-helpers.ts` أو `src/hooks/policy-types.ts`).
+
+### هيكل اختبار الشامل
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # تشغيل الملف الثنائي وإرسال حمولة JSON والتقاط كود الخروج والمخرجات والأخطاء
+    fixture-env.ts      # دليل مؤقت معزول لكل اختبار مع ملفات الإعدادات
+    payloads.ts         # مصانع الحمولة الدقيقة لـ Claude لكل نوع حدث
+  hooks/
+    builtin-policies.e2e.test.ts   # كل سياسة مدمجة مع عملية فرعية حقيقية
+    custom-hooks.e2e.test.ts       # تحميل وتقييم hook المخصص
+    config-scopes.e2e.test.ts      # دمج الإعدادات عبر المشروع/المحلي/العام
+    policy-params.e2e.test.ts      # حقن المعاملات لكل سياسة معاملات
+```
+
+### استخدام مساعدات الشامل
+
+**`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)
+```
+
+### كتابة اختبار شامل
+
+```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("");  // allow → empty stdout
+  });
+});
+```
+
+### أشكال استجابة الشامل
+
+| القرار | كود الخروج | stdout |
+|----------|-----------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct (غير Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| تعليمات Stop | `2` | stdout فارغة؛ السبب في stderr |
+| السماح | `0` | سلسلة فارغة |
+
+### إعدادات Vitest
+
+تستخدم اختبارات الشامل `vitest.config.e2e.mts` مع:
+
+- `environment: "node"` - لا توجد حاجة لمتغيرات المتصفح العام
+- `pool: "forks"` - عزل العملية الحقيقي (اختبارات تشغيل العمليات الفرعية)
+- `testTimeout: 20_000` - 20 ثانية لكل اختبار (بدء الملف الثنائي وتقييم hook)
+
+مجموعة `forks` مهمة: تشارك العمال المستندة إلى الخيط `globalThis`، وهو ما قد يتداخل مع اختبارات توليد العمليات الفرعية. تتجنب الفروع المستندة إلى العملية هذا.
+
+---
+
+## CI
+
+يجب أن تنجح عملية CI الكاملة (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) قبل الدمج. تعمل مجموعة الشامل كوظيفة CI منفصلة بالتوازي.
+
+انظر [المساهمة](../CONTRIBUTING.md) للحصول على قائمة التحقق الكاملة قبل الدمج.

package/.next/standalone/docs/{architecture.md → architecture.mdx}

@@ -4,7 +4,7 @@ description: "How the hook handler, config loading, and policy evaluation work i
 icon: sitemap
 ---
 
-This document explains how failproofai works internally: how the hook system processes events, how configuration is loaded and merged, how policies are evaluated, and how the dashboard fits in.
+This document explains how failproofai works internally: how the hook system intercepts agent tool calls, how configuration is loaded and merged, how policies are evaluated, and how the dashboard monitors agent activity.
 
 ---
 
@@ -12,8 +12,8 @@ This document explains how failproofai works internally: how the hook system pro
 
 failproofai has two independent subsystems:
 
-1. **Hook handler** — A fast CLI subprocess that Claude Code invokes on every tool call. Evaluates policies and returns a decision.
-2. **Dashboard** — A Next.js web application for browsing sessions and managing policies.
+1. **Hook handler** - A fast CLI subprocess that Claude Code invokes on every agent tool call. Evaluates policies and returns a decision.
+2. **Agent Monitor (Dashboard)** - A Next.js web application for monitoring agent sessions and managing policies.
 
 Both subsystems share configuration files in `~/.failproofai/` and the project's `.failproofai/` directory, but they run as separate processes and communicate only through the filesystem.
 
@@ -23,7 +23,7 @@ Both subsystems share configuration files in `~/.failproofai/` and the project's
 
 ### Integration with Claude Code
 
-When you run `failproofai --install-policies`, it writes entries like this into `~/.claude/settings.json`:
+When you run `failproofai policies --install`, it writes entries like this into `~/.claude/settings.json`:
 
 ```json
 {
@@ -60,7 +60,7 @@ Claude Code then invokes `failproofai --hook PreToolUse` as a subprocess before
 }
 ```
 
-For `PostToolUse` events, the payload additionally contains `tool_result` with the tool's output.
+For `PostToolUse` events, the payload also contains `tool_result` with the tool's output.
 
 The handler enforces a 1 MB stdin limit. Payloads exceeding this are discarded and all policies implicitly allow.
 
@@ -102,21 +102,38 @@ The handler enforces a 1 MB stdin limit. Payloads exceeding this are discarded a
 - Exit code: `0`
 - Empty stdout
 
+**Allow with message (beta):**
+
+Since v0.0.2-beta.3, `allow(message)` lets a policy send informational context back to Claude even when the operation is permitted. The hook handler writes the following JSON to **stdout** (not a config file — this is the handler's response to Claude Code, just like deny and instruct responses above):
+
+```json
+// Written to stdout by the hook handler process
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Exit code: `0` (operation is allowed)
+- When multiple policies return `allow` with a message, their messages are joined with newlines into a single `additionalContext` string
+- If no policy provides a message, stdout is empty (same as before)
+
 ### Processing pipeline
 
 `src/hooks/handler.ts` implements the full pipeline:
 
-```
+```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 hooks from customPoliciesPath (if set)
-  → register custom hooks into policy registry
+  → 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
@@ -130,17 +147,17 @@ The entire process runs in under 100ms for typical payloads with no LLM calls.
 
 `src/hooks/hooks-config.ts` implements three-scope config loading.
 
-```
+```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)
 ```
 
 Merge logic:
-- `enabledPolicies` — deduplicated union across all three files
-- `policyParams` — per-policy key, first file that defines it wins entirely
-- `customPoliciesPath` — first file that defines it wins
-- `llm` — first file that defines it wins
+- `enabledPolicies` - deduplicated union across all three files
+- `policyParams` - per-policy key, first file that defines it wins entirely
+- `customPoliciesPath` - first file that defines it wins
+- `llm` - first file that defines it wins
 
 The web dashboard uses `readHooksConfig()` (global only) for reading and writing, since it is not invoked with a project cwd.
 
@@ -169,7 +186,7 @@ After all policies run:
 
 ## Builtin policies
 
-`src/hooks/builtin-policies.ts` defines all 35+ built-in policies as `BuiltinPolicyDefinition` objects:
+`src/hooks/builtin-policies.ts` defines all 26 built-in policies as `BuiltinPolicyDefinition` objects:
 
 ```typescript
 interface BuiltinPolicyDefinition {
@@ -193,7 +210,7 @@ Pattern matching inside policies uses parsed command tokens (argv), not raw stri
 
 ---
 
-## Custom hooks
+## Custom policies
 
 `src/hooks/custom-hooks-registry.ts` implements a `globalThis`-backed registry:
 
@@ -208,7 +225,7 @@ export function getCustomHooks(): CustomHook[] { ... }
 export function clearCustomHooks(): void { ... }  // used in tests
 ```
 
-`src/hooks/custom-hooks-loader.ts` loads the user's hooks file:
+`src/hooks/custom-hooks-loader.ts` loads the user's policy file:
 
 1. Read `customPoliciesPath` from config; skip if absent.
 2. Resolve to absolute path; check file exists.
@@ -220,7 +237,7 @@ export function clearCustomHooks(): void { ... }  // used in tests
 
 On any error (file not found, syntax error, import failure), the error is logged to `~/.failproofai/hook.log` and the loader returns an empty array. Built-in policies are unaffected.
 
-Custom hooks are evaluated after all built-in policies. A custom hook `deny` still short-circuits further custom hooks (but all built-ins have already run by that point).
+Custom policies are evaluated after all built-in policies. A custom policy `deny` still short-circuits further custom policies (but all built-ins have already run by that point).
 
 ---
 
@@ -249,7 +266,7 @@ One line per policy that made a non-allow decision. Allow decisions are not logg
 
 The dashboard is a **Next.js 16** application using the App Router with React Server Components and Server Actions.
 
-```
+```text
 app/
   layout.tsx                  ← Root layout (theme, telemetry, nav)
   projects/page.tsx           ← Server component: list all Claude projects
@@ -275,22 +292,22 @@ app/
 
 **Key design decisions:**
 
-- No database — all persistent state is in plain files (`~/.failproofai/`, `~/.claude/projects/`).
-- Server Actions for mutations — no REST API needed for CRUD operations.
-- React Server Components for read pages — faster initial load, no client bundle for data fetching.
+- No database - all persistent state is in plain files (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions for mutations - no REST API needed for CRUD operations.
+- React Server Components for read pages - faster initial load, no client bundle for data fetching.
 - Client components only where interactivity is needed (policy toggles, activity search, log viewer).
 
 ---
 
 ## File layout
 
-```
+```text
 failproofai/
 ├── bin/
 │   └── failproofai.mjs           # CLI router (hook / dashboard / install / etc.)
 ├── src/hooks/
 │   ├── handler.ts                # Hook event pipeline
-│   ├── builtin-policies.ts       # 35+ policy definitions
+│   ├── builtin-policies.ts       # 26 policy definitions
 │   ├── policy-evaluator.ts       # Policy execution engine
 │   ├── policy-registry.ts        # Policy registration and lookup
 │   ├── policy-types.ts           # TypeScript interfaces