failproofai 0.0.2-beta.8 → 0.0.2-beta.9

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

@@ -0,0 +1,357 @@
+---
+title: Politiques personnalisées
+description: "Écrivez vos propres politiques en JavaScript — appliquez des conventions, prévenez la dérive, détectez les échecs, intégrez des systèmes externes"
+icon: code
+---
+
+Les politiques personnalisées vous permettent d'écrire des règles pour n'importe quel comportement d'agent : appliquer des conventions de projet, prévenir la dérive, bloquer les opérations destructrices, détecter les agents bloqués, ou s'intégrer avec Slack, des workflows d'approbation, et bien plus. Elles utilisent le même système d'événements hook et les mêmes décisions `allow`, `deny`, `instruct` que les politiques intégrées.
+
+---
+
+## Exemple rapide
+
+```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();
+  },
+});
+```
+
+Installez-le :
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Deux façons de charger des politiques personnalisées
+
+### Option 1 : Par convention (recommandé, v0.0.2-beta.7+)
+
+Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et ils sont chargés automatiquement — aucun indicateur ni changement de configuration requis. Cela fonctionne comme les git hooks : déposez un fichier, il est pris en compte immédiatement.
+
+```
+# Niveau projet — commité dans git, partagé avec l'équipe
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# Niveau utilisateur — personnel, s'applique à tous les projets
+~/.failproofai/policies/my-policies.mjs
+```
+
+**Comment ça fonctionne :**
+- Les répertoires projet et utilisateur sont tous deux analysés (union — pas de priorité au premier scope)
+- Les fichiers sont chargés alphabétiquement dans chaque répertoire. Préfixez avec `01-`, `02-` pour contrôler l'ordre
+- Seuls les fichiers correspondant à `*policies.{js,mjs,ts}` sont chargés ; les autres fichiers sont ignorés
+- Chaque fichier est chargé indépendamment (fail-open par fichier)
+- Fonctionne en parallèle avec les indicateurs `--custom` explicites et les politiques intégrées
+
+<Tip>
+Les politiques par convention sont le moyen le plus simple de partager des politiques au sein d'une équipe. Commitez `.failproofai/policies/` dans git et chaque membre de l'équipe les reçoit automatiquement.
+</Tip>
+
+### Option 2 : Chemin de fichier explicite
+
+```bash
+# Installer avec un fichier de politiques personnalisées
+failproofai policies --install --custom ./my-policies.js
+
+# Remplacer le chemin du fichier de politiques
+failproofai policies --install --custom ./new-policies.js
+
+# Supprimer le chemin de politiques personnalisées de la configuration
+failproofai policies --uninstall --custom
+```
+
+Le chemin absolu résolu est stocké dans `policies-config.json` sous `customPoliciesPath`. Le fichier est chargé à nouveau à chaque événement hook — aucune mise en cache entre les événements.
+
+### Utiliser les deux ensemble
+
+Les politiques par convention et le fichier `--custom` explicite peuvent coexister. Ordre de chargement :
+
+1. Fichier `customPoliciesPath` explicite (si configuré)
+2. Fichiers de convention projet (`{cwd}/.failproofai/policies/`, alphabétique)
+3. Fichiers de convention utilisateur (`~/.failproofai/policies/`, alphabétique)
+
+---
+
+## API
+
+### Import
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Enregistre une politique. Appelez cette méthode autant de fois que nécessaire pour plusieurs politiques dans le même fichier.
+
+```ts
+customPolicies.add({
+  name: string;                         // obligatoire - identifiant unique
+  description?: string;                 // affiché dans la sortie de `failproofai policies`
+  match?: { events?: HookEventType[] }; // filtrer par type d'événement ; omettre pour tout correspondre
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Fonctions d'aide aux décisions
+
+| Fonction | Effet | Utiliser quand |
+|----------|--------|----------|
+| `allow()` | Autorise l'opération silencieusement | L'action est sûre, aucun message nécessaire |
+| `deny(message)` | Bloque l'opération | L'agent ne doit pas effectuer cette action |
+| `instruct(message)` | Ajoute du contexte sans bloquer | Fournir à l'agent du contexte supplémentaire pour rester sur la bonne voie |
+
+`deny(message)` — le message apparaît à Claude préfixé par `"Blocked by failproofai:"`. Un seul `deny` court-circuite toute évaluation ultérieure.
+
+`instruct(message)` — le message est ajouté au contexte de Claude pour l'appel d'outil en cours. Tous les messages `instruct` sont accumulés et délivrés ensemble.
+
+<Tip>
+Vous pouvez ajouter des instructions supplémentaires à n'importe quel message `deny` ou `instruct` en ajoutant un champ `hint` dans `policyParams` — sans modifier le code. Cela fonctionne également pour les politiques personnalisées (`custom/`), par convention projet (`.failproofai-project/`) et par convention utilisateur (`.failproofai-user/`). Voir [Configuration → hint](/fr/configuration#hint-cross-cutting) pour les détails.
+</Tip>
+
+### Messages allow informationnels (bêta)
+
+<Note>
+`allow(message)` est une fonctionnalité bêta disponible depuis la v0.0.2-beta.3. L'API peut changer dans les versions futures. Les versions antérieures ne prennent en charge que `allow()` sans arguments.
+</Note>
+
+`allow(message)` autorise l'opération **et** envoie un message informationnel à Claude. Le message est délivré en tant que `additionalContext` dans la réponse stdout du gestionnaire de hook — le même mécanisme qu'`instruct`, mais sémantiquement différent : c'est une mise à jour de statut, pas un avertissement.
+
+| Fonction | Effet | Utiliser quand |
+|----------|--------|----------|
+| `allow(message)` | Autorise et envoie du contexte à Claude | Confirmer qu'une vérification a réussi, ou expliquer pourquoi une vérification a été ignorée |
+
+Cas d'utilisation :
+- **Confirmations de statut :** `allow("All CI checks passed.")` — indique à Claude que tout est en ordre
+- **Explications fail-open :** `allow("GitHub CLI not installed, skipping CI check.")` — indique à Claude pourquoi une vérification a été ignorée pour qu'il ait le contexte complet
+- **Accumulation de messages multiples :** si plusieurs politiques retournent chacune `allow(message)`, tous les messages sont joints par des sauts de ligne et délivrés ensemble
+
+```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.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### Champs de `PolicyContext`
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | L'outil appelé (ex. `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | Les paramètres d'entrée de l'outil |
+| `payload` | `Record<string, unknown>` | Payload brut complet de l'événement provenant de Claude Code |
+| `session` | `SessionMetadata \| undefined` | Contexte de session (voir ci-dessous) |
+
+### Champs de `SessionMetadata`
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `sessionId` | `string` | Identifiant de session Claude Code |
+| `cwd` | `string` | Répertoire de travail de la session Claude Code |
+| `transcriptPath` | `string` | Chemin vers le fichier de transcription JSONL de la session |
+
+### Types d'événements
+
+| Événement | Quand il se déclenche | Contenu de `toolInput` |
+|-------|--------------|----------------------|
+| `PreToolUse` | Avant que Claude exécute un outil | L'entrée de l'outil (ex. `{ command: "..." }` pour Bash) |
+| `PostToolUse` | Après qu'un outil se termine | L'entrée de l'outil + `tool_result` (la sortie) |
+| `Notification` | Quand Claude envoie une notification | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — les hooks doivent toujours retourner `allow()`, ils ne peuvent pas bloquer les notifications |
+| `Stop` | Quand la session Claude se termine | Vide |
+
+---
+
+## Ordre d'évaluation
+
+Les politiques sont évaluées dans cet ordre :
+
+1. Politiques intégrées (dans l'ordre de définition)
+2. Politiques personnalisées explicites de `customPoliciesPath` (dans l'ordre `.add()`)
+3. Politiques de convention projet `.failproofai/policies/` (fichiers alphabétiques, ordre `.add()` à l'intérieur)
+4. Politiques de convention utilisateur `~/.failproofai/policies/` (fichiers alphabétiques, ordre `.add()` à l'intérieur)
+
+<Note>
+Le premier `deny` court-circuite toutes les politiques suivantes. Tous les messages `instruct` sont accumulés et délivrés ensemble.
+</Note>
+
+---
+
+## Imports transitifs
+
+Les fichiers de politiques personnalisées peuvent importer des modules locaux en utilisant des chemins relatifs :
+
+```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");
+  },
+});
+```
+
+Tous les imports relatifs accessibles depuis le fichier d'entrée sont résolus. Cela est implémenté en réécrivant les imports `from "failproofai"` vers le chemin dist réel et en créant des fichiers `.mjs` temporaires pour assurer la compatibilité ESM.
+
+---
+
+## Filtrage par type d'événement
+
+Utilisez `match.events` pour limiter le déclenchement d'une politique :
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Ne se déclenche que lorsque la session se termine
+    // ctx.session.transcriptPath contient le journal complet de la session
+    return allow();
+  },
+});
+```
+
+Omettez `match` entièrement pour se déclencher sur chaque type d'événement.
+
+---
+
+## Gestion des erreurs et modes de défaillance
+
+Les politiques personnalisées sont **fail-open** : les erreurs ne bloquent jamais les politiques intégrées ni ne font planter le gestionnaire de hook.
+
+| Défaillance | Comportement |
+|---------|----------|
+| `customPoliciesPath` non défini | Aucune politique personnalisée explicite ne s'exécute ; les politiques de convention et les politiques intégrées continuent normalement |
+| Fichier introuvable | Avertissement consigné dans `~/.failproofai/hook.log` ; les politiques intégrées continuent |
+| Erreur de syntaxe/import (explicite) | Erreur consignée dans `~/.failproofai/hook.log` ; politiques personnalisées explicites ignorées |
+| Erreur de syntaxe/import (convention) | Erreur consignée ; ce fichier ignoré, les autres fichiers de convention se chargent quand même |
+| `fn` lève une exception à l'exécution | Erreur consignée ; ce hook traité comme `allow` ; les autres hooks continuent |
+| `fn` prend plus de 10s | Timeout consigné ; traité comme `allow` |
+| Répertoire de convention manquant | Aucune politique de convention ne s'exécute ; aucune erreur |
+
+<Tip>
+Pour déboguer les erreurs de politiques personnalisées, surveillez le fichier journal :
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Exemple complet : plusieurs politiques
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Prevent agent from writing to secrets/ directory
+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();
+  },
+});
+
+// Keep the agent on track: verify tests before committing
+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();
+  },
+});
+
+// Prevent unplanned dependency changes during 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 };
+```
+
+---
+
+## Exemples
+
+Le répertoire `examples/` contient des fichiers de politiques prêts à l'emploi :
+
+| Fichier | Contenu |
+|------|----------|
+| `examples/policies-basic.js` | Cinq politiques de démarrage couvrant les modes d'échec courants des agents |
+| `examples/policies-advanced/index.js` | Patterns avancés : imports transitifs, appels asynchrones, nettoyage de sortie et hooks de fin de session |
+| `examples/convention-policies/security-policies.mjs` | Politiques de sécurité par convention (bloquer les écritures .env, empêcher la réécriture de l'historique git) |
+| `examples/convention-policies/workflow-policies.mjs` | Politiques de workflow par convention (rappels de tests, audit des écritures de fichiers) |
+
+### Utiliser les exemples de fichiers explicites
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Utiliser les exemples par convention
+
+```bash
+# Copier au niveau projet
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Ou copier au niveau utilisateur
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+Aucune commande d'installation requise — les fichiers sont pris en compte automatiquement au prochain événement hook.

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

@@ -0,0 +1,142 @@
+---
+title: Tableau de bord
+description: "Surveillez les sessions des agents, examinez les appels d'outils et gérez les politiques"
+icon: chart-line
+---
+
+Le tableau de bord failproofai est une application web locale permettant de surveiller les sessions de vos agents IA et de gérer les politiques. Voyez ce que vos agents ont fait pendant votre absence.
+
+---
+
+## Démarrer le tableau de bord
+
+```bash
+failproofai
+```
+
+S'ouvre à l'adresse `http://localhost:8020`.
+
+Le tableau de bord lit directement depuis le système de fichiers — vos dossiers de projets Claude Code et les fichiers de configuration failproofai. Aucune donnée n'est envoyée vers un service distant.
+
+---
+
+## Pages
+
+### Projets
+
+Liste tous les projets Claude Code trouvés sur votre machine. Les projets sont découverts depuis `~/.claude/projects/` (ou le chemin défini par `CLAUDE_PROJECTS_PATH`).
+
+Chaque projet affiche :
+- Le nom du projet (dérivé du chemin du dossier)
+- Le nombre de sessions
+- La date de la dernière activité de session
+
+Cliquez sur un projet pour voir ses sessions.
+
+### Sessions
+
+Liste toutes les sessions d'un projet. Chaque session affiche :
+- L'identifiant de session
+- Les horodatages de début et de fin
+- Le nombre d'appels d'outils
+- Le nombre d'activités de hook (politiques déclenchées)
+
+Utilisez le filtre par plage de dates et la recherche par identifiant de session pour affiner la liste. Les sessions sont paginées.
+
+Cliquez sur une session pour ouvrir le visualiseur de session.
+
+### Visualiseur de session
+
+Le visualiseur de session répond à la question clé pour les agents autonomes : qu'a fait l'agent, et est-il resté sur la bonne voie ? Il affiche une chronologie de tout ce qui s'est passé lors d'une session :
+
+- **Messages** - Les réponses textuelles de Claude et les invites de l'utilisateur
+- **Appels d'outils** - Chaque outil invoqué par Claude, avec ses entrées et sorties
+- **Activité des politiques** - Pour chaque appel d'outil, quelles politiques ont été déclenchées et quelle décision elles ont rendue
+
+La barre de statistiques en haut affiche la durée de la session, le nombre total d'appels d'outils et un résumé des décisions de hook (compteurs allow / deny / instruct).
+
+Vous pouvez exporter la session sous forme de fichier ZIP ou JSONL à l'aide du bouton de téléchargement.
+
+### Politiques
+
+Une page à deux onglets pour gérer les politiques et consulter l'activité.
+
+<Tabs>
+  <Tab title="Onglet Politiques">
+  - Activez ou désactivez individuellement les politiques d'un simple clic (écrit dans `~/.failproofai/policies-config.json`)
+  - Développez une politique pour configurer ses paramètres (pour les politiques qui prennent en charge `policyParams`)
+  - Installez ou supprimez des hooks pour un scope donné
+  - Définissez un chemin personnalisé vers un fichier de politiques
+  </Tab>
+  <Tab title="Onglet Activité">
+  - Historique paginé complet de tous les événements de hook déclenchés dans toutes les sessions
+  - Recherchez par nom de politique, identifiant de session, nom d'outil ou décision
+  - Chaque ligne affiche : horodatage, nom de politique, décision, nom d'outil, identifiant de session et la raison des décisions deny/instruct
+  </Tab>
+</Tabs>
+
+---
+
+## Actualisation automatique
+
+Le tableau de bord dispose d'un bouton d'actualisation automatique dans la navigation supérieure. Lorsqu'il est activé, la page courante se rafraîchit périodiquement pour afficher les nouvelles sessions et l'activité des politiques au fur et à mesure qu'elles apparaissent. Indispensable pour surveiller des sessions d'agents autonomes de longue durée.
+
+---
+
+## Désactiver des pages
+
+Si vous n'avez besoin que de certaines parties du tableau de bord, définissez `FAILPROOFAI_DISABLE_PAGES` avec une liste de noms de pages séparés par des virgules :
+
+```bash
+FAILPROOFAI_DISABLE_PAGES=policies failproofai
+```
+
+Valeurs valides : `policies`, `projects`.
+
+---
+
+## Thème
+
+Le tableau de bord prend en charge les modes clair et sombre. Basculez entre les deux via le bouton dans la barre de navigation. La préférence est enregistrée dans le stockage local de votre navigateur.
+
+---
+
+## Configurer le chemin des projets
+
+Par défaut, le tableau de bord lit depuis le répertoire standard des projets Claude Code. Remplacez-le pour des configurations personnalisées :
+
+```bash
+CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
+```
+
+---
+
+## Accès depuis un hôte autre que localhost
+
+Lorsque vous exécutez le tableau de bord en **mode développement** (`npm run dev`) et que vous y accédez depuis un nom d'hôte autre que `localhost` — par exemple, un domaine personnalisé, une IP distante ou une URL tunnelisée — vous pouvez voir un avertissement du type :
+
+```text
+⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
+```
+
+Il s'agit de Next.js qui bloque l'accès cross-origin à son websocket HMR (rechargement à chaud des modules), une fonctionnalité réservée au développement. Pour autoriser votre hôte, utilisez le flag `--allowed-origins` :
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com
+```
+
+Pour plusieurs hôtes ou adresses IP, passez une liste séparée par des virgules :
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
+```
+
+Vous pouvez également définir la variable d'environnement `FAILPROOFAI_ALLOWED_DEV_ORIGINS` à la place :
+
+```bash
+FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
+```
+
+<Note>
+Ceci s'applique uniquement au mode développement. Lors de l'exécution de `failproofai` (mode production), il n'y a pas de websocket HMR ni de problème de ressource cross-origin en développement.
+</Note>