failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,260 @@
+---
+title: Tests
+description: "Tests unitaires, tests E2E et utilitaires de test"
+icon: flask-vial
+---
+
+failproofai dispose de deux suites de tests : les **tests unitaires** (rapides, avec mocks) et les **tests de bout en bout** (invocations réelles de sous-processus).
+
+---
+
+## Lancer les tests
+
+```bash
+# Lancer tous les tests unitaires une fois
+bun run test:run
+
+# Lancer les tests unitaires en mode watch
+bun run test
+
+# Lancer les tests E2E (nécessite une configuration - voir ci-dessous)
+bun run test:e2e
+
+# Vérification de types sans compilation
+bunx tsc --noEmit
+
+# Lint
+bun run lint
+```
+
+---
+
+## Tests unitaires
+
+Les tests unitaires se trouvent dans `__tests__/` et utilisent [Vitest](https://vitest.dev) avec `happy-dom`.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # Logique de politique pour chaque builtin
+    hooks-config.test.ts          # Chargement de la config et fusion des scopes
+    policy-evaluator.test.ts      # Injection de paramètres et ordre d'évaluation
+    custom-hooks-registry.test.ts # Registre globalThis add/get/clear
+    custom-hooks-loader.test.ts   # Chargeur ESM, imports transitifs, gestion des erreurs
+    manager.test.ts               # Opérations install/remove/list
+  components/
+    sessions-list.test.tsx        # Composant liste des sessions
+    project-list.test.tsx         # Composant liste des projets
+    ...
+  lib/
+    logger.test.ts
+    paths.test.ts
+    date-filters.test.ts
+    telemetry.test.ts
+    ...
+  actions/
+    get-hooks-config.test.ts
+    get-hook-activity.test.ts
+    ...
+  contexts/
+    ThemeContext.test.tsx
+    AutoRefreshContext.test.tsx
+```
+
+### Écrire un test unitaire de politique
+
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { getBuiltinPolicies } from "../../src/hooks/builtin-policies";
+import { allow, deny } from "../../src/hooks/policy-types";
+
+describe("block-sudo", () => {
+  const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!;
+
+  it("denies sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo apt install nodejs" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai"));
+  });
+
+  it("allows non-sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "ls -la" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+
+  it("allows patterns in allowPatterns", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo systemctl status nginx" },
+      params: { allowPatterns: ["sudo systemctl status"] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+});
+```
+
+---
+
+## Tests de bout en bout
+
+Les tests E2E invoquent le vrai binaire `failproofai` en tant que sous-processus, lui envoient une charge utile JSON via stdin et vérifient la sortie stdout ainsi que le code de sortie. Cela permet de tester le chemin d'intégration complet utilisé par Claude Code.
+
+### Configuration
+
+Les tests E2E exécutent le binaire directement depuis les sources du dépôt. Avant la première exécution, compilez le bundle CJS utilisé par les fichiers de hooks personnalisés lorsqu'ils importent depuis `'failproofai'` :
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+Lancez ensuite les tests :
+
+```bash
+bun run test:e2e
+```
+
+Recompilez `dist/` à chaque fois que vous modifiez l'API publique des hooks (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` ou `src/hooks/policy-types.ts`).
+
+### Structure des tests E2E
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # Lance le binaire, envoie le JSON de la charge utile, capture le code de sortie + stdout + stderr
+    fixture-env.ts      # Répertoires temporaires isolés par test avec fichiers de configuration
+    payloads.ts         # Factories de charges utiles fidèles à Claude pour chaque type d'événement
+  hooks/
+    builtin-policies.e2e.test.ts   # Chaque politique builtin avec un vrai sous-processus
+    custom-hooks.e2e.test.ts       # Chargement et évaluation des hooks personnalisés
+    config-scopes.e2e.test.ts      # Fusion de config entre scopes projet/local/global
+    policy-params.e2e.test.ts      # Injection de paramètres pour chaque politique paramétrée
+```
+
+### Utiliser les utilitaires E2E
+
+**`FixtureEnv`** - environnement isolé par test :
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - répertoire temporaire ; à passer en tant que payload.cwd pour charger .failproofai/policies-config.json
+// env.home   - répertoire home isolé ; évite les fuites depuis ~/.failproofai
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` enregistre automatiquement un nettoyage `afterEach`.
+
+**`runHook`** - invoquer le binaire :
+
+```typescript
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+const result = await runHook(
+  "PreToolUse",
+  Payloads.preToolUse.bash("sudo apt install nodejs", env.cwd),
+  { homeDir: env.home }
+);
+
+expect(result.exitCode).toBe(0);
+expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+```
+
+**`Payloads`** - factories de charges utiles prêtes à l'emploi :
+
+```typescript
+Payloads.preToolUse.bash(command, cwd)
+Payloads.preToolUse.write(filePath, content, cwd)
+Payloads.preToolUse.read(filePath, cwd)
+Payloads.postToolUse.bash(command, output, cwd)
+Payloads.postToolUse.read(filePath, content, cwd)
+Payloads.notification(message, cwd)
+Payloads.stop(cwd)
+```
+
+### Écrire un test E2E
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { createFixtureEnv } from "../helpers/fixture-env";
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+describe("block-rm-rf (E2E)", () => {
+  it("denies rm -rf", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm -rf /", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+  });
+
+  it("allows non-recursive rm", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm /tmp/file.txt", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("");  // allow → stdout vide
+  });
+});
+```
+
+### Formats de réponse E2E
+
+| Décision | Code de sortie | stdout |
+|----------|----------------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct (hors Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop instruct | `2` | stdout vide ; raison dans stderr |
+| Allow | `0` | chaîne vide |
+
+### Configuration Vitest
+
+Les tests E2E utilisent `vitest.config.e2e.mts` avec :
+
+- `environment: "node"` - aucune variable globale de navigateur requise
+- `pool: "forks"` - véritable isolation des processus (les tests lancent des sous-processus)
+- `testTimeout: 20_000` - 20 secondes par test (démarrage du binaire + évaluation des hooks)
+
+Le pool `forks` est important : les workers basés sur des threads partagent `globalThis`, ce qui peut interférer avec les tests qui lancent des sous-processus. Les forks basés sur des processus évitent ce problème.
+
+---
+
+## Intégration continue
+
+L'exécution complète en CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) doit passer avant toute fusion. La suite E2E s'exécute en tant que job CI distinct, en parallèle.
+
+Consultez [Contributing](../CONTRIBUTING.md) pour la liste de vérification complète avant fusion.

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

@@ -0,0 +1,134 @@
+---
+title: Getting started
+description: "Install failproofai, enable policies, and let your agents run reliably"
+icon: rocket
+---
+
+## Requirements
+
+- **Node.js** >= 20.9.0
+- **Bun** >= 1.3.0 (optional - only needed for building from source)
+
+---
+
+## Installation
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+---
+
+## Quick start
+
+<Steps>
+  <Step title="Enable policies">
+    Policies are rules that run before and after every agent tool call. They catch destructive commands, secret leakage, and other failure modes before they cause damage.
+
+    ```bash
+    failproofai policies --install
+    ```
+
+    This writes hook entries into Claude Code's `settings.json`. You can also install for a single project or pick specific policies:
+
+    ```bash
+    failproofai policies --install --scope project
+    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
+    ```
+  </Step>
+  <Step title="Verify">
+    ```bash
+    failproofai policies
+    ```
+
+    Shows every policy, whether it's enabled, and any configured parameters.
+  </Step>
+  <Step title="Launch the dashboard">
+    ```bash
+    failproofai
+    ```
+
+    Opens a local dashboard at `http://localhost:8020` where you can browse sessions, inspect tool calls, and manage policies.
+  </Step>
+  <Step title="Run your agent">
+    Start Claude Code as usual. If the agent tries something risky, failproofai intercepts it automatically. Leave it running unattended and review what happened in the dashboard.
+  </Step>
+</Steps>
+
+---
+
+## How policies work
+
+Every time an agent runs a tool, Claude Code calls failproofai as a subprocess:
+
+```text
+Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
+                                                 evaluates policies
+                                                 writes decision to stdout
+```
+
+Each policy returns one of three decisions:
+
+- **allow** - the agent proceeds normally
+- **deny** - the action is blocked, the agent is told why
+- **instruct** - extra context is added to the agent's prompt
+
+<Note>
+Policies run in your local process. Nothing is sent to a remote service.
+</Note>
+
+---
+
+## Data storage
+
+All configuration and logs stay on your machine:
+
+| Path | What it stores |
+|------|----------------|
+| `~/.failproofai/policies-config.json` | Global policy config |
+| `~/.failproofai/hook-activity.jsonl` | Hook execution history |
+| `~/.failproofai/hook.log` | Debug log for custom hook errors |
+| `.failproofai/policies-config.json` | Per-project config (committed) |
+| `.failproofai/policies-config.local.json` | Personal overrides (gitignored) |
+
+---
+
+## Uninstalling
+
+```bash
+failproofai policies --uninstall
+```
+
+Removes hook entries from `~/.claude/settings.json`. Config files in `~/.failproofai/` are kept.
+
+---
+
+## Next steps
+
+<CardGroup cols={2}>
+
+<Card title="Configuration" icon="gear" href="/configuration">
+  Scopes and config file format
+</Card>
+
+<Card title="Built-in policies" icon="shield" href="/built-in-policies">
+  All 26 policies with parameters
+</Card>
+
+<Card title="Custom policies" icon="code" href="/custom-policies">
+  Write your own policies in JavaScript
+</Card>
+
+<Card title="Agent monitor" icon="chart-line" href="/dashboard">
+  Monitor sessions and review policy activity
+</Card>
+
+</CardGroup>