failproofai 0.0.6-beta.3 → 0.0.6-beta.4

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

@@ -1,353 +0,0 @@
----
-title: Policy Personalizzate
-description: "Scrivi le tue regole in JavaScript - applica convenzioni, previeni derive, rileva errori, integra con sistemi esterni"
-icon: code
----
-
-Le policy personalizzate ti permettono di scrivere regole per qualsiasi comportamento dell'agente: applicare convenzioni di progetto, prevenire derive, bloccare operazioni distruttive, rilevare agenti bloccati, o integrarsi con Slack, workflow di approvazione e altro. Utilizzano lo stesso sistema di eventi hook e le decisioni `allow`, `deny`, `instruct` delle policy built-in.
-
----
-
-## Esempio veloce
-
-```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();
-  },
-});
-```
-
-Installalo:
-
-```bash
-failproofai policies --install --custom ./my-policies.js
-```
-
----
-
-## Due modi per caricare policy personalizzate
-
-### Opzione 1: Basata su convenzione (consigliato)
-
-Posiziona file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e vengono caricati automaticamente — nessun flag o modifica di configurazione necessaria. Funziona come i git hook: aggiungi un file, e semplicemente funziona.
-
-```
-# Livello di progetto — committato su git, condiviso con il team
-.failproofai/policies/security-policies.mjs
-.failproofai/policies/workflow-policies.mjs
-
-# Livello utente — personale, si applica a tutti i progetti
-~/.failproofai/policies/my-policies.mjs
-```
-
-**Come funziona:**
-- Entrambe le directory di progetto e utente sono scansionate (unione — non first-scope-wins)
-- I file vengono caricati alfabeticamente all'interno di ogni directory. Aggiungi il prefisso `01-`, `02-` per controllare l'ordine
-- Solo i file corrispondenti a `*policies.{js,mjs,ts}` vengono caricati; altri file vengono ignorati
-- Ogni file viene caricato indipendentemente (fail-open per file)
-- Funziona insieme a policy `--custom` esplicite e built-in
-
-<Tip>
-Le policy per convenzione sono il modo più semplice per creare uno standard di qualità per la tua organizzazione. Committa `.failproofai/policies/` su git e ogni membro del team ottiene automaticamente le stesse regole — nessuna configurazione per-sviluppatore necessaria. Man mano che il tuo team scopre nuove modalità di errore, aggiungi una policy e fai push. Nel tempo queste diventano uno standard di qualità vivente che migliora continuamente con ogni contributo.
-</Tip>
-
-### Opzione 2: Percorso file esplicito
-
-```bash
-# Installa con un file di policy personalizzate
-failproofai policies --install --custom ./my-policies.js
-
-# Sostituisci il percorso del file di policy
-failproofai policies --install --custom ./new-policies.js
-
-# Rimuovi il percorso delle policy personalizzate dalla configurazione
-failproofai policies --uninstall --custom
-```
-
-Il percorso assoluto risolto viene archiviato in `policies-config.json` come `customPoliciesPath`. Il file viene caricato di nuovo ad ogni evento hook - non c'è caching tra gli eventi.
-
-### Usare entrambi insieme
-
-Le policy per convenzione e il file `--custom` esplicito possono coesistere. Ordine di caricamento:
-
-1. File `customPoliciesPath` esplicito (se configurato)
-2. File per convenzione di progetto (`{cwd}/.failproofai/policies/`, alfabetico)
-3. File per convenzione utente (`~/.failproofai/policies/`, alfabetico)
-
----
-
-## API
-
-### Import
-
-```js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-```
-
-### `customPolicies.add(hook)`
-
-Registra una policy. Chiama questa funzione tutte le volte necessarie per più policy nello stesso file.
-
-```ts
-customPolicies.add({
-  name: string;                         // required - unique identifier
-  description?: string;                 // shown in `failproofai policies` output
-  match?: { events?: HookEventType[] }; // filter by event type; omit to match all
-  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
-});
-```
-
-### Decision helpers
-
-| Funzione | Effetto | Usare quando |
-|----------|--------|----------|
-| `allow()` | Permetti l'operazione silenziosamente | L'azione è sicura, nessun messaggio necessario |
-| `deny(message)` | Blocca l'operazione | L'agente non dovrebbe eseguire questa azione |
-| `instruct(message)` | Aggiungi contesto senza bloccare | Dai all'agente contesto extra per rimanere in traccia |
-
-`deny(message)` - il messaggio appare a Claude con prefisso `"Blocked by failproofai:"`. Un singolo `deny` interrompe tutta la valutazione successiva.
-
-`instruct(message)` - il messaggio viene aggiunto al contesto di Claude per la chiamata dello strumento corrente. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme.
-
-<Tip>
-Puoi aggiungere guida extra a qualsiasi messaggio `deny` o `instruct` aggiungendo un campo `hint` in `policyParams` — nessuna modifica del codice necessaria. Questo funziona per policy personalizzate (`custom/`), per convenzione di progetto (`.failproofai-project/`), e per convenzione utente (`.failproofai-user/`) anche. Vedi [Configuration → hint](/it/configuration#hint-cross-cutting) per i dettagli.
-</Tip>
-
-### Messaggi allow informativi
-
-`allow(message)` permette l'operazione **e** invia un messaggio informativo indietro a Claude. Il messaggio viene consegnato come `additionalContext` nella risposta stdout del gestore hook — lo stesso meccanismo usato da `instruct`, ma semanticamente diverso: è un aggiornamento di stato, non un avviso.
-
-| Funzione | Effetto | Usare quando |
-|----------|--------|----------|
-| `allow(message)` | Permetti e invia contesto a Claude | Conferma che un controllo è passato, o spiega perché un controllo è stato saltato |
-
-Casi d'uso:
-- **Conferme di stato:** `allow("All CI checks passed.")` — dice a Claude che tutto è verde
-- **Spiegazioni fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — dice a Claude perché un controllo è stato saltato così ha il contesto completo
-- **Più messaggi si accumulano:** se più policy ciascuna restituisce `allow(message)`, tutti i messaggi vengono uniti con newline e consegnati insieme
-
-```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.");
-  },
-});
-```
-
-### Campi `PolicyContext`
-
-| Campo | Tipo | Descrizione |
-|-------|------|-------------|
-| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | Lo strumento in corso di chiamata (es. `"Bash"`, `"Write"`, `"Read"`) |
-| `toolInput` | `Record<string, unknown> \| undefined` | I parametri di input dello strumento |
-| `payload` | `Record<string, unknown>` | Payload evento grezzo completo da Claude Code |
-| `session` | `SessionMetadata \| undefined` | Contesto della sessione (vedi sotto) |
-
-### Campi `SessionMetadata`
-
-| Campo | Tipo | Descrizione |
-|-------|------|-------------|
-| `sessionId` | `string` | Identificatore della sessione Claude Code |
-| `cwd` | `string` | Directory di lavoro della sessione Claude Code |
-| `transcriptPath` | `string` | Percorso del file transcript JSONL della sessione |
-
-### Tipi di evento
-
-| Evento | Quando si attiva | Contenuti `toolInput` |
-|-------|--------------|----------------------|
-| `PreToolUse` | Prima che Claude esegua uno strumento | L'input dello strumento (es. `{ command: "..." }` per Bash) |
-| `PostToolUse` | Dopo che uno strumento si completa | L'input dello strumento + `tool_result` (l'output) |
-| `Notification` | Quando Claude invia una notifica | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - gli hook devono sempre restituire `allow()`, non possono bloccare le notifiche |
-| `Stop` | Quando la sessione Claude termina | Vuoto |
-
----
-
-## Ordine di valutazione
-
-Le policy vengono valutate in questo ordine:
-
-1. Policy built-in (in ordine di definizione)
-2. Policy personalizzate esplicite da `customPoliciesPath` (in ordine `.add()`)
-3. Policy per convenzione dal progetto `.failproofai/policies/` (file alfabetico, ordine `.add()` interno)
-4. Policy per convenzione dall'utente `~/.failproofai/policies/` (file alfabetico, ordine `.add()` interno)
-
-<Note>
-Il primo `deny` interrompe tutte le policy successive. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme.
-</Note>
-
----
-
-## Import transitivi
-
-I file di policy personalizzate possono importare moduli locali usando percorsi relativi:
-
-```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");
-  },
-});
-```
-
-Tutti gli import relativi raggiungibili dal file di entry vengono risolti. Questo viene implementato riscrivendo gli import `from "failproofai"` al percorso dist effettivo e creando file `.mjs` temporanei per garantire la compatibilità ESM.
-
----
-
-## Filtraggio del tipo di evento
-
-Usa `match.events` per limitare quando una policy si attiva:
-
-```js
-customPolicies.add({
-  name: "require-summary-on-stop",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    // Only fires when the session ends
-    // ctx.session.transcriptPath contains the full session log
-    return allow();
-  },
-});
-```
-
-Ometti `match` completamente per attivare su ogni tipo di evento.
-
----
-
-## Gestione degli errori e modalità di guasto
-
-Le policy personalizzate sono **fail-open**: gli errori non bloccheranno mai le policy built-in o crasheranno il gestore hook.
-
-| Guasto | Comportamento |
-|---------|----------|
-| `customPoliciesPath` non impostato | Nessuna policy personalizzata esplicita viene eseguita; le policy per convenzione e le built-in continuano normalmente |
-| File non trovato | Avviso registrato in `~/.failproofai/hook.log`; le built-in continuano |
-| Errore di sintassi/import (esplicito) | Errore registrato in `~/.failproofai/hook.log`; le policy personalizzate esplicite vengono saltate |
-| Errore di sintassi/import (convenzione) | Errore registrato; quel file viene saltato, altri file per convenzione si caricano ancora |
-| `fn` lancia a runtime | Errore registrato; quell'hook viene trattato come `allow`; altri hook continuano |
-| `fn` impiega più di 10s | Timeout registrato; trattato come `allow` |
-| Directory per convenzione mancante | Nessuna policy per convenzione viene eseguita; nessun errore |
-
-<Tip>
-Per debuggare gli errori delle policy personalizzate, guarda il file log:
-
-```bash
-tail -f ~/.failproofai/hook.log
-```
-</Tip>
-
----
-
-## Esempio completo: policy multiple
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-// Prevent agent from writing to secrets/ directory
-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();
-  },
-});
-
-// Keep the agent on track: verify tests before committing
-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();
-  },
-});
-
-// Prevent unplanned dependency changes during freeze
-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 };
-```
-
----
-
-## Esempi
-
-La directory `examples/` contiene file di policy pronti all'esecuzione:
-
-| File | Contenuti |
-|------|----------|
-| `examples/policies-basic.js` | Cinque policy per iniziare che coprono modalità di guasto comuni dell'agente |
-| `examples/policies-advanced/index.js` | Pattern avanzati: import transitivi, chiamate async, output scrubbing, e hook di fine sessione |
-| `examples/convention-policies/security-policies.mjs` | Policy di sicurezza basate su convenzione (blocca scritture .env, previeni riscrittura della cronologia git) |
-| `examples/convention-policies/workflow-policies.mjs` | Policy di workflow basate su convenzione (promemoria test, file di audit writes) |
-
-### Usando esempi di file espliciti
-
-```bash
-failproofai policies --install --custom ./examples/policies-basic.js
-```
-
-### Usando esempi basati su convenzione
-
-```bash
-# Copy to project level
-mkdir -p .failproofai/policies
-cp examples/convention-policies/*.mjs .failproofai/policies/
-
-# Or copy to user level
-mkdir -p ~/.failproofai/policies
-cp examples/convention-policies/*.mjs ~/.failproofai/policies/
-```
-
-Nessun comando di installazione necessario — i file vengono raccolti automaticamente al prossimo evento hook.

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

@@ -1,142 +0,0 @@
----
-title: Dashboard
-description: "Monitora le sessioni degli agenti, esamina le chiamate di strumenti e gestisci le policy"
-icon: chart-line
----
-
-Il dashboard di failproofai è un'applicazione web locale per monitorare le sessioni dei tuoi agenti AI e gestire le policy. Scopri cosa hanno fatto i tuoi agenti mentre non eri presente.
-
----
-
-## Avvio del dashboard
-
-```bash
-failproofai
-```
-
-Si apre su `http://localhost:8020`.
-
-Il dashboard legge direttamente dal filesystem - le cartelle del tuo progetto Claude Code e i file di configurazione di failproofai. Niente viene scritto su un servizio remoto.
-
----
-
-## Pagine
-
-### Progetti
-
-Elenca tutti i progetti Claude Code trovati sul tuo computer. I progetti vengono individuati da `~/.claude/projects/` (o dal percorso impostato da `CLAUDE_PROJECTS_PATH`).
-
-Ogni progetto mostra:
-- Nome del progetto (derivato dal percorso della cartella)
-- Numero di sessioni
-- Data dell'attività della sessione più recente
-
-Clicca su un progetto per vedere le sue sessioni.
-
-### Sessioni
-
-Elenca tutte le sessioni all'interno di un progetto. Ogni sessione mostra:
-- ID della sessione
-- Timestamp di inizio e fine
-- Numero di chiamate di strumenti
-- Numero di attività hook (policy che si sono attivate)
-
-Utilizza il filtro per intervallo di date e la ricerca per ID della sessione per restringere l'elenco. Le sessioni sono impaginate.
-
-Clicca su una sessione per aprire il visualizzatore di sessioni.
-
-### Visualizzatore di sessioni
-
-Il visualizzatore di sessioni risponde alla domanda chiave per gli agenti autonomi: cosa ha fatto l'agente e ha mantenuto la giusta direzione? Mostra una sequenza temporale di tutto ciò che è accaduto in una sessione:
-
-- **Messaggi** - Risposte di testo di Claude e prompt dell'utente
-- **Chiamate di strumenti** - Ogni strumento invocato da Claude, con il suo input e output
-- **Attività policy** - Per ogni chiamata di strumento, quali policy si sono attivate e quale decisione hanno restituito
-
-La barra delle statistiche in alto mostra la durata della sessione, il numero totale di chiamate di strumenti e un riepilogo delle decisioni degli hook (conteggi allow / deny / instruct).
-
-Puoi esportare la sessione come file ZIP o JSONL utilizzando il pulsante di download.
-
-### Policy
-
-Una pagina con due schede per gestire le policy e revisionare l'attività.
-
-<Tabs>
-  <Tab title="Scheda Policy">
-  - Attiva o disattiva le singole policy con un solo clic (scrive in `~/.failproofai/policies-config.json`)
-  - Espandi una policy per configurare i suoi parametri (per le policy che supportano `policyParams`)
-  - Installa o rimuovi hook per uno scope specifico
-  - Imposta un percorso file di policy personalizzato
-  </Tab>
-  <Tab title="Scheda Attività">
-  - Cronologia completa impaginata di ogni evento hook che si è attivato in tutte le sessioni
-  - Cerca per nome della policy, ID della sessione, nome dello strumento o decisione
-  - Ogni riga mostra: timestamp, nome della policy, decisione, nome dello strumento, ID della sessione e il motivo delle decisioni deny/instruct
-  </Tab>
-</Tabs>
-
----
-
-## Aggiornamento automatico
-
-Il dashboard ha un'opzione di aggiornamento automatico nella barra di navigazione in alto. Quando abilitata, la pagina corrente si aggiorna periodicamente per mostrare le nuove sessioni e l'attività delle policy man mano che appaiono. Essenziale per monitorare le sessioni di agenti autonomi a lunga esecuzione.
-
----
-
-## Disabilitazione di pagine
-
-Se hai bisogno solo di alcune parti del dashboard, imposta `FAILPROOFAI_DISABLE_PAGES` a una lista separata da virgole di nomi di pagine:
-
-```bash
-FAILPROOFAI_DISABLE_PAGES=policies failproofai
-```
-
-Valori validi: `policies`, `projects`.
-
----
-
-## Tema
-
-Il dashboard supporta la modalità chiara e scura. Attiva/disattiva tramite il pulsante nella barra di navigazione. La preferenza viene memorizzata nell'archiviazione locale del tuo browser.
-
----
-
-## Configurazione del percorso dei progetti
-
-Per impostazione predefinita, il dashboard legge dalla directory dei progetti Claude Code standard. Sostituiscila per configurazioni personalizzate:
-
-```bash
-CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
-```
-
----
-
-## Accesso da un host non-localhost
-
-Quando esegui il dashboard in **modalità dev** (`npm run dev`) e vi accedi da un nome host diverso da `localhost` - ad esempio, un dominio personalizzato, un IP remoto o un URL tunnelato - potresti vedere un avviso come:
-
-```text
-⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
-```
-
-Questo è Next.js che blocca l'accesso cross-origin al suo websocket HMR (hot module reload), una funzione solo per dev. Per consentire il tuo host, usa il flag `--allowed-origins`:
-
-```bash
-npm run dev -- --allowed-origins dashboard.example.com
-```
-
-Per più host o IP, passa una lista separata da virgole:
-
-```bash
-npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
-```
-
-Puoi anche impostare la variabile di ambiente `FAILPROOFAI_ALLOWED_DEV_ORIGINS`:
-
-```bash
-FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
-```
-
-<Note>
-Questo si applica solo alla modalità dev. Quando esegui `failproofai` (modalità produzione), non c'è nessun websocket HMR e nessun problema di risorsa dev cross-origin.
-</Note>