failproofai 0.0.2 → 0.0.4-beta.0

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>

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

@@ -0,0 +1,253 @@
+---
+title: Exemples
+description: "Comment configurer des hooks pour Claude Code et le Agents SDK"
+icon: book-open
+---
+
+Des exemples prêts à l'emploi pour les scénarios courants. Chacun montre comment installer et ce que vous pouvez attendre.
+
+---
+
+## Configurer des hooks pour Claude Code
+
+Failproof AI s'intègre à Claude Code via son [système de hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Lorsque vous exécutez `failproofai policies --install`, il enregistre des commandes de hooks dans le fichier `settings.json` de Claude Code, qui se déclenchent à chaque appel d'outil.
+
+<Steps>
+  <Step title="Installer failproofai">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="Activer toutes les politiques intégrées">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="Vérifier que les hooks sont enregistrés">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    Vous devriez voir des entrées de hooks pour les événements `PreToolUse`, `PostToolUse`, `Notification` et `Stop`.
+  </Step>
+  <Step title="Lancer Claude Code">
+    ```bash
+    claude
+    ```
+
+    Les politiques s'exécutent désormais automatiquement à chaque appel d'outil. Essayez de demander à Claude d'exécuter `sudo rm -rf /` — cela sera bloqué.
+  </Step>
+</Steps>
+
+---
+
+## Configurer des hooks pour le Agents SDK
+
+Si vous développez avec le [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), vous pouvez utiliser le même système de hooks par programmation.
+
+<Steps>
+  <Step title="Installer failproofai dans votre projet">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="Configurer les hooks dans votre agent">
+    Passez des commandes de hooks lors de la création de votre processus agent. Les hooks se déclenchent de la même manière que dans Claude Code — via stdin/stdout JSON :
+
+    ```bash
+    failproofai --hook PreToolUse   # appelé avant chaque outil
+    failproofai --hook PostToolUse  # appelé après chaque outil
+    ```
+  </Step>
+  <Step title="Écrire une politique personnalisée pour votre agent">
+    ```javascript
+    import { customPolicies, allow, deny } from "failproofai";
+
+    customPolicies.add({
+      name: "limit-to-project-dir",
+      description: "Keep the agent inside the project directory",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        const path = String(ctx.toolInput?.file_path ?? "");
+        if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
+          return deny("Agent is restricted to the project directory");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="Installer la politique personnalisée">
+    ```bash
+    failproofai policies --install --custom ./my-agent-policies.js
+    ```
+  </Step>
+</Steps>
+
+---
+
+## Bloquer les commandes destructives
+
+La configuration la plus courante — empêcher les agents de causer des dommages irréversibles.
+
+```bash
+failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
+```
+
+Ce que ça fait :
+- `block-sudo` — bloque toutes les commandes `sudo`
+- `block-rm-rf` — bloque la suppression récursive de fichiers
+- `block-force-push` — bloque les `git push --force`
+- `block-curl-pipe-sh` — bloque le piping de scripts distants vers le shell
+
+---
+
+## Prévenir les fuites de secrets
+
+Empêchez les agents de voir ou de divulguer des identifiants dans la sortie des outils.
+
+```bash
+failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
+```
+
+Ces politiques se déclenchent sur `PostToolUse` — après l'exécution d'un outil, elles nettoient la sortie avant que l'agent ne la voie.
+
+---
+
+## Recevoir des alertes Slack quand les agents ont besoin d'attention
+
+Utilisez le hook de notification pour transmettre les alertes d'inactivité vers Slack.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "slack-on-idle",
+  description: "Alert Slack when the agent is waiting for input",
+  match: { events: ["Notification"] },
+  fn: async (ctx) => {
+    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
+    if (!webhookUrl) return allow();
+
+    const message = String(ctx.payload?.message ?? "Agent is waiting");
+    const project = ctx.session?.cwd ?? "unknown";
+
+    try {
+      await fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          text: `*${message}*\nProject: \`${project}\``,
+        }),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch {
+      // ne jamais bloquer l'agent si Slack est inaccessible
+    }
+
+    return allow();
+  },
+});
+```
+
+Installez-le :
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
+```
+
+---
+
+## Maintenir les agents sur une branche
+
+Empêchez les agents de changer de branche ou de pousser vers des branches protégées.
+
+```javascript
+import { customPolicies, allow, deny } from "failproofai";
+
+customPolicies.add({
+  name: "stay-on-branch",
+  description: "Prevent the agent from checking out other branches",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
+      return deny("Stay on the current branch. Create a new branch with -b if needed.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## Exiger des tests avant les commits
+
+Rappelez aux agents d'exécuter les tests avant de committer.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "test-before-commit",
+  description: "Remind the agent to run tests before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## Verrouiller un dépôt de production
+
+Commitez une configuration au niveau du projet pour que tous les développeurs de votre équipe bénéficient des mêmes politiques.
+
+Créez `.failproofai/policies-config.json` dans votre dépôt :
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-force-push",
+    "block-push-master",
+    "block-env-files",
+    "sanitize-api-keys",
+    "sanitize-jwt"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "production"]
+    }
+  }
+}
+```
+
+Puis commitez-le :
+
+```bash
+git add .failproofai/policies-config.json
+git commit -m "Add failproofai team policies"
+```
+
+Chaque membre de l'équipe ayant failproofai installé récupérera automatiquement ces règles.
+
+---
+
+## Plus d'exemples
+
+Le répertoire [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) du dépôt contient :
+
+| Fichier | Ce qu'il illustre |
+|---------|-------------------|
+| `policies-basic.js` | Politiques de démarrage — bloquer les écritures en production, les force-push et les scripts pipés |
+| `policies-notification.js` | Alertes Slack pour les notifications d'inactivité et la fin de session |
+| `policies-advanced/index.js` | Imports transitifs, hooks asynchrones, nettoyage de la sortie `PostToolUse`, gestion de l'événement `Stop` |

package/.next/standalone/docs/fr/for-agents.mdx

@@ -0,0 +1,38 @@
+---
+title: "Pour les agents"
+description: "Ajoutez les connaissances Failproof AI à votre agent de codage en une seule commande. Compatible avec Claude Code, Cursor, Windsurf, et bien plus."
+---
+
+Ajoutez l'intégralité de la référence Failproof AI à votre agent de codage en une seule commande. Compatible avec Claude Code, Cursor, Windsurf, et tout autre agent prenant en charge les skills.
+
+```bash
+npx skills add https://docs.befailproof.ai
+```
+
+`npx skills` détecte les agents installés sur votre machine et ajoute le skill dans le format approprié pour chacun d'eux automatiquement.
+
+## Ce que couvre le skill
+
+| Domaine | Contenu |
+|---------|---------|
+| Politiques | Noms des politiques intégrées, types d'événements, paramètres, activation/désactivation |
+| Politiques personnalisées | `customPolicies.add()`, filtres de correspondance, API `allow`/`deny`/`instruct` |
+| Objet de contexte | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` |
+| Configuration | Structure de `policies-config.json`, fusion des portées, `policyParams` |
+| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, portées |
+| Tableau de bord | Visualiseur de sessions, activité des politiques, variables d'environnement |
+| Architecture | Flux du gestionnaire de hooks, codes de sortie, contrat stdin/stdout |
+
+## Le skill est-il complet ?
+
+Mintlify génère `llms.txt` à partir de toutes les pages de la navigation. La documentation Failproof AI couvre l'intégralité de l'API — chaque politique, option et exemple est inclus. Si vous constatez qu'il manque quelque chose, la source est disponible à l'adresse `https://docs.befailproof.ai/llms-full.txt`.
+
+Pour un contexte ciblé, créez un lien directement vers une page spécifique :
+
+```bash
+# Uniquement l'API des politiques personnalisées
+npx skills add https://docs.befailproof.ai/custom-policies
+
+# Uniquement les politiques intégrées
+npx skills add https://docs.befailproof.ai/built-in-policies
+```

package/.next/standalone/docs/fr/getting-started.mdx

@@ -0,0 +1,134 @@
+---
+title: Démarrage rapide
+description: "Installez failproofai, activez les politiques et laissez vos agents s'exécuter de manière fiable"
+icon: rocket
+---
+
+## Prérequis
+
+- **Node.js** >= 20.9.0
+- **Bun** >= 1.3.0 (optionnel - uniquement nécessaire pour compiler depuis les sources)
+
+---
+
+## Installation
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+---
+
+## Démarrage rapide
+
+<Steps>
+  <Step title="Activer les politiques">
+    Les politiques sont des règles qui s'exécutent avant et après chaque appel d'outil de l'agent. Elles interceptent les commandes destructrices, les fuites de secrets et autres modes de défaillance avant qu'ils ne causent des dommages.
+
+    ```bash
+    failproofai policies --install
+    ```
+
+    Cela écrit des entrées de hook dans le fichier `settings.json` de Claude Code. Vous pouvez également installer pour un seul projet ou choisir des politiques spécifiques :
+
+    ```bash
+    failproofai policies --install --scope project
+    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
+    ```
+  </Step>
+  <Step title="Vérifier">
+    ```bash
+    failproofai policies
+    ```
+
+    Affiche toutes les politiques, leur état d'activation et les paramètres configurés.
+  </Step>
+  <Step title="Lancer le tableau de bord">
+    ```bash
+    failproofai
+    ```
+
+    Ouvre un tableau de bord local à l'adresse `http://localhost:8020` où vous pouvez parcourir les sessions, inspecter les appels d'outils et gérer les politiques.
+  </Step>
+  <Step title="Exécuter votre agent">
+    Démarrez Claude Code comme d'habitude. Si l'agent tente quelque chose de risqué, failproofai l'intercepte automatiquement. Laissez-le tourner sans surveillance et consultez ce qui s'est passé dans le tableau de bord.
+  </Step>
+</Steps>
+
+---
+
+## Comment fonctionnent les politiques
+
+Chaque fois qu'un agent exécute un outil, Claude Code appelle failproofai en tant que sous-processus :
+
+```text
+Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
+                                                 evaluates policies
+                                                 writes decision to stdout
+```
+
+Chaque politique retourne l'une des trois décisions suivantes :
+
+- **allow** - l'agent continue normalement
+- **deny** - l'action est bloquée, l'agent est informé de la raison
+- **instruct** - du contexte supplémentaire est ajouté au prompt de l'agent
+
+<Note>
+Les politiques s'exécutent dans votre processus local. Aucune donnée n'est envoyée à un service distant.
+</Note>
+
+---
+
+## Stockage des données
+
+Toute la configuration et les journaux restent sur votre machine :
+
+| Chemin | Contenu |
+|--------|---------|
+| `~/.failproofai/policies-config.json` | Configuration globale des politiques |
+| `~/.failproofai/hook-activity.jsonl` | Historique d'exécution des hooks |
+| `~/.failproofai/hook.log` | Journal de débogage pour les erreurs de hooks personnalisés |
+| `.failproofai/policies-config.json` | Configuration par projet (validée dans le dépôt) |
+| `.failproofai/policies-config.local.json` | Remplacements personnels (ignorés par git) |
+
+---
+
+## Désinstallation
+
+```bash
+failproofai policies --uninstall
+```
+
+Supprime les entrées de hook du fichier `~/.claude/settings.json`. Les fichiers de configuration dans `~/.failproofai/` sont conservés.
+
+---
+
+## Étapes suivantes
+
+<CardGroup cols={2}>
+
+<Card title="Configuration" icon="gear" href="/fr/configuration">
+  Périmètres et format des fichiers de configuration
+</Card>
+
+<Card title="Politiques intégrées" icon="shield" href="/fr/built-in-policies">
+  Les 26 politiques avec leurs paramètres
+</Card>
+
+<Card title="Politiques personnalisées" icon="code" href="/fr/custom-policies">
+  Écrivez vos propres politiques en JavaScript
+</Card>
+
+<Card title="Moniteur d'agents" icon="chart-line" href="/fr/dashboard">
+  Surveillez les sessions et consultez l'activité des politiques
+</Card>
+
+</CardGroup>

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

@@ -0,0 +1,57 @@
+---
+title: Failproof AI
+description: "Gérez les hooks et les politiques qui maintiennent vos agents IA fiables et autonomes"
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+Des hooks et des politiques qui maintiennent vos agents IA fiables et autonomes - pour **Claude Code** et le **Agents SDK**.
+
+Les agents IA échouent de manière prévisible. Ils exécutent des commandes destructrices, exposent des secrets, dérivent hors sujet, se retrouvent bloqués dans des boucles ou poussent directement vers la branche principale. Sans surveillance, les petites défaillances s'enchaînent.
+
+Failproof AI résout ce problème grâce aux **politiques** - des règles qui s'intègrent à chaque appel d'outil de l'agent et peuvent **détecter les défaillances**, **les atténuer** (bloquer, instruire, assainir) et **vous alerter** lorsqu'une intervention est nécessaire. Un tableau de bord local vous permet de tout passer en revue par la suite.
+
+Tout s'exécute localement. Aucune donnée ne quitte votre machine.
+
+## Démarrer
+
+<CardGroup cols={2}>
+
+<Card title="26 politiques intégrées" icon="shield" href="/fr/built-in-policies">
+  Bloquez les commandes destructrices, empêchez les fuites de secrets, maintenez les agents dans les limites du projet, et bien plus encore - directement intégré.
+</Card>
+
+<Card title="Politiques personnalisées" icon="code" href="/fr/custom-policies">
+  Écrivez vos propres règles en JavaScript avec une API simple allow / deny / instruct.
+</Card>
+
+<Card title="Moniteur d'agents" icon="chart-line" href="/fr/dashboard">
+  Voyez ce que vos agents ont fait pendant votre absence. Parcourez les sessions, inspectez les appels d'outils, examinez où les politiques se sont déclenchées.
+</Card>
+
+<Card title="Configuration simplifiée" icon="gear" href="/fr/configuration">
+  Ajustez n'importe quelle politique sans code. Définissez des listes d'autorisation, des branches protégées ou des seuils par projet ou globalement.
+</Card>
+
+</CardGroup>
+
+## Démarrage rapide
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # activer les politiques
+failproofai                      # lancer le tableau de bord
+```
+
+Consultez le guide [Premiers pas](/fr/getting-started) pour une présentation complète.