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

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

@@ -1,334 +0,0 @@
----
-
----
-title: Architettura
-description: "Come funzionano internamente il gestore hook, il caricamento della config e la valutazione delle policy"
-icon: sitemap
----
-
-Questo documento spiega come failproofai funziona internamente: come il sistema di hook intercetta le chiamate agli strumenti dell'agente, come viene caricata e unita la configurazione, come vengono valutate le policy e come il dashboard monitora l'attività dell'agente.
-
----
-
-## Panoramica
-
-failproofai ha due sottosistemi indipendenti:
-
-1. **Hook handler** - Un veloce subprocess CLI che Claude Code invoca a ogni chiamata di strumento dell'agente. Valuta le policy e restituisce una decisione.
-2. **Agent Monitor (Dashboard)** - Un'applicazione web Next.js per monitorare le sessioni dell'agente e gestire le policy.
-
-Entrambi i sottosistemi condividono i file di configurazione in `~/.failproofai/` e nella directory `.failproofai/` del progetto, ma vengono eseguiti come processi separati e comunicano solo attraverso il filesystem.
-
----
-
-## Hook handler
-
-### Integrazione con Claude Code
-
-Quando esegui `failproofai policies --install`, scrive voci come questa in `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "failproofai --hook PreToolUse"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [ ... ]
-  }
-}
-```
-
-Claude Code invoca quindi `failproofai --hook PreToolUse` come subprocess prima di ogni chiamata di strumento, passando un payload JSON su stdin.
-
-### Formato del payload
-
-```json
-{
-  "session_id": "abc123",
-  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
-  "cwd": "/home/user/myproject",
-  "permission_mode": "default",
-  "hook_event_name": "PreToolUse",
-  "tool_name": "Bash",
-  "tool_input": { "command": "sudo apt install nodejs" }
-}
-```
-
-Per gli eventi `PostToolUse`, il payload contiene anche `tool_result` con l'output dello strumento.
-
-L'handler applica un limite di stdin di 1 MB. I payload che superano questo limite vengono scartati e tutte le policy permettono implicitamente.
-
-### Formato della risposta
-
-**Deny (PreToolUse):**
-```json
-{
-  "hookSpecificOutput": {
-    "permissionDecision": "deny",
-    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
-  }
-}
-```
-
-**Deny (PostToolUse):**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Blocked by failproofai because: API key detected in output"
-  }
-}
-```
-
-**Instruct (qualsiasi evento tranne Stop):**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
-  }
-}
-```
-
-**Instruct per evento Stop:**
-- Exit code: `2`
-- Motivo scritto su stderr (non stdout)
-
-**Allow:**
-- Exit code: `0`
-- stdout vuoto
-
-**Allow con messaggio:**
-
-`allow(message)` consente a una policy di inviare contesto informativo a Claude anche quando l'operazione è consentita. L'hook handler scrive il seguente JSON su **stdout** (non su un file di config — questa è la risposta dell'handler a Claude Code, proprio come le risposte deny e instruct sopra):
-
-```json
-// Written to stdout by the hook handler process
-{
-  "hookSpecificOutput": {
-    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
-  }
-}
-```
-- Exit code: `0` (operazione consentita)
-- Quando più policy restituiscono `allow` con un messaggio, i loro messaggi vengono uniti con newline in un'unica stringa `additionalContext`
-- Se nessuna policy fornisce un messaggio, stdout è vuoto (come prima)
-
-### Pipeline di elaborazione
-
-`src/hooks/handler.ts` implementa la pipeline completa:
-
-```text
-stdin JSON
-  → parse payload (max 1 MB)
-  → extract session metadata (session_id, cwd, tool_name, tool_input, etc.)
-  → readMergedHooksConfig(cwd)    ← merges project + local + global config
-  → register enabled builtin policies with resolved params
-  → load custom policies from customPoliciesPath (if set)
-  → register custom policies into policy registry
-  → evaluate all policies (builtins first, then custom)
-      → first deny short-circuits
-      → instruct decisions accumulate
-      → allow messages accumulate
-  → write JSON decision to stdout
-  → persist event to ~/.failproofai/hook-activity.jsonl
-  → exit
-```
-
-L'intero processo viene eseguito in meno di 100ms per payload tipici senza chiamate LLM.
-
----
-
-## Caricamento della configurazione
-
-`src/hooks/hooks-config.ts` implementa il caricamento della config a tre ambiti.
-
-```text
-[1] {cwd}/.failproofai/policies-config.json        ← project  (highest priority)
-[2] {cwd}/.failproofai/policies-config.local.json  ← local
-[3] ~/.failproofai/policies-config.json             ← global   (lowest priority)
-```
-
-Logica di unione:
-- `enabledPolicies` - unione deduplicated in tutti e tre i file
-- `policyParams` - per policy, il primo file che lo definisce vince completamente
-- `customPoliciesPath` - il primo file che lo definisce vince
-- `llm` - il primo file che lo definisce vince
-
-Il dashboard web utilizza `readHooksConfig()` (solo globale) per leggere e scrivere, poiché non viene invocato con un cwd del progetto.
-
----
-
-## Valutazione delle policy
-
-`src/hooks/policy-evaluator.ts` esegue le policy in ordine.
-
-Per ogni policy:
-
-1. Cerca lo schema `params` della policy (se ne ha uno).
-2. Leggi `policyParams[policy.name]` dalla config unita.
-3. Unisci i valori forniti dall'utente sui default dello schema per produrre `ctx.params`.
-4. Chiama `policy.fn(ctx)` con il contesto risolto.
-5. Se il risultato è `deny`, fermati immediatamente e restituisci quella decisione.
-6. Se il risultato è `instruct`, accumula il messaggio e continua.
-7. Se il risultato è `allow`, continua con la policy successiva.
-
-Dopo che tutte le policy vengono eseguite:
-- Se è stato restituito un qualsiasi `deny`, emetti la risposta deny.
-- Se sono stati raccolti dei ritorni `instruct`, emetti un'unica risposta instruct con tutti i messaggi uniti.
-- Altrimenti, emetti una risposta allow (stdout vuoto, exit 0).
-
----
-
-## Policy built-in
-
-`src/hooks/builtin-policies.ts` definisce tutte le 26 policy built-in come oggetti `BuiltinPolicyDefinition`:
-
-```typescript
-interface BuiltinPolicyDefinition {
-  name: string;
-  description: string;
-  fn: (ctx: PolicyContext) => PolicyResult;
-  match: {
-    events: HookEventType[];
-    tools?: string[];
-  };
-  defaultEnabled: boolean;
-  category: string;
-  beta?: boolean;
-  params?: PolicyParamsSchema;
-}
-```
-
-Le policy che accettano `params` dichiarano uno `PolicyParamsSchema` con tipi e default per ogni parametro. L'evaluator delle policy inietta i valori risolti in `ctx.params` prima di chiamare `fn`. Le funzioni delle policy leggono `ctx.params` senza null-guarding perché i default vengono sempre applicati per primi.
-
-Il pattern matching all'interno delle policy utilizza token di comando analizzati (argv), non corrispondenza di stringhe grezze. Questo previene il bypass via iniezione di operatori shell (ad es. un pattern per `sudo systemctl status *` non può essere bypassato aggiungendo `; rm -rf /` al comando).
-
----
-
-## Policy personalizzate
-
-`src/hooks/custom-hooks-registry.ts` implementa un registro supportato da `globalThis`:
-
-```typescript
-const REGISTRY_KEY = "__failproofai_custom_hooks__";
-
-export const customPolicies = {
-  add(hook: CustomHook): void { ... }
-};
-
-export function getCustomHooks(): CustomHook[] { ... }
-export function clearCustomHooks(): void { ... }  // used in tests
-```
-
-`src/hooks/custom-hooks-loader.ts` carica il file di policy dell'utente:
-
-1. Leggi `customPoliciesPath` dalla config; salta se assente.
-2. Risolvi al percorso assoluto; controlla che il file esista.
-3. Riscrivi tutti gli import `from "failproofai"` al percorso dist effettivo in modo che `customPolicies` si risolva nello stesso registro `globalThis`.
-4. Riscrivi ricorsivamente gli import locali transitivi per garantire la compatibilità ESM.
-5. Scrivi file `.mjs` temporanei e `import()` il file di entry.
-6. Chiama `getCustomHooks()` per recuperare gli hook registrati.
-7. Pulisci tutti i file temp in un blocco `finally`.
-
-In caso di errore (file non trovato, errore di sintassi, errore di import), l'errore viene registrato in `~/.failproofai/hook.log` e il loader restituisce un array vuoto. Le policy built-in non ne sono interessate.
-
-Le policy personalizzate vengono valutate dopo tutte le policy built-in. Un `deny` di policy personalizzata continua a fare short-circuit delle ulteriori policy personalizzate (ma tutte le built-in sono già state eseguite a questo punto).
-
----
-
-## Registrazione dell'attività
-
-Dopo ogni evento hook, l'handler aggiunge una riga JSONL a `~/.failproofai/hook-activity.jsonl`:
-
-```json
-{
-  "timestamp": "2026-04-06T12:34:56.789Z",
-  "sessionId": "abc123",
-  "eventType": "PreToolUse",
-  "toolName": "Bash",
-  "policyName": "block-sudo",
-  "decision": "deny",
-  "reason": "sudo command blocked by failproofai",
-  "durationMs": 12
-}
-```
-
-Una riga per policy che ha preso una decisione non-allow. Le decisioni allow non vengono registrate (per mantenere il file piccolo).
-
----
-
-## Architettura del dashboard
-
-Il dashboard è un'applicazione **Next.js 16** che utilizza l'App Router con React Server Components e Server Actions.
-
-```text
-app/
-  layout.tsx                  ← Root layout (theme, telemetry, nav)
-  projects/page.tsx           ← Server component: list all Claude projects
-  project/[name]/page.tsx     ← Server component: list sessions in a project
-  project/[name]/session/
-    [sessionId]/page.tsx      ← Server component: render session viewer
-  policies/page.tsx           ← Client component: policy management + activity log
-  actions/
-    get-hooks-config.ts       ← Read config + policy list
-    update-hooks-config.ts    ← Toggle policy on/off
-    update-policy-params.ts   ← Update policy parameters
-    get-hook-activity.ts      ← Paginate/search activity log
-    install-hooks-web.ts      ← Install/remove hooks from the browser
-  api/
-    download/[project]/[session]/route.ts   ← Export session as ZIP/JSONL
-```
-
-**Flusso di dati:**
-
-- I componenti pagina chiamano `lib/projects.ts` e `lib/log-entries.ts` per leggere i dati del progetto/sessione direttamente dal filesystem (nessun livello API per le letture).
-- La pagina Policies utilizza Server Actions per tutte le mutazioni (toggle, aggiornamento params, install/remove).
-- Il visualizzatore di sessione analizza il formato di trascritto JSONL di Claude e renderizza una timeline di messaggi e chiamate di strumento.
-
-**Decisioni di progettazione chiave:**
-
-- Nessun database - tutto lo stato persistente è in file semplici (`~/.failproofai/`, `~/.claude/projects/`).
-- Server Actions per mutazioni - nessuna API REST necessaria per le operazioni CRUD.
-- React Server Components per le pagine di lettura - caricamento iniziale più veloce, nessun bundle client per il fetch dei dati.
-- Componenti client solo dove è necessaria l'interattività (toggle policy, ricerca attività, visualizzatore log).
-
----
-
-## Layout dei file
-
-```text
-failproofai/
-├── bin/
-│   └── failproofai.mjs           # CLI router (hook / dashboard / install / etc.)
-├── src/hooks/
-│   ├── handler.ts                # Hook event pipeline
-│   ├── builtin-policies.ts       # 26 policy definitions
-│   ├── policy-evaluator.ts       # Policy execution engine
-│   ├── policy-registry.ts        # Policy registration and lookup
-│   ├── policy-types.ts           # TypeScript interfaces
-│   ├── hooks-config.ts           # Multi-scope config loading
-│   ├── custom-hooks-registry.ts  # globalThis-backed hook registry
-│   ├── custom-hooks-loader.ts    # ESM loader for user JS hooks
-│   ├── manager.ts                # install / remove / list operations
-│   ├── install-prompt.ts         # Interactive policy selection prompt
-│   ├── hook-logger.ts            # Logging to hook.log
-│   ├── hook-activity-store.ts    # Persist activity to hook-activity.jsonl
-│   └── llm-client.ts             # LLM API client (for AI-powered policies)
-├── app/                          # Next.js dashboard (pages + server actions)
-├── lib/                          # Shared utilities
-│   ├── projects.ts               # Enumerate Claude projects from filesystem
-│   ├── log-entries.ts            # Parse Claude transcript JSONL format
-│   ├── paths.ts                  # Resolve system paths
-│   └── ...
-├── components/                   # Shared React UI components
-├── contexts/                     # React context providers (theme, auto-refresh, telemetry)
-├── examples/                     # Example custom hook files
-└── __tests__/                    # Unit and E2E tests
-```