failproofai 1.0.1-beta.1 → 1.0.2-beta.0

package/.next/standalone/docs-old/examples.mdx

@@ -0,0 +1,307 @@
+---
+title: Examples
+description: "How to set up hooks for Claude Code and the Agents SDK"
+icon: book-open
+---
+
+Ready-to-use examples for common scenarios. Each one shows how to install and what to expect.
+
+---
+
+## Setting up hooks for Claude Code
+
+Failproof AI integrates with Claude Code via its [hooks system](https://docs.anthropic.com/en/docs/claude-code/hooks). When you run `failproofai policies --install`, it registers hook commands in Claude Code's `settings.json` that fire on every tool call.
+
+<Steps>
+  <Step title="Install failproofai">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="Enable all built-in policies">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="Verify hooks are registered">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    You should see hook entries for `PreToolUse`, `PostToolUse`, `Notification`, and `Stop` events.
+  </Step>
+  <Step title="Run Claude Code">
+    ```bash
+    claude
+    ```
+
+    Policies now run automatically on every tool call. Try asking Claude to run `sudo rm -rf /` - it will be blocked.
+  </Step>
+</Steps>
+
+---
+
+## Setting up hooks for the Agents SDK
+
+If you're building with the [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), you can use the same hook system programmatically.
+
+<Steps>
+  <Step title="Install failproofai in your project">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="Configure hooks in your agent">
+    Pass hook commands when creating your agent process. The hooks fire the same way as in Claude Code - via stdin/stdout JSON:
+
+    ```bash
+    failproofai --hook PreToolUse   # called before each tool
+    failproofai --hook PostToolUse  # called after each tool
+    ```
+  </Step>
+  <Step title="Write a custom policy for your 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="Install the custom policy">
+    ```bash
+    failproofai policies --install --custom ./my-agent-policies.js
+    ```
+  </Step>
+</Steps>
+
+---
+
+## Block destructive commands
+
+The most common setup - prevent agents from doing irreversible damage.
+
+```bash
+failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
+```
+
+What this does:
+- `block-sudo` - blocks all `sudo` commands
+- `block-rm-rf` - blocks recursive file deletion
+- `block-force-push` - blocks `git push --force`
+- `block-curl-pipe-sh` - blocks piping remote scripts to shell
+
+---
+
+## Prevent secret leakage
+
+Stop agents from seeing or leaking credentials in tool output.
+
+```bash
+failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
+```
+
+These fire on `PostToolUse` - after a tool runs, they scrub the output before the agent sees it.
+
+---
+
+## Get Slack alerts when agents need attention
+
+Use the notification hook to forward idle alerts to 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 {
+      // never block the agent if Slack is unreachable
+    }
+
+    return allow();
+  },
+});
+```
+
+Install it:
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
+```
+
+---
+
+## Keep agents on a branch
+
+Prevent agents from switching branches or pushing to protected ones.
+
+```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();
+  },
+});
+```
+
+---
+
+## Require tests before commits
+
+Remind agents to run tests before committing.
+
+```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();
+  },
+});
+```
+
+---
+
+## Lock down a production repo
+
+Commit a project-level config so every developer on your team gets the same policies.
+
+Create `.failproofai/policies-config.json` in your repo:
+
+```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"]
+    }
+  }
+}
+```
+
+Then commit it:
+
+```bash
+git add .failproofai/policies-config.json
+git commit -m "Add failproofai team policies"
+```
+
+Every team member who has failproofai installed will automatically pick up these rules.
+
+---
+
+## Build an org-wide quality standard with convention policies
+
+The most impactful setup: commit `.failproofai/policies/` to your repo with policies tailored to your project. Every team member gets them automatically — no install commands, no config changes.
+
+<Steps>
+  <Step title="Create the directory and add policies">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+
+    ```js
+    // .failproofai/policies/team-policies.mjs
+    import { customPolicies, allow, deny, instruct } from "failproofai";
+
+    // Enforce your team's preferred package manager
+    // (or enable the built-in prefer-package-manager policy instead)
+    customPolicies.add({
+      name: "enforce-bun",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        const cmd = String(ctx.toolInput?.command ?? "");
+        if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm.");
+        return allow();
+      },
+    });
+
+    // Remind the agent to run tests before committing
+    customPolicies.add({
+      name: "test-before-commit",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
+          return instruct("Run tests before committing.");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="Commit to git">
+    ```bash
+    git add .failproofai/policies/
+    git commit -m "Add team quality policies"
+    ```
+  </Step>
+  <Step title="Keep improving">
+    As your team hits new failure modes, add policies and push. Everyone gets the update on their next `git pull`. These policies become a living quality standard that grows with your team.
+  </Step>
+</Steps>
+
+---
+
+## More examples
+
+The [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) directory in the repo contains:
+
+| File | What it shows |
+|------|---------------|
+| `policies-basic.js` | Starter policies - block production writes, force-push, piped scripts |
+| `policies-notification.js` | Slack alerts for idle notifications and session end |
+| `policies-advanced/index.js` | Transitive imports, async hooks, PostToolUse output scrubbing, Stop event handling |

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

@@ -0,0 +1,38 @@
+---
+title: "For agents"
+description: "Add Failproof AI knowledge to your coding agent in one command. Works with Claude Code, Cursor, Windsurf, and more."
+---
+
+Add the full Failproof AI reference to your coding agent in one command. Works with Claude Code, Cursor, Windsurf, and any other agent that supports skills.
+
+```bash
+npx skills add https://docs.befailproof.ai
+```
+
+`npx skills` detects which agents you have installed and adds the skill in the right format for each one automatically.
+
+## What the skill covers
+
+| Area | What's included |
+|------|----------------|
+| Policies | Built-in policy names, event types, parameters, enable/disable |
+| Custom policies | `customPolicies.add()`, match filters, `allow`/`deny`/`instruct` API |
+| Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` |
+| Configuration | `policies-config.json` structure, scope merging, `policyParams` |
+| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scopes |
+| Dashboard | Session viewer, policy activity, environment variables |
+| Architecture | Hook handler flow, exit codes, stdin/stdout contract |
+
+## Is the skill complete?
+
+Mintlify generates `llms.txt` from all pages in the navigation. The Failproof AI docs cover the full API - every policy, option, and example is included. If you find something missing, the source is at `https://docs.befailproof.ai/llms-full.txt`.
+
+For targeted context, link directly to a specific page:
+
+```bash
+# Just the custom policies API
+npx skills add https://docs.befailproof.ai/custom-policies
+
+# Just the built-in policies
+npx skills add https://docs.befailproof.ai/built-in-policies
+```

package/.next/standalone/docs-old/fr/agenteye/alerts.mdx

@@ -0,0 +1,63 @@
+---
+title: "Alertes"
+description: "Soyez informé dès qu'un seuil est franchi, sur le canal déjà utilisé par votre équipe, plutôt que de l'apprendre d'un client."
+---
+
+
+Soyez informé dès qu'un seuil est franchi, sur le canal déjà utilisé par votre équipe, plutôt que de l'apprendre d'un client. Définissez une règle une fois, et l'observabilité Failproof AI la vérifie selon un planning, puis vous alerte par e-mail, Slack, webhook ou directement dans le tableau de bord.
+
+![La page Alertes : une grille de cartes de règles d'alerte, chacune affichant son déclencheur, sa fenêtre d'évaluation, ses canaux et un badge de sévérité info, avertissement ou critique](/agenteye/images/alerts.png)
+*Toutes les règles d'alerte en un coup d'œil : ce qu'elles surveillent, à quelle fréquence, où elles notifient et leur niveau d'urgence.*
+
+## Soyez alerté des problèmes avant vos utilisateurs
+
+Arrêtez de rafraîchir un tableau de bord dans l'espoir de détecter une régression. Configurez une alerte dès qu'il y a un signal que vous voudriez connaître même quand personne ne surveille, et recevez-la là où vous êtes déjà :
+
+- **E-mail**, pour toutes les personnes concernées.
+- **Slack**, un message enrichi avec un bouton qui mène directement à l'incident.
+- **Webhook**, un POST JSON pour PagerDuty, Opsgenie ou votre propre endpoint, avec une signature optionnelle pour que le récepteur puisse le valider.
+- **Dans le tableau de bord**, discret par conception, pour quand vous affinez une règle et ne souhaitez pas encore envoyer de notification.
+
+Combinez n'importe lesquels sur une même règle, et la sévérité (info, avertissement ou critique) est transmise avec l'alerte pour que les plus urgentes soient clairement identifiées.
+
+## Créez la règle via un formulaire, pas du JSON
+
+Vous décrivez ce que signifie « en erreur » dans un formulaire, et l'observabilité Failproof AI génère la règle sous-jacente pour vous. La spec JSON n'est que ce que ce formulaire produit en coulisses, vous pouvez la lire pour comprendre une règle, mais vous la saisissez rarement manuellement.
+
+![Le formulaire de nouvelle alerte : nom et description, un interrupteur d'activation et un sélecteur de déclencheur proposant seuil de métrique, SQL personnalisé, score d'évaluation, évaluation composée et conditions par événement](/agenteye/images/alert-new.png)
+*Choisissez un déclencheur et le formulaire affiche les bons champs ; Enregistrer écrit la règle.*
+
+Le chemin classique est rapide : nommez-la, choisissez un **déclencheur** (ce qu'il faut surveiller), définissez le **seuil et la fenêtre** (quelle gravité, sur quelle durée), associez au moins un **canal**, puis **Enregistrez** et cliquez sur **Tester** pour déclencher une notification synthétique et vérifier que chaque destination est bien configurée. En coulisses, cela produit une petite spec comme :
+
+```json
+{ "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 }
+```
+
+Vous n'êtes pas limité à un seul type de signal. Choisissez le déclencheur qui correspond à votre façon de penser la défaillance :
+
+| Déclencheur | Se déclenche quand |
+|---|---|
+| **Seuil de métrique** | une métrique prédéfinie (taux d'erreur, latence p95 ou p99, nombre d'événements ou d'erreurs, dépenses en tokens) franchit votre seuil sur une fenêtre |
+| **SQL personnalisé** | votre propre requête en lecture seule retourne une ligne, ou une valeur calculée franchit un seuil |
+| **Score d'évaluation** | la moyenne d'un score d'évaluateur (par exemple, les hallucinations) franchit un seuil |
+| **Évaluation composée** | plusieurs vérifications de scores se combinent avec une logique any, all ou au-moins-N, pour détecter une régression qui n'apparaît qu'à travers plusieurs scores |
+| **Par événement** | un événement correspondant survient : un agent spécifique, un type d'erreur spécifique ou une sous-chaîne de message |
+
+Vous êtes déjà en train d'examiner une défaillance sur la [page Erreurs](/fr/agenteye/error-tracking) ? Chaque ligne dispose d'un bouton **+ alerte** qui ouvre ce même formulaire pré-rempli pour détecter exactement cette défaillance à l'avenir, de sorte que l'incident que vous venez de traiter devient celui qui vous alertera la prochaine fois.
+
+**Où le trouver :** Les alertes se trouvent à `/<org-slug>/alerts`. La création, la modification, la suppression et le test des règles nécessitent **`alerts:write`** ; `alerts:read` suffit pour consulter. Le sélecteur de destinataires liste les membres de votre organisation par nom, vous pouvez donc notifier une personne sans quitter le formulaire.
+
+## Ne me notifier que lorsque c'est réel
+
+Une mauvaise mesure ne devrait pas vous réveiller. Le filtre anti-bruit **M sur N** contrôle combien des dernières vérifications doivent échouer avant que l'alerte vous notifie réellement. Réglez-le sur **3 sur 5** et la règle ne se déclenche qu'après avoir dépassé le seuil lors de trois des cinq dernières vérifications, évitant ainsi les fausses alarmes d'un signal instable ; laissez-le sur la valeur par défaut **1 sur 1** pour déclencher dès le premier dépassement. Vous choisissez également la fréquence d'exécution de la règle, parmi les préréglages 1m, 5m, 15m et 1h, adaptée à la rapidité réelle d'évolution du signal.
+
+## Ce qui se passe quand une alerte se déclenche
+
+Un dépassement ouvre un **incident** et notifie vos canaux une fois. À partir de là, votre équipe le reconnaît, lui assigne un responsable, en discute et le résout, le tout dans un journal clair et attribué. Ce workflow de triage a son propre espace : voir [Incidents](/fr/agenteye/incidents).
+
+## Voir aussi
+
+- [Incidents](/fr/agenteye/incidents) : suivez une alerte déclenchée de l'ouverture à l'acquittement jusqu'à la résolution.
+- [Suivi des erreurs](/fr/agenteye/error-tracking) : regroupez les défaillances des agents et transformez-en une en alerte en un clic.
+- [Tableaux de bord](/fr/agenteye/dashboards) : consultez les tableaux partagés d'où proviennent les seuils que vous alertez.
+- [CLI et agents](/fr/agenteye/cli-and-agents) : créez des alertes et acquittez des incidents depuis votre terminal, ou intégrez-les dans votre CI.