failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,142 @@
+---
+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>

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

@@ -0,0 +1,253 @@
+---
+title: Esempi
+description: "Come configurare hook per Claude Code e Agents SDK"
+icon: book-open
+---
+
+Esempi pronti all'uso per scenari comuni. Ogni esempio mostra come installare e cosa aspettarsi.
+
+---
+
+## Configurazione di hook per Claude Code
+
+Failproof AI si integra con Claude Code tramite il suo [sistema di hook](https://docs.anthropic.com/en/docs/claude-code/hooks). Quando esegui `failproofai policies --install`, registra comandi hook nel file `settings.json` di Claude Code che si attivano ad ogni chiamata di tool.
+
+<Steps>
+  <Step title="Installa failproofai">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="Abilita tutte le policy integrate">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="Verifica che gli hook siano registrati">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    Dovresti vedere voci di hook per gli eventi `PreToolUse`, `PostToolUse`, `Notification` e `Stop`.
+  </Step>
+  <Step title="Esegui Claude Code">
+    ```bash
+    claude
+    ```
+
+    Le policy ora vengono eseguite automaticamente ad ogni chiamata di tool. Prova a chiedere a Claude di eseguire `sudo rm -rf /` - verrà bloccato.
+  </Step>
+</Steps>
+
+---
+
+## Configurazione di hook per Agents SDK
+
+Se stai costruendo con [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), puoi utilizzare lo stesso sistema di hook a livello programmatico.
+
+<Steps>
+  <Step title="Installa failproofai nel tuo progetto">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="Configura gli hook nel tuo agent">
+    Passa comandi hook quando crei il tuo processo agent. Gli hook si attivano allo stesso modo che in Claude Code - tramite JSON su stdin/stdout:
+
+    ```bash
+    failproofai --hook PreToolUse   # called before each tool
+    failproofai --hook PostToolUse  # called after each tool
+    ```
+  </Step>
+  <Step title="Scrivi una policy personalizzata per il tuo 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="Installa la policy personalizzata">
+    ```bash
+    failproofai policies --install --custom ./my-agent-policies.js
+    ```
+  </Step>
+</Steps>
+
+---
+
+## Blocca i comandi distruttivi
+
+La configurazione più comune - impedisci agli agent di causare danni irreversibili.
+
+```bash
+failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
+```
+
+Cosa fa:
+- `block-sudo` - blocca tutti i comandi `sudo`
+- `block-rm-rf` - blocca l'eliminazione ricorsiva di file
+- `block-force-push` - blocca `git push --force`
+- `block-curl-pipe-sh` - blocca il piping di script remoti a shell
+
+---
+
+## Previeni la perdita di segreti
+
+Impedisci agli agent di vedere o perdere credenziali nell'output dei tool.
+
+```bash
+failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
+```
+
+Queste si attivano su `PostToolUse` - dopo che uno strumento viene eseguito, puliscono l'output prima che l'agent lo veda.
+
+---
+
+## Ricevi avvisi Slack quando gli agent hanno bisogno di attenzione
+
+Utilizza l'hook di notifica per inviare gli avvisi di inattività a 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();
+  },
+});
+```
+
+Installalo:
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
+```
+
+---
+
+## Mantieni gli agent su un branch
+
+Impedisci agli agent di cambiare branch o fare push su quelli protetti.
+
+```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();
+  },
+});
+```
+
+---
+
+## Richiedi test prima dei commit
+
+Ricorda agli agent di eseguire i test prima di fare commit.
+
+```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();
+  },
+});
+```
+
+---
+
+## Proteggi un repository di produzione
+
+Fai il commit di una config a livello di progetto in modo che ogni sviluppatore del tuo team ottenga le stesse policy.
+
+Crea `.failproofai/policies-config.json` nel tuo repository:
+
+```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"]
+    }
+  }
+}
+```
+
+Poi fai il commit:
+
+```bash
+git add .failproofai/policies-config.json
+git commit -m "Add failproofai team policies"
+```
+
+Ogni membro del team che ha failproofai installato raccoglierà automaticamente queste regole.
+
+---
+
+## Altri esempi
+
+La directory [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) nel repository contiene:
+
+| File | Cosa mostra |
+|------|-------------|
+| `policies-basic.js` | Policy di base - blocca scritture in produzione, force-push, script pipati |
+| `policies-notification.js` | Avvisi Slack per notifiche di inattività e fine sessione |
+| `policies-advanced/index.js` | Import transitivi, hook asincroni, scrubbing dell'output PostToolUse, gestione dell'evento Stop |

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

@@ -0,0 +1,38 @@
+---
+title: "Per gli agenti"
+description: "Aggiungi la conoscenza di Failproof AI al tuo agente di codifica in un comando. Funziona con Claude Code, Cursor, Windsurf e altri."
+---
+
+Aggiungi il riferimento completo di Failproof AI al tuo agente di codifica in un comando. Funziona con Claude Code, Cursor, Windsurf e qualsiasi altro agente che supporti le skill.
+
+```bash
+npx skills add https://docs.befailproof.ai
+```
+
+`npx skills` rileva quali agenti hai installato e aggiunge la skill nel formato corretto per ognuno automaticamente.
+
+## Cosa copre la skill
+
+| Area | Cosa include |
+|------|---|
+| Policies | Nomi delle policy built-in, tipi di evento, parametri, abilita/disabilita |
+| Custom policies | `customPolicies.add()`, match filter, API `allow`/`deny`/`instruct` |
+| Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` |
+| Configuration | Struttura di `policies-config.json`, scope merging, `policyParams` |
+| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scope |
+| Dashboard | Session viewer, policy activity, variabili di ambiente |
+| Architecture | Hook handler flow, exit code, contratto stdin/stdout |
+
+## La skill è completa?
+
+Mintlify genera `llms.txt` da tutte le pagine nella navigazione. La documentazione di Failproof AI copre l'API completa - ogni policy, opzione ed esempio è incluso. Se trovi qualcosa di mancante, la fonte è disponibile a `https://docs.befailproof.ai/llms-full.txt`.
+
+Per un contesto più mirato, collega direttamente a una pagina specifica:
+
+```bash
+# Solo l'API delle custom policies
+npx skills add https://docs.befailproof.ai/custom-policies
+
+# Solo le built-in policies
+npx skills add https://docs.befailproof.ai/built-in-policies
+```

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

@@ -0,0 +1,134 @@
+---
+title: Per iniziare
+description: "Installa failproofai, abilita le policy 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 la compilazione dal sorgente)
+
+---
+
+## Installazione
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+---
+
+## Avvio rapido
+
+<Steps>
+  <Step title="Abilita le policy">
+    Le policy sono regole che vengono eseguite prima e dopo ogni chiamata a uno strumento dell'agente. Intercettano comandi distruttivi, fughe di segreti e altre modalità di errore prima che causino danni.
+
+    ```bash
+    failproofai policies --install
+    ```
+
+    Questo scrive voci di hook nel file `settings.json` di Claude Code. Puoi anche installare per un singolo progetto o selezionare policy specifiche:
+
+    ```bash
+    failproofai policies --install --scope project
+    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
+    ```
+  </Step>
+  <Step title="Verifica">
+    ```bash
+    failproofai policies
+    ```
+
+    Mostra ogni policy, se è abilitata e tutti i parametri configurati.
+  </Step>
+  <Step title="Avvia il dashboard">
+    ```bash
+    failproofai
+    ```
+
+    Apre un dashboard locale su `http://localhost:8020` dove puoi esplorare le sessioni, ispezionare le chiamate agli strumenti e gestire le policy.
+  </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 senza supervisione e rivedi cosa è accaduto nel dashboard.
+  </Step>
+</Steps>
+
+---
+
+## Come funzionano le policy
+
+Ogni volta che un agente esegue uno strumento, Claude Code chiama failproofai come sottoprocesso:
+
+```text
+Claude Code  →  failproofai --hook PreToolUse  →  legge JSON da stdin
+                                                 valuta le policy
+                                                 scrive la decisione su stdout
+```
+
+Ogni policy restituisce una di tre decisioni:
+
+- **allow** - l'agente procede normalmente
+- **deny** - l'azione è bloccata, all'agente viene spiegato il motivo
+- **instruct** - viene aggiunto contesto aggiuntivo al prompt dell'agente
+
+<Note>
+Le policy vengono eseguite nel tuo processo locale. Nulla viene inviato a un servizio remoto.
+</Note>
+
+---
+
+## Archiviazione dei dati
+
+Tutta la configurazione e i log rimangono sul tuo computer:
+
+| Percorso | Cosa archivia |
+|----------|---------------|
+| `~/.failproofai/policies-config.json` | Configurazione globale delle policy |
+| `~/.failproofai/hook-activity.jsonl` | Cronologia dell'esecuzione degli hook |
+| `~/.failproofai/hook.log` | Log di debug per errori hook personalizzati |
+| `.failproofai/policies-config.json` | Configurazione per progetto (committed) |
+| `.failproofai/policies-config.local.json` | Personalizzazioni personali (gitignored) |
+
+---
+
+## Disinstallazione
+
+```bash
+failproofai policies --uninstall
+```
+
+Rimuove le voci di hook da `~/.claude/settings.json`. I file di configurazione in `~/.failproofai/` vengono conservati.
+
+---
+
+## Prossimi passaggi
+
+<CardGroup cols={2}>
+
+<Card title="Configurazione" icon="gear" href="/it/configuration">
+  Scope e formato del file di configurazione
+</Card>
+
+<Card title="Policy integrate" icon="shield" href="/it/built-in-policies">
+  Tutte le 26 policy con parametri
+</Card>
+
+<Card title="Policy personalizzate" icon="code" href="/it/custom-policies">
+  Scrivi le tue policy in JavaScript
+</Card>
+
+<Card title="Monitor agente" icon="chart-line" href="/it/dashboard">
+  Monitora le sessioni e esamina l'attività delle policy
+</Card>
+
+</CardGroup>

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

@@ -0,0 +1,57 @@
+---
+title: Failproof AI
+description: "Gestisci hook e policy che mantengono i tuoi agenti AI affidabili e in esecuzione autonoma"
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+Hook e policy che mantengono i tuoi agenti AI affidabili e in esecuzione autonoma - per **Claude Code** e **Agents SDK**.
+
+Gli agenti AI falliscono in modi prevedibili. Eseguono comandi distruttivi, perdono segreti, si allontanano dal compito assegnato, si bloccano in loop infiniti o spingono direttamente al ramo principale. Se lasciati incustoditi, i piccoli errori si moltiplicano a cascata.
+
+Failproof AI risolve questo problema con le **policy** - regole che si collegano ad ogni chiamata di strumento dell'agente e possono **rilevare i fallimenti**, **attenuarli** (bloccare, istruire, sanitizzare) e **avvisarti** quando qualcosa richiede attenzione. Una dashboard locale ti permette di controllare tutto in seguito.
+
+Tutto viene eseguito localmente. Nessun dato lascia la tua macchina.
+
+## Inizia
+
+<CardGroup cols={2}>
+
+<Card title="26 policy predefinite" icon="shield" href="/it/built-in-policies">
+  Blocca comandi distruttivi, previeni la perdita di segreti, mantieni gli agenti all'interno dei confini del progetto, e molto altro - pronto all'uso.
+</Card>
+
+<Card title="Policy personalizzate" icon="code" href="/it/custom-policies">
+  Scrivi le tue regole in JavaScript con una semplice API allow / deny / instruct.
+</Card>
+
+<Card title="Monitor agente" icon="chart-line" href="/it/dashboard">
+  Vedi cosa hanno fatto i tuoi agenti mentre eri via. Sfoglia le sessioni, ispeziona le chiamate ai tool, esamina dove le policy sono state applicate.
+</Card>
+
+<Card title="Configurazione semplice" icon="gear" href="/it/configuration">
+  Regola qualsiasi policy senza scrivere codice. Imposta liste consentite, rami protetti o soglie per progetto o globalmente.
+</Card>
+
+</CardGroup>
+
+## Avvio rapido
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # abilita le policy
+failproofai                      # avvia la dashboard
+```
+
+Consulta la guida [Inizia](/it/getting-started) per la procedura dettagliata completa.