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

package/.next/standalone/docs/de/custom-policies.mdx

@@ -1,353 +0,0 @@
----
-title: Benutzerdefinierte Richtlinien
-description: "Schreibe eigene Richtlinien in JavaScript – setze Konventionen durch, verhindere Abweichungen, erkenne Fehler und integriere externe Systeme"
-icon: code
----
-
-Benutzerdefinierte Richtlinien ermöglichen es dir, Regeln für jedes Agentenverhalten zu schreiben: Projektkonventionen durchsetzen, Abweichungen verhindern, destruktive Operationen absichern, feststeckende Agenten erkennen oder Integrationen mit Slack, Genehmigungsworkflows und mehr umsetzen. Sie verwenden dasselbe Hook-Event-System und dieselben `allow`-, `deny`- und `instruct`-Entscheidungen wie integrierte Richtlinien.
-
----
-
-## Schnellbeispiel
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-customPolicies.add({
-  name: "no-production-writes",
-  description: "Block writes to paths containing 'production'",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
-    const path = ctx.toolInput?.file_path ?? "";
-    if (path.includes("production")) {
-      return deny("Writes to production paths are blocked");
-    }
-    return allow();
-  },
-});
-```
-
-Installieren:
-
-```bash
-failproofai policies --install --custom ./my-policies.js
-```
-
----
-
-## Zwei Möglichkeiten, benutzerdefinierte Richtlinien zu laden
-
-### Option 1: Konventionsbasiert (empfohlen)
-
-Lege `*policies.{js,mjs,ts}`-Dateien in `.failproofai/policies/` ab – sie werden automatisch geladen, ohne Flags oder Konfigurationsänderungen. Das funktioniert wie Git-Hooks: Datei ablegen, fertig.
-
-```
-# Projektebene — in Git eingecheckt, wird mit dem Team geteilt
-.failproofai/policies/security-policies.mjs
-.failproofai/policies/workflow-policies.mjs
-
-# Benutzerebene — persönlich, gilt für alle Projekte
-~/.failproofai/policies/my-policies.mjs
-```
-
-**So funktioniert es:**
-- Sowohl Projekt- als auch Benutzerverzeichnisse werden durchsucht (Vereinigung – kein „First-scope-wins")
-- Dateien werden innerhalb jedes Verzeichnisses alphabetisch geladen. Mit `01-`, `02-` als Präfix lässt sich die Reihenfolge steuern
-- Nur Dateien, die auf `*policies.{js,mjs,ts}` passen, werden geladen; andere Dateien werden ignoriert
-- Jede Datei wird unabhängig geladen (fail-open pro Datei)
-- Funktioniert zusammen mit expliziten `--custom`- und integrierten Richtlinien
-
-<Tip>
-Konventionsrichtlinien sind der einfachste Weg, einen Qualitätsstandard für deine Organisation aufzubauen. Checke `.failproofai/policies/` in Git ein, und jedes Teammitglied erhält automatisch dieselben Regeln – kein Setup pro Entwickler nötig. Wenn dein Team neue Fehlerquellen entdeckt, füge eine Richtlinie hinzu und pushe sie. Mit der Zeit entstehen so lebendige Qualitätsstandards, die mit jedem Beitrag besser werden.
-</Tip>
-
-### Option 2: Expliziter Dateipfad
-
-```bash
-# Mit einer benutzerdefinierten Richtliniendatei installieren
-failproofai policies --install --custom ./my-policies.js
-
-# Den Pfad zur Richtliniendatei ersetzen
-failproofai policies --install --custom ./new-policies.js
-
-# Den benutzerdefinierten Richtlinienpfad aus der Konfiguration entfernen
-failproofai policies --uninstall --custom
-```
-
-Der aufgelöste absolute Pfad wird in `policies-config.json` als `customPoliciesPath` gespeichert. Die Datei wird bei jedem Hook-Event neu geladen – es gibt kein Caching zwischen Events.
-
-### Beide Varianten zusammen verwenden
-
-Konventionsrichtlinien und die explizite `--custom`-Datei können nebeneinander existieren. Ladereihenfolge:
-
-1. Explizite `customPoliciesPath`-Datei (falls konfiguriert)
-2. Projektkonventionsdateien (`{cwd}/.failproofai/policies/`, alphabetisch)
-3. Benutzerkonventionsdateien (`~/.failproofai/policies/`, alphabetisch)
-
----
-
-## API
-
-### Import
-
-```js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-```
-
-### `customPolicies.add(hook)`
-
-Registriert eine Richtlinie. Kann mehrfach aufgerufen werden, um mehrere Richtlinien in derselben Datei zu definieren.
-
-```ts
-customPolicies.add({
-  name: string;                         // erforderlich – eindeutiger Bezeichner
-  description?: string;                 // wird in der Ausgabe von `failproofai policies` angezeigt
-  match?: { events?: HookEventType[] }; // nach Event-Typ filtern; weglassen, um alle abzugleichen
-  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
-});
-```
-
-### Entscheidungs-Hilfsfunktionen
-
-| Funktion | Wirkung | Verwenden, wenn |
-|----------|---------|-----------------|
-| `allow()` | Operation lautlos erlauben | Die Aktion ist sicher, keine Meldung erforderlich |
-| `deny(message)` | Operation blockieren | Der Agent soll diese Aktion nicht ausführen |
-| `instruct(message)` | Kontext hinzufügen, ohne zu blockieren | Dem Agenten zusätzlichen Kontext geben, damit er auf Kurs bleibt |
-
-`deny(message)` – die Nachricht wird Claude mit dem Präfix `"Blocked by failproofai:"` angezeigt. Ein einzelnes `deny` bricht die gesamte weitere Auswertung ab.
-
-`instruct(message)` – die Nachricht wird dem Kontext von Claude für den aktuellen Tool-Aufruf hinzugefügt. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam übermittelt.
-
-<Tip>
-Du kannst jeder `deny`- oder `instruct`-Nachricht zusätzliche Hinweise hinzufügen, indem du ein `hint`-Feld in `policyParams` setzt – ohne Codeänderung. Das funktioniert auch für benutzerdefinierte (`custom/`), Projektkonventions- (`.failproofai-project/`) und Benutzerkonventionsrichtlinien (`.failproofai-user/`). Weitere Details unter [Konfiguration → hint](/de/configuration#hint-cross-cutting).
-</Tip>
-
-### Informative Allow-Nachrichten
-
-`allow(message)` erlaubt die Operation **und** sendet eine informative Nachricht an Claude. Die Nachricht wird als `additionalContext` in der stdout-Antwort des Hook-Handlers übermittelt – derselbe Mechanismus wie bei `instruct`, aber semantisch anders: Es handelt sich um eine Statusmeldung, nicht um eine Warnung.
-
-| Funktion | Wirkung | Verwenden, wenn |
-|----------|---------|-----------------|
-| `allow(message)` | Erlauben und Kontext an Claude senden | Bestätigen, dass eine Prüfung bestanden wurde, oder erklären, warum eine Prüfung übersprungen wurde |
-
-Anwendungsfälle:
-- **Statusbestätigungen:** `allow("All CI checks passed.")` – teilt Claude mit, dass alles in Ordnung ist
-- **Fail-open-Erklärungen:** `allow("GitHub CLI not installed, skipping CI check.")` – erklärt Claude, warum eine Prüfung übersprungen wurde, damit er den vollen Kontext hat
-- **Mehrere Nachrichten werden akkumuliert:** Wenn mehrere Richtlinien jeweils `allow(message)` zurückgeben, werden alle Nachrichten mit Zeilenumbrüchen verbunden und gemeinsam übermittelt
-
-```js
-customPolicies.add({
-  name: "confirm-branch-status",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    const cwd = ctx.session?.cwd;
-    if (!cwd) return allow("No working directory, skipping branch check.");
-
-    // ... Branch-Status prüfen ...
-    if (allPushed) {
-      return allow("Branch is up to date with remote.");
-    }
-    return deny("Unpushed changes detected.");
-  },
-});
-```
-
-### Felder von `PolicyContext`
-
-| Feld | Typ | Beschreibung |
-|------|-----|--------------|
-| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | Das aufgerufene Tool (z. B. `"Bash"`, `"Write"`, `"Read"`) |
-| `toolInput` | `Record<string, unknown> \| undefined` | Die Eingabeparameter des Tools |
-| `payload` | `Record<string, unknown>` | Vollständige rohe Event-Nutzlast von Claude Code |
-| `session` | `SessionMetadata \| undefined` | Sitzungskontext (siehe unten) |
-
-### Felder von `SessionMetadata`
-
-| Feld | Typ | Beschreibung |
-|------|-----|--------------|
-| `sessionId` | `string` | Claude Code-Sitzungsbezeichner |
-| `cwd` | `string` | Arbeitsverzeichnis der Claude Code-Sitzung |
-| `transcriptPath` | `string` | Pfad zur JSONL-Transkriptdatei der Sitzung |
-
-### Event-Typen
-
-| Event | Wann ausgelöst | Inhalt von `toolInput` |
-|-------|---------------|------------------------|
-| `PreToolUse` | Bevor Claude ein Tool ausführt | Die Eingabe des Tools (z. B. `{ command: "..." }` für Bash) |
-| `PostToolUse` | Nachdem ein Tool abgeschlossen ist | Die Eingabe des Tools + `tool_result` (die Ausgabe) |
-| `Notification` | Wenn Claude eine Benachrichtigung sendet | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` – Hooks müssen immer `allow()` zurückgeben, Benachrichtigungen können nicht blockiert werden |
-| `Stop` | Wenn die Claude-Sitzung endet | Leer |
-
----
-
-## Auswertungsreihenfolge
-
-Richtlinien werden in dieser Reihenfolge ausgewertet:
-
-1. Integrierte Richtlinien (in Definitionsreihenfolge)
-2. Explizite benutzerdefinierte Richtlinien aus `customPoliciesPath` (in `.add()`-Reihenfolge)
-3. Konventionsrichtlinien aus dem Projekt unter `.failproofai/policies/` (Dateien alphabetisch, `.add()`-Reihenfolge innerhalb)
-4. Konventionsrichtlinien aus dem Benutzerverzeichnis `~/.failproofai/policies/` (Dateien alphabetisch, `.add()`-Reihenfolge innerhalb)
-
-<Note>
-Das erste `deny` bricht alle nachfolgenden Richtlinien ab. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam übermittelt.
-</Note>
-
----
-
-## Transitive Imports
-
-Benutzerdefinierte Richtliniendateien können lokale Module über relative Pfade importieren:
-
-```js
-// my-policies.js
-import { isBlockedPath } from "./utils.js";
-import { checkApproval } from "./approval-client.js";
-
-customPolicies.add({
-  name: "approval-gate",
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
-    return approved ? allow() : deny("Approval required for this command");
-  },
-});
-```
-
-Alle relativen Imports, die von der Einstiegsdatei aus erreichbar sind, werden aufgelöst. Dies wird implementiert, indem `from "failproofai"`-Imports auf den tatsächlichen dist-Pfad umgeschrieben und temporäre `.mjs`-Dateien erstellt werden, um ESM-Kompatibilität sicherzustellen.
-
----
-
-## Filterung nach Event-Typ
-
-Verwende `match.events`, um einzuschränken, wann eine Richtlinie ausgelöst wird:
-
-```js
-customPolicies.add({
-  name: "require-summary-on-stop",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    // Wird nur ausgelöst, wenn die Sitzung endet
-    // ctx.session.transcriptPath enthält das vollständige Sitzungsprotokoll
-    return allow();
-  },
-});
-```
-
-Lass `match` vollständig weg, um bei jedem Event-Typ ausgelöst zu werden.
-
----
-
-## Fehlerbehandlung und Fehlermodi
-
-Benutzerdefinierte Richtlinien sind **fail-open**: Fehler blockieren niemals integrierte Richtlinien oder bringen den Hook-Handler zum Absturz.
-
-| Fehler | Verhalten |
-|--------|-----------|
-| `customPoliciesPath` nicht gesetzt | Keine expliziten benutzerdefinierten Richtlinien werden ausgeführt; Konventionsrichtlinien und integrierte Richtlinien laufen normal weiter |
-| Datei nicht gefunden | Warnung wird in `~/.failproofai/hook.log` protokolliert; integrierte Richtlinien laufen weiter |
-| Syntax-/Importfehler (explizit) | Fehler wird in `~/.failproofai/hook.log` protokolliert; explizite benutzerdefinierte Richtlinien werden übersprungen |
-| Syntax-/Importfehler (Konvention) | Fehler wird protokolliert; diese Datei wird übersprungen, andere Konventionsdateien werden weiterhin geladen |
-| `fn` wirft zur Laufzeit | Fehler wird protokolliert; dieser Hook wird als `allow` behandelt; andere Hooks laufen weiter |
-| `fn` dauert länger als 10 Sekunden | Timeout wird protokolliert; wird als `allow` behandelt |
-| Konventionsverzeichnis fehlt | Keine Konventionsrichtlinien werden ausgeführt; kein Fehler |
-
-<Tip>
-Um Fehler in benutzerdefinierten Richtlinien zu debuggen, beobachte die Protokolldatei:
-
-```bash
-tail -f ~/.failproofai/hook.log
-```
-</Tip>
-
----
-
-## Vollständiges Beispiel: Mehrere Richtlinien
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-// Verhindert, dass der Agent in das Verzeichnis secrets/ schreibt
-customPolicies.add({
-  name: "block-secrets-dir",
-  description: "Prevent agent from writing to secrets/ directory",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
-    const path = ctx.toolInput?.file_path ?? "";
-    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
-    return allow();
-  },
-});
-
-// Hält den Agenten auf Kurs: Tests vor dem Commit prüfen
-customPolicies.add({
-  name: "remind-test-before-commit",
-  description: "Keep the agent on track: verify tests pass before committing",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = ctx.toolInput?.command ?? "";
-    if (/git\s+commit/.test(cmd)) {
-      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
-    }
-    return allow();
-  },
-});
-
-// Verhindert ungeplante Abhängigkeitsänderungen während eines Freeze
-customPolicies.add({
-  name: "dependency-freeze",
-  description: "Prevent unplanned dependency changes during freeze period",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = ctx.toolInput?.command ?? "";
-    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
-    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
-      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
-    }
-    return allow();
-  },
-});
-
-export { customPolicies };
-```
-
----
-
-## Beispiele
-
-Das Verzeichnis `examples/` enthält fertige Richtliniendateien:
-
-| Datei | Inhalt |
-|-------|--------|
-| `examples/policies-basic.js` | Fünf Einstiegsrichtlinien für häufige Agenten-Fehlerszenarien |
-| `examples/policies-advanced/index.js` | Fortgeschrittene Muster: transitive Imports, asynchrone Aufrufe, Ausgabebereinigung und Sitzungsende-Hooks |
-| `examples/convention-policies/security-policies.mjs` | Konventionsbasierte Sicherheitsrichtlinien (blockiert .env-Schreibzugriffe, verhindert das Umschreiben der Git-Historie) |
-| `examples/convention-policies/workflow-policies.mjs` | Konventionsbasierte Workflow-Richtlinien (Test-Erinnerungen, Protokollierung von Dateiänderungen) |
-
-### Explizite Dateibeispiele verwenden
-
-```bash
-failproofai policies --install --custom ./examples/policies-basic.js
-```
-
-### Konventionsbasierte Beispiele verwenden
-
-```bash
-# Auf Projektebene kopieren
-mkdir -p .failproofai/policies
-cp examples/convention-policies/*.mjs .failproofai/policies/
-
-# Oder auf Benutzerebene kopieren
-mkdir -p ~/.failproofai/policies
-cp examples/convention-policies/*.mjs ~/.failproofai/policies/
-```
-
-Kein Installationsbefehl erforderlich – die Dateien werden beim nächsten Hook-Event automatisch erkannt.

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

@@ -1,142 +0,0 @@
----
-title: Dashboard
-description: "Agent-Sitzungen überwachen, Tool-Aufrufe einsehen und Richtlinien verwalten"
-icon: chart-line
----
-
-Das failproofai Dashboard ist eine lokale Webanwendung zur Überwachung deiner KI-Agent-Sitzungen und zur Verwaltung von Richtlinien. Sieh nach, was deine Agents in deiner Abwesenheit gemacht haben.
-
----
-
-## Dashboard starten
-
-```bash
-failproofai
-```
-
-Öffnet sich unter `http://localhost:8020`.
-
-Das Dashboard liest direkt aus dem Dateisystem – aus deinen Claude Code Projektordnern und den failproofai Konfigurationsdateien. Es werden keine Daten an einen externen Dienst übertragen.
-
----
-
-## Seiten
-
-### Projekte
-
-Listet alle Claude Code Projekte auf, die auf deinem Rechner gefunden wurden. Projekte werden aus `~/.claude/projects/` (oder dem über `CLAUDE_PROJECTS_PATH` festgelegten Pfad) eingelesen.
-
-Jedes Projekt zeigt:
-- Projektname (abgeleitet vom Ordnerpfad)
-- Anzahl der Sitzungen
-- Datum der letzten Sitzungsaktivität
-
-Klicke auf ein Projekt, um dessen Sitzungen anzuzeigen.
-
-### Sitzungen
-
-Listet alle Sitzungen innerhalb eines Projekts auf. Jede Sitzung zeigt:
-- Sitzungs-ID
-- Start- und Endzeitstempel
-- Anzahl der Tool-Aufrufe
-- Anzahl der Hook-Aktivitäten (ausgelöste Richtlinien)
-
-Verwende den Datumsbereichsfilter und die Sitzungs-ID-Suche, um die Liste einzugrenzen. Sitzungen werden seitenweise angezeigt.
-
-Klicke auf eine Sitzung, um den Sitzungs-Viewer zu öffnen.
-
-### Sitzungs-Viewer
-
-Der Sitzungs-Viewer beantwortet die zentrale Frage bei autonomen Agents: Was hat der Agent getan, und ist er auf Kurs geblieben? Er zeigt eine Zeitleiste aller Ereignisse einer Sitzung:
-
-- **Nachrichten** – Claudes Textantworten und Benutzeranfragen
-- **Tool-Aufrufe** – Jeder von Claude aufgerufene Tool, mit Eingabe und Ausgabe
-- **Richtlinienaktivität** – Für jeden Tool-Aufruf: welche Richtlinien ausgelöst wurden und welche Entscheidung sie zurückgegeben haben
-
-Die Statistikleiste oben zeigt Sitzungsdauer, Gesamtanzahl der Tool-Aufrufe sowie eine Zusammenfassung der Hook-Entscheidungen (Anzahl allow / deny / instruct).
-
-Du kannst die Sitzung über den Download-Button als ZIP- oder JSONL-Datei exportieren.
-
-### Richtlinien
-
-Eine Seite mit zwei Tabs zur Verwaltung von Richtlinien und zur Einsicht in Aktivitäten.
-
-<Tabs>
-  <Tab title="Policies tab">
-  - Einzelne Richtlinien per Klick aktivieren oder deaktivieren (schreibt in `~/.failproofai/policies-config.json`)
-  - Eine Richtlinie aufklappen, um ihre Parameter zu konfigurieren (für Richtlinien, die `policyParams` unterstützen)
-  - Hooks für einen bestimmten Scope installieren oder entfernen
-  - Einen benutzerdefinierten Pfad für die Richtliniendatei festlegen
-  </Tab>
-  <Tab title="Activity tab">
-  - Vollständige, seitenweise Historie aller Hook-Ereignisse, die sitzungsübergreifend ausgelöst wurden
-  - Suche nach Richtlinienname, Sitzungs-ID, Tool-Name oder Entscheidung
-  - Jede Zeile zeigt: Zeitstempel, Richtlinienname, Entscheidung, Tool-Name, Sitzungs-ID und den Grund für deny/instruct-Entscheidungen
-  </Tab>
-</Tabs>
-
----
-
-## Automatische Aktualisierung
-
-Das Dashboard verfügt über einen Auto-Refresh-Schalter in der oberen Navigation. Wenn aktiviert, wird die aktuelle Seite regelmäßig aktualisiert, um neue Sitzungen und Richtlinienaktivitäten anzuzeigen, sobald sie auftreten. Unverzichtbar für die Überwachung langläufiger autonomer Agent-Sitzungen.
-
----
-
-## Seiten deaktivieren
-
-Wenn du nur bestimmte Teile des Dashboards benötigst, setze `FAILPROOFAI_DISABLE_PAGES` auf eine kommagetrennte Liste von Seitennamen:
-
-```bash
-FAILPROOFAI_DISABLE_PAGES=policies failproofai
-```
-
-Gültige Werte: `policies`, `projects`.
-
----
-
-## Design
-
-Das Dashboard unterstützt hellen und dunklen Modus. Umschalten über den Button in der Navigationsleiste. Die Einstellung wird im lokalen Speicher deines Browsers gespeichert.
-
----
-
-## Projektpfad konfigurieren
-
-Standardmäßig liest das Dashboard aus dem Standard-Claude Code Projektverzeichnis. Für individuelle Setups lässt sich dieser Pfad überschreiben:
-
-```bash
-CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
-```
-
----
-
-## Zugriff von einem Nicht-localhost-Host
-
-Wenn du das Dashboard im **Dev-Modus** (`npm run dev`) ausführst und von einem anderen Hostnamen als `localhost` darauf zugreifst – beispielsweise einer benutzerdefinierten Domain, einer Remote-IP oder einer getunnelten URL – kann folgende Warnung erscheinen:
-
-```text
-⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
-```
-
-Dabei blockiert Next.js den Cross-Origin-Zugriff auf seinen HMR-Websocket (Hot Module Reload), was ein ausschließlich im Dev-Modus vorhandenes Feature ist. Um deinen Host zuzulassen, verwende das Flag `--allowed-origins`:
-
-```bash
-npm run dev -- --allowed-origins dashboard.example.com
-```
-
-Für mehrere Hosts oder IPs wird eine kommagetrennte Liste übergeben:
-
-```bash
-npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
-```
-
-Alternativ kann die Umgebungsvariable `FAILPROOFAI_ALLOWED_DEV_ORIGINS` gesetzt werden:
-
-```bash
-FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
-```
-
-<Note>
-Dies gilt ausschließlich für den Dev-Modus. Beim Ausführen von `failproofai` (Produktionsmodus) gibt es keinen HMR-Websocket und kein Cross-Origin-Problem mit Dev-Ressourcen.
-</Note>