failproofai 0.0.6-beta.3 → 0.0.6-beta.5

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

@@ -1,353 +0,0 @@
----
-title: Politiques personnalisées
-description: "Rédigez vos propres politiques en JavaScript — appliquez des conventions de projet, évitez 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, contrôler les opérations destructrices, détecter les agents bloqués, ou s'intégrer avec Slack, des workflows d'approbation, et plus encore. 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é)
-
-Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et ils sont chargés automatiquement — sans indicateurs ni modifications de configuration. Cela fonctionne comme les hooks git : déposez un fichier, ça fonctionne.
-
-```
-# 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é par périmètre)
-- Les fichiers sont chargés par ordre alphabétique 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 avec les politiques `--custom` explicites et les politiques intégrées
-
-<Tip>
-Les politiques par convention sont le moyen le plus simple de définir un standard de qualité pour votre organisation. Commitez `.failproofai/policies/` dans git et chaque membre de l'équipe obtient les mêmes règles automatiquement — aucune configuration individuelle requise. Au fil des découvertes de nouveaux modes d'échec, ajoutez une politique et poussez. Ces politiques deviennent avec le temps un standard de qualité vivant qui s'améliore à chaque contribution.
-</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 des 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 — il n'y a pas de 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 du 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 fonction autant de fois que nécessaire pour plusieurs politiques dans le même fichier.
-
-```ts
-customPolicies.add({
-  name: string;                         // requis - 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 | Donner à l'agent un contexte supplémentaire pour rester sur la bonne voie |
-
-`deny(message)` — le message apparaît à Claude préfixé de `"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 transmis ensemble.
-
-<Tip>
-Vous pouvez ajouter des instructions supplémentaires à n'importe quel message `deny` ou `instruct` en ajoutant un champ `hint` dans `policyParams` — sans modification de code. Cela fonctionne également pour les politiques personnalisées (`custom/`), par convention de projet (`.failproofai-project/`) et par convention utilisateur (`.failproofai-user/`). Consultez [Configuration → hint](/fr/configuration#hint-cross-cutting) pour plus de détails.
-</Tip>
-
-### Messages allow informatifs
-
-`allow(message)` autorise l'opération **et** envoie un message informatif à Claude. Le message est transmis en tant qu'`additionalContext` dans la réponse stdout du gestionnaire de hook — le même mécanisme utilisé par `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'usage :
-- **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 afin qu'il dispose du contexte complet
-- **Accumulation de plusieurs messages :** si plusieurs politiques retournent chacune `allow(message)`, tous les messages sont joints avec des sauts de ligne et transmis 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>` | Charge utile brute complète de l'événement depuis 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 qu'un outil soit exécuté par Claude | L'entrée de l'outil (ex. `{ command: "..." }` pour Bash) |
-| `PostToolUse` | Après la fin d'un outil | 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 depuis `customPoliciesPath` (dans l'ordre de `.add()`)
-3. Politiques de convention du 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 transmis ensemble.
-</Note>
-
----
-
-## Imports transitifs
-
-Les fichiers de politiques personnalisées peuvent importer des modules locaux via 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. Ceci 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 d'échec
-
-Les politiques personnalisées sont **fail-open** : les erreurs ne bloquent jamais les politiques intégrées et ne font pas planter le gestionnaire de hook.
-
-| Échec | Comportement |
-|---------|----------|
-| `customPoliciesPath` non défini | Aucune politique personnalisée explicite n'est exécutée ; les politiques par convention et 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 est ignoré, les autres fichiers de convention sont toujours chargés |
-| `fn` lève une exception à l'exécution | Erreur consignée ; ce hook est traité comme `allow` ; les autres hooks continuent |
-| `fn` prend plus de 10 secondes | Timeout consigné ; traité comme `allow` |
-| Répertoire de convention manquant | Aucune politique de convention n'est exécutée ; aucune erreur |
-
-<Tip>
-Pour déboguer les erreurs de politiques personnalisées, surveillez le fichier de log :
-
-```bash
-tail -f ~/.failproofai/hook.log
-```
-</Tip>
-
----
-
-## Exemple complet : plusieurs politiques
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-// Empêche l'agent d'écrire dans le répertoire secrets/
-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();
-  },
-});
-
-// Maintient l'agent sur la bonne voie : vérifier les tests avant de commiter
-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();
-  },
-});
-
-// Empêche les modifications de dépendances non planifiées pendant le gel
-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` | Modèles 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 n'est nécessaire — les fichiers sont automatiquement détectés au prochain événement hook.

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

@@ -1,142 +0,0 @@
----
-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>