npm - failproofai - Versions diffs - 0.0.6-beta.3 → 0.0.6-beta.5 - Mend

failproofai 0.0.6-beta.3 → 0.0.6-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (509) hide show

package/.next/standalone/docs/it/testing.mdx DELETED Viewed

@@ -1,260 +0,0 @@
----
-title: Test
-description: "Unit test, test end-to-end e assistenti di test"
-icon: flask-vial
----
-failproofai dispone di due suite di test: **unit test** (veloci, con mock) e **test end-to-end** (invocazioni reali di subprocess).
----
-## Esecuzione dei test
-```bash
-# Esegui tutti gli unit test una sola 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 i tipi senza compilare
-bunx tsc --noEmit
-# Linting
-bun run lint
-```
----
-## Unit test
-Gli unit test si trovano in `__tests__/` e utilizzano [Vitest](https://vitest.dev) con `happy-dom`.
-```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 di parametri e ordine di valutazione
-    custom-hooks-registry.test.ts # Registry di globalThis add/get/clear
-    custom-hooks-loader.test.ts   # Loader ESM, importazioni transitive, 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 `failproofai` reale come subprocess, inviano un payload JSON a stdin e effettuano asserzioni sull'output stdout e il codice di uscita. Questo verifica il percorso di integrazione completo che utilizza Claude Code.
-### Setup
-I test E2E eseguono il binario direttamente dal codice sorgente del repository. Prima della prima esecuzione, compila il bundle CJS che i file di custom hook 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 pubblica dei hook (`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      # Avvia il binario, invia payload JSON, cattura codice di uscita + stdout + stderr
-    fixture-env.ts      # Directory temp isolate per test con file di config
-    payloads.ts         # Factory di payload conformi a 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 di custom hook
-    config-scopes.e2e.test.ts      # Merge della configurazione tra project/local/global
-    policy-params.e2e.test.ts      # Iniezione di parametri per ogni policy parametrizzata
-```
-### Utilizzo degli helper E2E
-**`FixtureEnv`** - ambiente isolato per ogni test:
-```typescript
-import { createFixtureEnv } from "../helpers/fixture-env";
-const env = createFixtureEnv();
-// env.cwd    - directory temporanea; passa come payload.cwd per raccogliere .failproofai/policies-config.json
-// env.home   - directory home isolata; nessun vero ~/.failproofai in conflitto
-env.writeConfig({
-  enabledPolicies: ["block-sudo"],
-  policyParams: {
-    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
-  },
-});
-```
-`createFixtureEnv()` registra la pulizia `afterEach` automaticamente.
-**`runHook`** - invoca 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 già 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; ragione in stderr |
-| Allow | `0` | stringa vuota |
-### Config di Vitest
-I test E2E utilizzano `vitest.config.e2e.mts` con:
-- `environment: "node"` - nessuna global del browser necessaria
-- `pool: "forks"` - vera isolazione dei processi (i test avviano subprocess)
-- `testTimeout: 20_000` - 20s per test (startup del binario + valutazione hook)
-Il pool `forks` è importante: i worker basati su thread condividono `globalThis`, il che può interferire con i test che avviano subprocess. I fork basati su processi evitano questo problema.
----
-## CI
-L'esecuzione CI completa (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) è richiesta per essere approvata prima di fare merge. La suite E2E viene eseguita come un job CI separato in parallelo.
-Consulta [Contributing](../CONTRIBUTING.md) per la checklist completa pre-merge.

package/.next/standalone/docs/ja/architecture.mdx DELETED Viewed

@@ -1,332 +0,0 @@
----
-title: アーキテクチャ
-description: "フックハンドラー、設定の読み込み、ポリシー評価の内部動作について"
-icon: sitemap
----
-このドキュメントでは、failproofai の内部動作を説明します。フックシステムがエージェントのツール呼び出しをどのようにインターセプトするか、設定がどのように読み込まれてマージされるか、ポリシーがどのように評価されるか、そしてダッシュボードがエージェントのアクティビティをどのように監視するかについて解説します。
----
-## 概要
-failproofai には独立した2つのサブシステムがあります。
-1. **フックハンドラー** - Claude Code がエージェントのツール呼び出しのたびに起動する高速な CLI サブプロセスです。ポリシーを評価して判断結果を返します。
-2. **エージェントモニター（ダッシュボード）** - エージェントセッションの監視とポリシー管理のための Next.js ウェブアプリケーションです。
-両サブシステムは `~/.failproofai/` とプロジェクトの `.failproofai/` ディレクトリにある設定ファイルを共有しますが、別々のプロセスとして動作し、ファイルシステムを通じてのみ通信します。
----
-## フックハンドラー
-### Claude Code との統合
-`failproofai policies --install` を実行すると、`~/.claude/settings.json` に次のようなエントリが書き込まれます。
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "failproofai --hook PreToolUse"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [ ... ]
-  }
-}
-```
-Claude Code はその後、各ツール呼び出しの前に `failproofai --hook PreToolUse` をサブプロセスとして起動し、stdin に JSON ペイロードを渡します。
-### ペイロード形式
-```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" }
-}
-```
-`PostToolUse` イベントの場合、ペイロードにはツールの出力を含む `tool_result` も含まれます。
-ハンドラーは stdin に対して 1 MB の上限を適用します。これを超えるペイロードは破棄され、すべてのポリシーは暗黙的に allow となります。
-### レスポンス形式
-**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（Stop 以外の任意のイベント）：**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
-  }
-}
-```
-**Stop イベントの instruct：**
-- 終了コード：`2`
-- 理由は stdout ではなく stderr に書き込まれます
-**Allow：**
-- 終了コード：`0`
-- stdout は空
-**メッセージ付き Allow：**
-`allow(message)` を使うと、操作が許可されている場合でも、ポリシーが Claude に情報コンテキストを返せます。フックハンドラーは以下の JSON を **stdout** に書き込みます（設定ファイルではなく、上記の deny や instruct レスポンスと同様に、ハンドラープロセスから Claude Code へのレスポンスです）。
-```json
-// フックハンドラープロセスが stdout に書き込む内容
-{
-  "hookSpecificOutput": {
-    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
-  }
-}
-```
-- 終了コード：`0`（操作は許可されます）
-- 複数のポリシーがメッセージ付きの `allow` を返した場合、各メッセージは改行で結合されて1つの `additionalContext` 文字列になります
-- どのポリシーもメッセージを提供しない場合、stdout は空になります（従来と同じ動作）
-### 処理パイプライン
-`src/hooks/handler.ts` がパイプライン全体を実装しています。
-```text
-stdin JSON
-  → ペイロードのパース（最大 1 MB）
-  → セッションメタデータの抽出（session_id, cwd, tool_name, tool_input など）
-  → readMergedHooksConfig(cwd)    ← プロジェクト・ローカル・グローバル設定をマージ
-  → 有効な組み込みポリシーを解決済みパラメーターで登録
-  → customPoliciesPath からカスタムポリシーを読み込む（設定されている場合）
-  → カスタムポリシーをポリシーレジストリに登録
-  → すべてのポリシーを評価（組み込みが先、次にカスタム）
-      → 最初の deny で短絡評価
-      → instruct の判断は蓄積
-      → allow のメッセージは蓄積
-  → JSON 判断結果を stdout に書き込む
-  → イベントを ~/.failproofai/hook-activity.jsonl に保存
-  → 終了
-```
-プロセス全体は、LLM 呼び出しなしの典型的なペイロードで 100ms 以内に完了します。
----
-## 設定の読み込み
-`src/hooks/hooks-config.ts` が3スコープの設定読み込みを実装しています。
-```text
-[1] {cwd}/.failproofai/policies-config.json        ← プロジェクト（最高優先度）
-[2] {cwd}/.failproofai/policies-config.local.json  ← ローカル
-[3] ~/.failproofai/policies-config.json             ← グローバル（最低優先度）
-```
-マージロジック：
-- `enabledPolicies` - 3つのファイルすべての重複排除された和集合
-- `policyParams` - ポリシーごとのキーで、最初に定義したファイルの値が全体として優先されます
-- `customPoliciesPath` - 最初に定義したファイルの値が優先されます
-- `llm` - 最初に定義したファイルの値が優先されます
-ウェブダッシュボードは、プロジェクトの cwd を使って起動されるわけではないため、読み書きに `readHooksConfig()`（グローバルのみ）を使用します。
----
-## ポリシー評価
-`src/hooks/policy-evaluator.ts` がポリシーを順番に実行します。
-各ポリシーに対して：
-1. ポリシーの `params` スキーマを検索します（存在する場合）。
-2. マージされた設定から `policyParams[policy.name]` を読み込みます。
-3. スキーマのデフォルト値にユーザー指定の値をマージして `ctx.params` を生成します。
-4. 解決されたコンテキストで `policy.fn(ctx)` を呼び出します。
-5. 結果が `deny` の場合、直ちに処理を停止してその判断を返します。
-6. 結果が `instruct` の場合、メッセージを蓄積して次のポリシーに進みます。
-7. 結果が `allow` の場合、次のポリシーに進みます。
-すべてのポリシーの実行後：
-- `deny` が返されていた場合、deny レスポンスを発行します。
-- `instruct` の返却が収集されていた場合、すべてのメッセージを結合した単一の instruct レスポンスを発行します。
-- それ以外の場合、allow レスポンスを発行します（stdout は空、終了コード 0）。
----
-## 組み込みポリシー
-`src/hooks/builtin-policies.ts` が全26件の組み込みポリシーを `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;
-}
-```
-`params` を受け付けるポリシーは、各パラメーターの型とデフォルト値を持つ `PolicyParamsSchema` を宣言します。ポリシー評価器は `fn` を呼び出す前に解決済みの値を `ctx.params` に注入します。デフォルト値は常に先に適用されるため、ポリシー関数は null チェックなしで `ctx.params` を読み込めます。
-ポリシー内部のパターンマッチングは、生の文字列マッチングではなく、パース済みのコマンドトークン（argv）を使用します。これにより、シェル演算子インジェクションによるバイパスを防ぎます（例えば、`sudo systemctl status *` に対するパターンは、コマンドに `; rm -rf /` を追加してもバイパスできません）。
----
-## カスタムポリシー
-`src/hooks/custom-hooks-registry.ts` が `globalThis` ベースのレジストリを実装しています。
-```typescript
-const REGISTRY_KEY = "__failproofai_custom_hooks__";
-export const customPolicies = {
-  add(hook: CustomHook): void { ... }
-};
-export function getCustomHooks(): CustomHook[] { ... }
-export function clearCustomHooks(): void { ... }  // テストで使用
-```
-`src/hooks/custom-hooks-loader.ts` がユーザーのポリシーファイルを読み込みます。
-1. 設定から `customPoliciesPath` を読み込み、存在しない場合はスキップします。
-2. 絶対パスに解決してファイルの存在を確認します。
-3. `from "failproofai"` のすべてのインポートを実際の dist パスに書き換え、`customPolicies` が同じ `globalThis` レジストリを参照するようにします。
-4. ESM 互換性を確保するために、推移的なローカルインポートを再帰的に書き換えます。
-5. 一時的な `.mjs` ファイルを書き込み、エントリファイルを `import()` します。
-6. `getCustomHooks()` を呼び出して登録済みのフックを取得します。
-7. `finally` ブロックですべての一時ファイルを削除します。
-エラー（ファイルが見つからない、構文エラー、インポートの失敗など）が発生した場合、エラーは `~/.failproofai/hook.log` に記録され、ローダーは空の配列を返します。組み込みポリシーへの影響はありません。
-カスタムポリシーはすべての組み込みポリシーの後に評価されます。カスタムポリシーの `deny` は、それ以降のカスタムポリシーの短絡評価を引き起こしますが（ただし、その時点ですべての組み込みポリシーは実行済みです）。
----
-## アクティビティログ
-各フックイベントの後、ハンドラーは `~/.failproofai/hook-activity.jsonl` に 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
-}
-```
-allow 以外の判断を行ったポリシーごとに1行が記録されます。allow の判断はファイルサイズを小さく保つために記録されません。
----
-## ダッシュボードのアーキテクチャ
-ダッシュボードは、App Router と React Server Components および Server Actions を使用した **Next.js 16** アプリケーションです。
-```text
-app/
-  layout.tsx                  ← ルートレイアウト（テーマ、テレメトリー、ナビゲーション）
-  projects/page.tsx           ← サーバーコンポーネント：すべての Claude プロジェクトを一覧表示
-  project/[name]/page.tsx     ← サーバーコンポーネント：プロジェクト内のセッションを一覧表示
-  project/[name]/session/
-    [sessionId]/page.tsx      ← サーバーコンポーネント：セッションビューアーを表示
-  policies/page.tsx           ← クライアントコンポーネント：ポリシー管理 + アクティビティログ
-  actions/
-    get-hooks-config.ts       ← 設定とポリシーリストの読み込み
-    update-hooks-config.ts    ← ポリシーの有効・無効の切り替え
-    update-policy-params.ts   ← ポリシーパラメーターの更新
-    get-hook-activity.ts      ← アクティビティログのページネーション・検索
-    install-hooks-web.ts      ← ブラウザからのフックのインストール・削除
-  api/
-    download/[project]/[session]/route.ts   ← セッションを ZIP/JSONL としてエクスポート
-```
-**データフロー：**
-- ページコンポーネントは `lib/projects.ts` と `lib/log-entries.ts` を呼び出し、ファイルシステムから直接プロジェクト・セッションデータを読み込みます（読み取りに API レイヤーは不要）。
-- Policies ページはすべての変更操作（切り替え、パラメーター更新、インストール・削除）に Server Actions を使用します。
-- セッションビューアーは Claude の JSONL トランスクリプト形式をパースし、メッセージとツール呼び出しのタイムラインを表示します。
-**主要な設計上の決定事項：**
-- データベースなし - すべての永続状態はプレーンファイル（`~/.failproofai/`、`~/.claude/projects/`）に保存されます。
-- 変更操作には Server Actions を使用 - CRUD 操作に REST API は不要です。
-- 読み取りページには React Server Components を使用 - 初期表示が高速で、データ取得のクライアントバンドルが不要です。
-- クライアントコンポーネントはインタラクティブ性が必要な箇所のみ使用（ポリシーの切り替え、アクティビティ検索、ログビューアー）。
----
-## ファイル構成
-```text
-failproofai/
-├── bin/
-│   └── failproofai.mjs           # CLI ルーター（hook / dashboard / install など）
-├── src/hooks/
-│   ├── handler.ts                # フックイベントパイプライン
-│   ├── builtin-policies.ts       # 26件のポリシー定義
-│   ├── policy-evaluator.ts       # ポリシー実行エンジン
-│   ├── policy-registry.ts        # ポリシーの登録と検索
-│   ├── policy-types.ts           # TypeScript インターフェース
-│   ├── hooks-config.ts           # マルチスコープ設定の読み込み
-│   ├── custom-hooks-registry.ts  # globalThis ベースのフックレジストリ
-│   ├── custom-hooks-loader.ts    # ユーザー JS フック用の ESM ローダー
-│   ├── manager.ts                # インストール・削除・一覧操作
-│   ├── install-prompt.ts         # インタラクティブなポリシー選択プロンプト
-│   ├── hook-logger.ts            # hook.log へのログ記録
-│   ├── hook-activity-store.ts    # hook-activity.jsonl へのアクティビティ保存
-│   └── llm-client.ts             # LLM API クライアント（AI 駆動ポリシー用）
-├── app/                          # Next.js ダッシュボード（ページ + サーバーアクション）
-├── lib/                          # 共有ユーティリティ
-│   ├── projects.ts               # ファイルシステムから Claude プロジェクトを列挙
-│   ├── log-entries.ts            # Claude トランスクリプト JSONL 形式のパース
-│   ├── paths.ts                  # システムパスの解決
-│   └── ...
-├── components/                   # 共有 React UI コンポーネント
-├── contexts/                     # React コンテキストプロバイダー（テーマ、自動更新、テレメトリー）
-├── examples/                     # カスタムフックのサンプルファイル
-└── __tests__/                    # ユニットテストおよび E2E テスト
-```