failproofai 1.0.1-beta.1 → 1.0.1

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

@@ -0,0 +1,199 @@
+---
+title: Iniziare
+description: "Installa failproofai, abilita i criteri e lascia che i tuoi agenti funzionino in modo affidabile"
+icon: rocket
+---
+
+## Requisiti
+
+- **Node.js** >= 20.9.0
+- **Bun** >= 1.3.0 (facoltativo - necessario solo per compilare dal codice sorgente)
+
+---
+
+## Installazione
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+---
+
+## Avvio rapido
+
+<Steps>
+  <Step title="Abilita i criteri">
+    I criteri sono regole che vengono eseguite prima e dopo ogni chiamata di strumento dell'agente. Catturano comandi distruttivi, perdite di segreti e altre modalità di errore prima che causino danni.
+
+    ```bash
+    failproofai policies --install
+    ```
+
+    Questo scrive voci di hook nelle CLI dell'agente installate (`~/.claude/settings.json` di Claude Code, `~/.codex/hooks.json` di OpenAI Codex, `~/.copilot/hooks/failproofai.json` di GitHub Copilot CLI, `~/.cursor/hooks.json` di Cursor Agent, il plugin shim generato di OpenCode in `~/.config/opencode/plugins/failproofai.mjs` più una voce di registrazione nell'array `plugin` di `~/.config/opencode/opencode.json`, `~/.pi/agent/settings.json` di Pi, `~/.hermes/config.yaml` di Hermes, `~/.openclaw/openclaw.json` di OpenClaw, `~/.factory/hooks.json` di Factory Droid, `~/.config/devin/config.json` di Devin CLI, `~/.gemini/config/hooks.json` di Antigravity CLI, o la directory plugin auto-rilevata di Goose in `~/.agents/plugins/failproofai/hooks/hooks.json`). Quando ne è presente più di uno, ti verrà chiesto; passa `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose` (qualsiasi sottoinsieme) per saltare il prompt.
+
+    GitHub Copilot CLI, Cursor Agent, OpenCode e il supporto per Pi sono in **beta** — installa con `--cli copilot`, `--cli cursor`, `--cli opencode`, o `--cli pi`. Hermes (hermes-agent, un gateway Slack/Telegram) si installa con scope utente con `--cli hermes` ed è **anche** una fonte di controllo offline. OpenClaw (gateway openclaw, un assistente multi-canale self-hosted) si installa con scope utente con `--cli openclaw` — l'enforcement viene eseguito attraverso i suoi hook di plugin in-process (`before_agent_finalize` è un vero gate di fine turno, quindi i builtin `require-*-before-stop` enforcer) — ed è **anche** una fonte di controllo offline. Factory Droid (`droid`) si installa con `--cli factory` (scope utente + progetto) ed è **anche** una fonte di controllo offline. Devin CLI (`devin`, Cognition) si installa con `--cli devin` (scope utente + progetto) ed è **anche** una fonte di controllo offline. Antigravity CLI (`agy`) si installa con `--cli antigravity` (scope utente + progetto) ed è **anche** una fonte di controllo offline. Goose (codename goose, Block) si installa con `--cli goose` (scope utente + progetto) — l'installer rilascia semplicemente una directory di plugin in `~/.agents/plugins/failproofai/` che Goose auto-rileva, ed è **anche** una fonte di controllo offline.
+
+    ```bash
+    failproofai policies --install --scope project
+    failproofai policies --install --cli codex --scope project
+    failproofai policies --install --cli copilot --scope project
+    failproofai policies --install --cli cursor --scope project
+    failproofai policies --install --cli opencode --scope project
+    failproofai policies --install --cli pi --scope project
+    failproofai policies --install --cli hermes --scope user
+    failproofai policies --install --cli openclaw --scope user
+    failproofai policies --install --cli factory --scope project
+    failproofai policies --install --cli devin --scope project
+    failproofai policies --install --cli antigravity --scope project
+    failproofai policies --install --cli goose --scope project
+    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
+    ```
+  </Step>
+  <Step title="Verifica">
+    ```bash
+    failproofai policies
+    ```
+
+    Mostra ogni criterio, se è abilitato e eventuali parametri configurati.
+  </Step>
+  <Step title="Avvia la dashboard">
+    ```bash
+    failproofai
+    ```
+
+    Apre una dashboard locale in `http://localhost:8020` dove puoi sfogliare le sessioni, ispezionare le chiamate di strumento e gestire i criteri.
+  </Step>
+  <Step title="Esegui il tuo agente">
+    Avvia Claude Code come al solito. Se l'agente tenta qualcosa di rischioso, failproofai lo intercetta automaticamente. Lascialo in esecuzione incustodito e rivedi quello che è successo nella dashboard.
+  </Step>
+</Steps>
+
+---
+
+## Come funzionano i criteri
+
+Ogni volta che un agente esegue uno strumento, Claude Code chiama failproofai come subprocess:
+
+```text
+Claude Code  →  failproofai --hook PreToolUse  →  legge JSON da stdin
+                                                   valuta i criteri
+                                                   scrive la decisione su stdout
+```
+
+Ogni criterio restituisce una di tre decisioni:
+
+- **allow** - l'agente procede normalmente
+- **deny** - l'azione è bloccata, all'agente viene spiegato il motivo
+- **instruct** - un contesto aggiuntivo viene aggiunto al prompt dell'agente
+
+<Note>
+I criteri vengono eseguiti nel tuo processo locale. Nulla viene inviato a un servizio remoto.
+</Note>
+
+---
+
+## Configura i criteri del team con criteri basati sulla convenzione
+
+Il modo più veloce per stabilire standard di qualità su tutto il team è la convenzione `.failproofai/policies/`. Inserisci i file di criterio in questa directory e verranno caricati automaticamente — nessun flag, nessun cambio di configurazione, nessun comando di installazione.
+
+<Steps>
+  <Step title="Crea la directory dei criteri">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+  </Step>
+  <Step title="Aggiungi file di criterio">
+    Copia gli esempi di avviamento o scrivi i tuoi:
+
+    ```bash
+    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
+    ```
+
+    Oppure creane uno nuovo:
+
+    ```js
+    // .failproofai/policies/team-policies.mjs
+    import { customPolicies, allow, deny, instruct } from "failproofai";
+
+    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="Esegui il commit su git">
+    ```bash
+    git add .failproofai/policies/
+    git commit -m "Add team quality policies"
+    ```
+
+    Ogni membro del team che ha failproofai installato raccoglie automaticamente questi criteri. Non è necessaria alcuna configurazione per sviluppatore.
+  </Step>
+</Steps>
+
+<Tip>
+Esegui il commit di `.failproofai/policies/` nel tuo repository in modo che l'intero team condivida gli stessi standard. Man mano che il team scopre nuove modalità di errore, aggiungi criteri e spingili — tutti ricevono l'aggiornamento al prossimo `git pull`. Nel tempo questi criteri diventano uno standard di qualità vivente che continua a migliorare.
+</Tip>
+
+---
+
+## Archiviazione dei dati
+
+Tutte le configurazioni e i log rimangono sulla tua macchina:
+
+| Percorso | Cosa contiene |
+|------|----------------|
+| `~/.failproofai/policies/local-policies/policies-config.json` | Configurazione globale dei criteri |
+| `~/.failproofai/hook-activity/` | Cronologia dell'esecuzione dei hook (JSONL pagginato) |
+| `~/.failproofai/logs/` | Log di debug per errori di hook personalizzati |
+| `.failproofai/policies-config.json` | Configurazione per progetto (committata) |
+| `.failproofai/policies-config.local.json` | Override personali (gitignored) |
+
+---
+
+## Disinstallazione
+
+```bash
+failproofai policies --uninstall
+```
+
+Rimuove le voci di hook da `~/.claude/settings.json`. I file di configurazione in `~/.failproofai/` vengono mantenuti.
+
+---
+
+## Passaggi successivi
+
+<CardGroup cols={2}>
+
+<Card title="Configurazione" icon="gear" href="/it/configuration">
+  Scope e formato del file di configurazione
+</Card>
+
+<Card title="Criteri integrati" icon="shield" href="/it/built-in-policies">
+  Tutti i 26 criteri con parametri
+</Card>
+
+<Card title="Criteri personalizzati" icon="code" href="/it/custom-policies">
+  Scrivi i tuoi criteri in JavaScript
+</Card>
+
+<Card title="Monitor agente" icon="chart-line" href="/it/dashboard">
+  Monitora le sessioni e rivedi l'attività dei criteri
+</Card>
+
+</CardGroup>

package/.next/standalone/docs-old/it/introduction.mdx

@@ -0,0 +1,58 @@
+---
+---
+title: "Failproof AI"
+description: "FailproofAI fornisce agli agenti AI 39 politiche di errore integrate che catturano loop, perdite di segreti, chiamate di strumenti distruttive e altro ancora in una singola installazione."
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+Hook e politiche per **gestione degli errori nell'AI**, **recupero dagli errori** e **affidabilità degli LLM**. Mantieni i tuoi agenti AI affidabili e in esecuzione autonoma su **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Hermes**, **OpenClaw**, **Factory Droid**, **Devin CLI**, **Antigravity CLI** e **Agents SDK**.
+
+Gli agenti AI falliscono in modi prevedibili. Eseguono comandi distruttivi, perdono segreti, si allontanano dall'obiettivo, rimangono bloccati in loop o eseguono push direttamente su main. Se lasciati incustoditi, i piccoli errori si cascano in interruzioni, credenziali compromesse e lavoro perso.
+
+FailproofAI risolve questo con le **politiche**. Queste regole si collegano a ogni chiamata di strumento dell'agente per **rilevare i fallimenti**, **mitigarli** (bloccare, istruire, sanificare) e **avvertirti** quando qualcosa ha bisogno di attenzione. Una dashboard locale ti consente di esaminare ogni chiamata di strumento, fallimento dell'agente e azione di recupero in seguito.
+
+I trascritti e la valutazione delle politiche rimangono sul tuo computer. I dati vengono inviati solo quando utilizzi esplicitamente una funzione online, come promemoria di audit autenticati o inviti.
+
+## Inizia
+
+<CardGroup cols={2}>
+
+<Card title="39 politiche integrate" icon="shield" href="/it/built-in-policies">
+  Blocca i comandi distruttivi, previeni la perdita di segreti, mantieni gli agenti entro i confini del progetto e altro ancora. Tutto pronto all'uso.
+</Card>
+
+<Card title="Politiche personalizzate" icon="code" href="/it/custom-policies">
+  Scrivi le tue regole in JavaScript con una semplice API allow / deny / instruct.
+</Card>
+
+<Card title="Monitoraggio agenti" icon="chart-line" href="/it/dashboard">
+  Vedi cosa hanno fatto i tuoi agenti mentre eri via. Sfoglia le sessioni, ispeziona le chiamate di strumenti, rivedi dove le politiche hanno avuto effetto.
+</Card>
+
+<Card title="Configurazione facile" icon="gear" href="/it/configuration">
+  Regola qualsiasi politica senza codice. Imposta allowlist, rami protetti o soglie per progetto o a livello globale.
+</Card>
+
+</CardGroup>
+
+## Avvio rapido
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # abilita le politiche (oppure salta — `failproofai` ti offrirà di configurarle alla prima esecuzione)
+failproofai                      # avvia la dashboard
+```
+
+Consulta la guida [Inizia](/it/getting-started) per la procedura dettagliata completa.

package/.next/standalone/docs-old/it/package-aliases.mdx

@@ -0,0 +1,82 @@
+---
+title: Alias dei Package
+description: "Alias registrati per la prevenzione del typosquatting e come funzionano"
+icon: copy
+---
+
+## Package ufficiale
+
+Il package npm canonico è **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# or
+bun add -g failproofai
+```
+
+---
+
+## Perché possediamo i nomi degli alias
+
+Il typosquatting è un attacco comune alla supply chain in cui un attore malevolo registra un nome di package che dista un solo tasto da un package popolare. Gli utenti ignari che scrivono male il comando di installazione finiscono per eseguire codice controllato dall'attaccante con accesso completo al sistema - esattamente il tipo di minaccia che Failproof AI è progettato per difendere.
+
+Per eliminare questa superficie di attacco, **possediamo preventivamente tutte le comuni errate ortografie e varianti di formattazione** di `failproofai` su npm. Nessuno di questi nomi può essere registrato da terze parti. Ognuno di essi è un thin proxy che installa e delega al vero package `failproofai`.
+
+---
+
+## Alias registrati
+
+**Varianti di formattazione** - diversi modi di scrivere "failproof ai":
+
+| Package | Stato |
+|---------|-------|
+| `failproof` | ✅ Pubblicato |
+| `failproof-ai` | ⏳ In attesa di supporto npm |
+| `fail-proof-ai` | ⏳ In attesa di supporto npm |
+| `failproof_ai` | ⏳ In attesa di supporto npm |
+| `fail_proof_ai` | ⏳ In attesa di supporto npm |
+| `fail-proofai` | ⏳ In attesa di supporto npm |
+
+**Errori di digitazione `failprof*`** - manca una `o` da "proof":
+
+| Package | Stato |
+|---------|-------|
+| `failprof` | ✅ Pubblicato |
+| `failprof-ai` | ✅ Pubblicato |
+| `failprofai` | ⏳ In attesa di supporto npm |
+| `fail-prof-ai` | ⏳ In attesa di supporto npm |
+| `failprof_ai` | ⏳ In attesa di supporto npm |
+
+**Errori di digitazione `faliproof*`** - `a` e `i` scambiate:
+
+| Package | Stato |
+|---------|-------|
+| `faliproof` | ✅ Pubblicato |
+| `faliproof-ai` | ✅ Pubblicato |
+| `faliproofai` | ⏳ In attesa di supporto npm |
+
+> **Perché in attesa?** La politica di prevenzione dello spam di npm blocca i nomi che si normalizzano alla stessa stringa di un package esistente dopo aver rimosso la punteggiatura ed eseguito controlli di somiglianza. Abbiamo contattato il supporto npm per riservare questi nomi a scopo di anti-squatting. Saranno attivati una volta approvati.
+
+Puoi verificare che qualsiasi alias pubblicato sia di nostra proprietà:
+
+```bash
+npm info failproof
+# Cerca: "ExosphereHost Inc." nel campo maintainers
+```
+
+---
+
+## Come funzionano gli alias
+
+Ogni package alias:
+
+1. Elenca `failproofai` come dipendenza - in modo che il package reale sia installato e il suo binary diventi disponibile
+2. Espone un binary che corrisponde al proprio nome (ad es. `failprof-ai`) che reindirizzi tutti gli argomenti al binary `failproofai`
+
+Il proxy è uno script Node di due righe; non c'è alcuna logica, nessuna chiamata di rete e nessuna raccolta di dati al di là di quello che fa `failproofai` stesso.
+
+---
+
+## Se trovi un nome che abbiamo perso
+
+Apri un issue su [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) e lo registreremo.

package/.next/standalone/docs-old/it/testing.mdx

@@ -0,0 +1,261 @@
+---
+---
+title: Test
+description: "Unit test, test end-to-end e test helper"
+icon: flask-vial
+---
+
+failproofai dispone di due suite di test: **unit test** (veloci, mockati) e **test end-to-end** (invocazioni reali di subprocess).
+
+---
+
+## Esecuzione dei test
+
+```bash
+# Esegui tutti gli unit test una volta
+bun run test:run
+
+# Esegui gli unit test in modalità watch
+bun run test
+
+# Esegui i test E2E (richiede setup - vedi sotto)
+bun run test:e2e
+
+# Verifica dei tipi senza compilazione
+bunx tsc --noEmit
+
+# Lint
+bun run lint
+```
+
+---
+
+## Unit test
+
+Gli unit test si trovano in `__tests__/` e utilizzano [Vitest](https://vitest.dev) con `jsdom`.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # Logica delle policy per ogni builtin
+    hooks-config.test.ts          # Caricamento della config e merge dello scope
+    policy-evaluator.test.ts      # Iniezione dei param e ordine di valutazione
+    custom-hooks-registry.test.ts # Aggiungi/ottieni/cancella dal registro globalThis
+    custom-hooks-loader.test.ts   # Loader ESM, import transitivi, gestione errori
+    manager.test.ts               # Operazioni install/remove/list
+  components/
+    sessions-list.test.tsx        # Componente lista sessioni
+    project-list.test.tsx         # Componente lista progetti
+    ...
+  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
+```
+
+### Scrivere un unit test per una policy
+
+```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());
+  });
+});
+```
+
+---
+
+## Test end-to-end
+
+I test E2E invocano il binario reale `failproofai` come subprocess, inviano un payload JSON a stdin e verificano l'output su stdout e il codice di uscita. Questo test l'intero percorso di integrazione che Claude Code utilizza.
+
+### Setup
+
+I test E2E eseguono il binario direttamente dal sorgente del repository. Prima della prima esecuzione, compila il bundle CJS che i file di hook personalizzati utilizzano quando importano da `'failproofai'`:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+Quindi esegui i test:
+
+```bash
+bun run test:e2e
+```
+
+Ricompila `dist/` ogni volta che modifichi l'API hook pubblica (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, o `src/hooks/policy-types.ts`).
+
+### Struttura dei test E2E
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # Spawn del binario, invio del payload JSON, cattura exit code + stdout + stderr
+    fixture-env.ts      # Directory temporanee isolate per test con file di config
+    payloads.ts         # Factory di payload accurati come Claude per ogni tipo di evento
+  hooks/
+    builtin-policies.e2e.test.ts   # Ogni policy builtin con subprocess reale
+    custom-hooks.e2e.test.ts       # Caricamento e valutazione degli hook personalizzati
+    config-scopes.e2e.test.ts      # Merge della config tra project/local/global
+    policy-params.e2e.test.ts      # Iniezione dei parametri per ogni policy parametrizzata
+```
+
+### Utilizzo degli helper E2E
+
+**`FixtureEnv`** - ambiente isolato per test:
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - directory temp; passalo come payload.cwd per caricare .failproofai/policies-config.json
+// env.home   - directory home isolata; nessuna perdita reale di ~/.failproofai
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` registra automaticamente la pulizia di `afterEach`.
+
+**`runHook`** - invocare il binario:
+
+```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`** - factory di payload pronti:
+
+```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)
+```
+
+### Scrivere 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 vuoto
+  });
+});
+```
+
+### Forme di risposta E2E
+
+| Decisione | Codice di uscita | stdout |
+|----------|-----------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct (non-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop instruct | `2` | stdout vuoto; motivo in stderr |
+| Allow | `0` | stringa vuota |
+
+### Config di Vitest
+
+I test E2E utilizzano `vitest.config.e2e.mts` con:
+
+- `environment: "node"` - nessun global del browser necessario
+- `pool: "forks"` - vera isolamento dei processi (i test eseguono subprocess)
+- `testTimeout: 20_000` - 20s per test (avvio del binario + valutazione dell'hook)
+
+Il pool `forks` è importante: i worker basati su thread condividono `globalThis`, il che può interferire con i test che eseguono subprocess. I fork basati su processi evitano questo problema.
+
+---
+
+## CI
+
+L'esecuzione completa di CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) deve superare i controlli prima del merge. La suite E2E viene eseguita come job CI separato in parallelo.
+
+Vedi [Contributing](../CONTRIBUTING.md) per la checklist completa prima del merge.

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

@@ -0,0 +1,63 @@
+---
+title: "アラート"
+description: "チームがすでに使っているチャンネルで、問題が閾値を超えた瞬間に通知を受け取りましょう。顧客からの報告で気づく前に。"
+---
+
+
+チームがすでに使っているチャンネルで、問題が閾値を超えた瞬間に通知を受け取りましょう。顧客からの報告で気づく前に。ルールを一度設定するだけで、Failproof AI Observabilityがスケジュールに従ってチェックし、メール・Slack・webhook、またはダッシュボード上で通知します。
+
+![アラートページ：アラートルールのカードグリッド。それぞれトリガー、評価ウィンドウ、チャンネル、およびinfo・warning・criticalの重大度バッジを表示している](/agenteye/images/alerts.png)
+*すべてのアラートルールを一目で確認：監視対象、確認頻度、通知先、緊急度。*
+
+## ユーザーより先に問題を把握する
+
+回帰を見つけようとダッシュボードを何度もリロードするのはもうやめましょう。誰も見ていないときでも気づきたいシグナルにはアラートを設定し、普段いる場所に通知を届けましょう：
+
+- **メール**：知らせるべき担当者へ。
+- **Slack**：インシデントに直接ジャンプするボタン付きのリッチメッセージ。
+- **Webhook**：PagerDuty・Opsgenie、または独自のエンドポイントへのJSON POSTリクエスト。受信側が信頼できるようオプションの署名付き。
+- **ダッシュボード内**：誰にも通知せずルールを調整したいときのための、静かな通知。
+
+1つのルールに任意の組み合わせで通知先を設定でき、重大度（info・warning・critical）も合わせて通知されるため、緊急のものは一目でわかります。
+
+## ルールはJSONでなくフォームで作る
+
+「壊れている」状態をフォームで記述すると、Failproof AI Observabilityが基盤となるルールを自動生成します。JSONの仕様はあくまでフォームが裏で生成するものなので、ルールを理解するために読むことはあっても、直接入力することはほとんどありません。
+
+![新規アラートフォーム：名前と説明、有効化トグル、およびmetric threshold・custom SQL・evaluation score・compound eval・per-eventの条件を選べるトリガーピッカー](/agenteye/images/alert-new.png)
+*トリガーを選ぶとフォームが適切なフィールドに切り替わります。保存するとルールが書き込まれます。*
+
+基本的な流れはシンプルです：名前を入力し、**トリガー**（監視対象）を選び、**閾値とウィンドウ**（どの程度悪化したら、どの期間で）を設定し、**チャンネル**を少なくとも1つ追加して、**保存**します。その後 **テスト** を実行して仮の通知を送信し、すべての送信先が正しく設定されていることを確認しましょう。裏ではこのような小さなスペックが生成されます：
+
+```json
+{ "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 }
+```
+
+シグナルの種類は1つに限りません。障害をどう捉えるかに合わせてトリガーを選びましょう：
+
+| トリガー | 発火条件 |
+|---|---|
+| **Metric threshold** | エラー率・p95/p99レイテンシ・イベント数やエラー数・トークン消費量などのプリセットメトリクスが、指定期間内に閾値を超えたとき |
+| **Custom SQL** | 独自の読み取り専用クエリが行を返したとき、またはクエリで計算した値が閾値を超えたとき |
+| **Evaluation score** | 評価スコア（例：ハルシネーション）の平均値が閾値を超えたとき |
+| **Compound eval** | 複数のスコアチェックをany・all・at-least-Nロジックで組み合わせ、スコア全体にまたがる回帰を検出したいとき |
+| **Per event** | 特定のエージェント・特定のエラー種別・メッセージの部分文字列など、条件に一致する単一イベントが発生したとき |
+
+[エラーページ](/ja/agenteye/error-tracking)で障害を確認している最中ですか？各行には **+ alert** ボタンがあり、クリックするとその障害を再発時にキャッチするための内容があらかじめ入力されたフォームが開きます。今トリアージしたインシデントが、次回自動で通知されるようになります。
+
+**場所：** アラートは `/<org-slug>/alerts` にあります。ルールの作成・編集・削除・テストには **`alerts:write`** 権限が必要です。閲覧だけなら `alerts:read` で十分です。通知先ピッカーには組織のメンバーが名前で表示されるため、フォームを離れずに特定の担当者に通知できます。
+
+## 本当に問題なときだけ通知する
+
+1回の悪い計測結果で起こされるのは避けたいものです。**M of N** ノイズフィルターは、アラートが実際に通知を送る前に、直近の何回のチェックのうち何回が失敗する必要があるかを制御します。**3 of 5** に設定すると、直近5回のチェックのうち3回が閾値を超えた場合にのみ発火するため、不安定なシグナルによる誤報を防げます。デフォルトの **1 of 1** のままにすれば、最初の閾値超過で即座に発火します。ルールの実行頻度も1m・5m・15m・1hのプリセットから選択でき、シグナルの変化速度に合わせて調整できます。
+
+## アラートが発火したときの動作
+
+閾値超過が発生すると**インシデント**が開かれ、チャンネルへの通知が1回送信されます。その後チームは確認・担当者のアサイン・議論・解決を行い、すべてがクリーンな記録として残ります。このトリアージワークフローには専用の場所があります：[インシデント](/ja/agenteye/incidents)をご覧ください。
+
+## 関連情報
+
+- [インシデント](/ja/agenteye/incidents)：発火したアラートをオープンから確認済み・解決済みまで追跡する。
+- [エラートラッキング](/ja/agenteye/error-tracking)：エージェントの障害をグループ化し、ワンクリックでアラートに昇格させる。
+- [ダッシュボード](/ja/agenteye/dashboards)：アラートの閾値の基となる共有ボードを監視する。
+- [CLIとエージェント](/ja/agenteye/cli-and-agents)：ターミナルからアラートの作成やインシデントの確認を行う、またはCIにスクリプトとして組み込む。