failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,332 @@
+---
+title: Architektur
+description: "Wie der Hook-Handler, das Laden der Konfiguration und die Policy-Auswertung intern funktionieren"
+icon: sitemap
+---
+
+Dieses Dokument erklärt, wie failproofai intern funktioniert: wie das Hook-System Agent-Tool-Aufrufe abfängt, wie die Konfiguration geladen und zusammengeführt wird, wie Policies ausgewertet werden und wie das Dashboard die Agentenaktivität überwacht.
+
+---
+
+## Überblick
+
+failproofai besteht aus zwei unabhängigen Subsystemen:
+
+1. **Hook-Handler** – Ein schneller CLI-Subprocess, den Claude Code bei jedem Agent-Tool-Aufruf aufruft. Wertet Policies aus und gibt eine Entscheidung zurück.
+2. **Agent Monitor (Dashboard)** – Eine Next.js-Webanwendung zur Überwachung von Agentensitzungen und zur Verwaltung von Policies.
+
+Beide Subsysteme teilen sich Konfigurationsdateien in `~/.failproofai/` und im `.failproofai/`-Verzeichnis des Projekts, laufen jedoch als separate Prozesse und kommunizieren ausschließlich über das Dateisystem.
+
+---
+
+## Hook-Handler
+
+### Integration mit Claude Code
+
+Wenn Sie `failproofai policies --install` ausführen, schreibt es folgende Einträge in `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code ruft daraufhin `failproofai --hook PreToolUse` als Subprocess vor jedem Tool-Aufruf auf und übergibt dabei einen JSON-Payload über stdin.
+
+### Payload-Format
+
+```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" }
+}
+```
+
+Bei `PostToolUse`-Events enthält der Payload zusätzlich `tool_result` mit der Ausgabe des Tools.
+
+Der Handler setzt ein Limit von 1 MB für stdin. Payloads, die dieses Limit überschreiten, werden verworfen und alle Policies erlauben implizit.
+
+### Antwortformat
+
+**Deny (PreToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
+  }
+}
+```
+
+**Deny (PostToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Blocked by failproofai because: API key detected in output"
+  }
+}
+```
+
+**Instruct (alle Events außer Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Stop-Event instruct:**
+- Exit-Code: `2`
+- Grund wird nach stderr geschrieben (nicht stdout)
+
+**Allow:**
+- Exit-Code: `0`
+- Leerer stdout
+
+**Allow mit Nachricht (Beta):**
+
+Seit v0.0.2-beta.3 ermöglicht `allow(message)` einer Policy, informativen Kontext an Claude zurückzusenden, auch wenn die Operation erlaubt wird. Der Hook-Handler schreibt folgendes JSON nach **stdout** (keine Konfigurationsdatei – dies ist die Antwort des Handlers an Claude Code, genau wie deny- und instruct-Antworten oben):
+
+```json
+// Written to stdout by the hook handler process
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Exit-Code: `0` (Operation ist erlaubt)
+- Wenn mehrere Policies `allow` mit einer Nachricht zurückgeben, werden ihre Nachrichten mit Zeilenumbrüchen zu einem einzigen `additionalContext`-String verbunden
+- Wenn keine Policy eine Nachricht liefert, ist stdout leer (wie zuvor)
+
+### Verarbeitungspipeline
+
+`src/hooks/handler.ts` implementiert die vollständige 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 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
+```
+
+Der gesamte Prozess läuft bei typischen Payloads ohne LLM-Aufrufe in unter 100 ms ab.
+
+---
+
+## Konfiguration laden
+
+`src/hooks/hooks-config.ts` implementiert das dreistufige Laden der Konfiguration.
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← Projekt  (höchste Priorität)
+[2] {cwd}/.failproofai/policies-config.local.json  ← lokal
+[3] ~/.failproofai/policies-config.json             ← global   (niedrigste Priorität)
+```
+
+Zusammenführungslogik:
+- `enabledPolicies` – deduplizierte Vereinigung aller drei Dateien
+- `policyParams` – pro Policy-Schlüssel gewinnt die erste Datei, die ihn definiert, vollständig
+- `customPoliciesPath` – die erste Datei, die ihn definiert, gewinnt
+- `llm` – die erste Datei, die ihn definiert, gewinnt
+
+Das Web-Dashboard verwendet `readHooksConfig()` (nur global) zum Lesen und Schreiben, da es nicht mit einem Projekt-cwd aufgerufen wird.
+
+---
+
+## Policy-Auswertung
+
+`src/hooks/policy-evaluator.ts` führt Policies der Reihe nach aus.
+
+Für jede Policy:
+
+1. Das `params`-Schema der Policy nachschlagen (sofern vorhanden).
+2. `policyParams[policy.name]` aus der zusammengeführten Konfiguration lesen.
+3. Benutzerdefinierte Werte über Schema-Standardwerte zusammenführen, um `ctx.params` zu erzeugen.
+4. `policy.fn(ctx)` mit dem aufgelösten Kontext aufrufen.
+5. Ist das Ergebnis `deny`, sofort stoppen und diese Entscheidung zurückgeben.
+6. Ist das Ergebnis `instruct`, die Nachricht sammeln und fortfahren.
+7. Ist das Ergebnis `allow`, mit der nächsten Policy fortfahren.
+
+Nach Ausführung aller Policies:
+- Wenn ein `deny` zurückgegeben wurde, die Deny-Antwort ausgeben.
+- Wenn `instruct`-Rückgaben gesammelt wurden, eine einzelne instruct-Antwort mit allen verbundenen Nachrichten ausgeben.
+- Andernfalls eine Allow-Antwort ausgeben (leerer stdout, Exit 0).
+
+---
+
+## Eingebaute Policies
+
+`src/hooks/builtin-policies.ts` definiert alle 26 eingebauten Policies als `BuiltinPolicyDefinition`-Objekte:
+
+```typescript
+interface BuiltinPolicyDefinition {
+  name: string;
+  description: string;
+  fn: (ctx: PolicyContext) => PolicyResult;
+  match: {
+    events: HookEventType[];
+    tools?: string[];
+  };
+  defaultEnabled: boolean;
+  category: string;
+  beta?: boolean;
+  params?: PolicyParamsSchema;
+}
+```
+
+Policies, die `params` akzeptieren, deklarieren ein `PolicyParamsSchema` mit Typen und Standardwerten für jeden Parameter. Der Policy-Evaluator injiziert aufgelöste Werte in `ctx.params`, bevor `fn` aufgerufen wird. Policy-Funktionen lesen `ctx.params` ohne Null-Prüfung, da Standardwerte immer zuerst angewendet werden.
+
+Pattern-Matching innerhalb von Policies verwendet geparste Befehlstoken (argv) statt einfachen String-Vergleichen. Dies verhindert Umgehungsversuche durch Shell-Operator-Injection (z. B. kann ein Muster für `sudo systemctl status *` nicht durch Anhängen von `; rm -rf /` an den Befehl umgangen werden).
+
+---
+
+## Benutzerdefinierte Policies
+
+`src/hooks/custom-hooks-registry.ts` implementiert eine `globalThis`-basierte Registry:
+
+```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` lädt die Policy-Datei des Benutzers:
+
+1. `customPoliciesPath` aus der Konfiguration lesen; überspringen, falls nicht vorhanden.
+2. Zu absolutem Pfad auflösen; prüfen, ob die Datei existiert.
+3. Alle `from "failproofai"`-Imports zum tatsächlichen dist-Pfad umschreiben, damit `customPolicies` zur selben `globalThis`-Registry aufgelöst wird.
+4. Transitive lokale Imports rekursiv umschreiben, um ESM-Kompatibilität sicherzustellen.
+5. Temporäre `.mjs`-Dateien schreiben und die Einstiegsdatei per `import()` laden.
+6. `getCustomHooks()` aufrufen, um registrierte Hooks abzurufen.
+7. Alle temporären Dateien in einem `finally`-Block bereinigen.
+
+Bei jedem Fehler (Datei nicht gefunden, Syntaxfehler, Import-Fehler) wird der Fehler in `~/.failproofai/hook.log` protokolliert und der Loader gibt ein leeres Array zurück. Eingebaute Policies sind davon nicht betroffen.
+
+Benutzerdefinierte Policies werden nach allen eingebauten Policies ausgewertet. Ein `deny` einer benutzerdefinierten Policy unterbricht dennoch weitere benutzerdefinierte Policies (alle eingebauten Policies sind zu diesem Zeitpunkt jedoch bereits ausgeführt worden).
+
+---
+
+## Aktivitätsprotokollierung
+
+Nach jedem Hook-Event hängt der Handler eine JSONL-Zeile an `~/.failproofai/hook-activity.jsonl` an:
+
+```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
+}
+```
+
+Eine Zeile pro Policy, die eine Nicht-Allow-Entscheidung getroffen hat. Allow-Entscheidungen werden nicht protokolliert (um die Dateigröße gering zu halten).
+
+---
+
+## Dashboard-Architektur
+
+Das Dashboard ist eine **Next.js 16**-Anwendung, die den App Router mit React Server Components und Server Actions verwendet.
+
+```text
+app/
+  layout.tsx                  ← Root-Layout (Theme, Telemetrie, Navigation)
+  projects/page.tsx           ← Server-Komponente: alle Claude-Projekte auflisten
+  project/[name]/page.tsx     ← Server-Komponente: Sitzungen in einem Projekt auflisten
+  project/[name]/session/
+    [sessionId]/page.tsx      ← Server-Komponente: Sitzungsansicht rendern
+  policies/page.tsx           ← Client-Komponente: Policy-Verwaltung + Aktivitätslog
+  actions/
+    get-hooks-config.ts       ← Konfiguration + Policy-Liste lesen
+    update-hooks-config.ts    ← Policy ein-/ausschalten
+    update-policy-params.ts   ← Policy-Parameter aktualisieren
+    get-hook-activity.ts      ← Aktivitätslog paginieren/durchsuchen
+    install-hooks-web.ts      ← Hooks über den Browser installieren/entfernen
+  api/
+    download/[project]/[session]/route.ts   ← Sitzung als ZIP/JSONL exportieren
+```
+
+**Datenfluss:**
+
+- Seitenkomponenten rufen `lib/projects.ts` und `lib/log-entries.ts` auf, um Projekt-/Sitzungsdaten direkt aus dem Dateisystem zu lesen (keine API-Schicht für Lesevorgänge).
+- Die Policies-Seite verwendet Server Actions für alle Mutationen (Umschalten, Parameter-Aktualisierung, Installieren/Entfernen).
+- Der Sitzungs-Viewer parst das JSONL-Transkriptformat von Claude und rendert einen Zeitstrahl von Nachrichten und Tool-Aufrufen.
+
+**Wesentliche Designentscheidungen:**
+
+- Keine Datenbank – der gesamte persistente Zustand liegt in einfachen Dateien (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions für Mutationen – kein REST-API für CRUD-Operationen erforderlich.
+- React Server Components für Lese-Seiten – schnelleres initiales Laden, kein Client-Bundle für Datenabruf.
+- Client-Komponenten nur dort, wo Interaktivität benötigt wird (Policy-Umschalter, Aktivitätssuche, Log-Viewer).
+
+---
+
+## Dateistruktur
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # CLI-Router (hook / dashboard / install / etc.)
+├── src/hooks/
+│   ├── handler.ts                # Hook-Event-Pipeline
+│   ├── builtin-policies.ts       # 26 Policy-Definitionen
+│   ├── policy-evaluator.ts       # Policy-Ausführungs-Engine
+│   ├── policy-registry.ts        # Policy-Registrierung und -Nachschlagen
+│   ├── policy-types.ts           # TypeScript-Interfaces
+│   ├── hooks-config.ts           # Mehrstufiges Laden der Konfiguration
+│   ├── custom-hooks-registry.ts  # globalThis-basierte Hook-Registry
+│   ├── custom-hooks-loader.ts    # ESM-Loader für benutzerdefinierte JS-Hooks
+│   ├── manager.ts                # Installations-/Entfernen-/Auflistungsoperationen
+│   ├── install-prompt.ts         # Interaktive Policy-Auswahlabfrage
+│   ├── hook-logger.ts            # Protokollierung nach hook.log
+│   ├── hook-activity-store.ts    # Aktivität nach hook-activity.jsonl persistieren
+│   └── llm-client.ts             # LLM-API-Client (für KI-gestützte Policies)
+├── app/                          # Next.js-Dashboard (Seiten + Server Actions)
+├── lib/                          # Gemeinsame Hilfsfunktionen
+│   ├── projects.ts               # Claude-Projekte aus dem Dateisystem aufzählen
+│   ├── log-entries.ts            # Claude-Transkript-JSONL-Format parsen
+│   ├── paths.ts                  # Systempfade auflösen
+│   └── ...
+├── components/                   # Gemeinsame React-UI-Komponenten
+├── contexts/                     # React-Context-Provider (Theme, Auto-Refresh, Telemetrie)
+├── examples/                     # Beispieldateien für benutzerdefinierte Hooks
+└── __tests__/                    # Unit- und E2E-Tests
+```