failproofai 0.0.2 → 0.0.4-beta.0

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

@@ -0,0 +1,142 @@
+---
+title: ダッシュボード
+description: "エージェントセッションの監視、ツール呼び出しの確認、ポリシーの管理"
+icon: chart-line
+---
+
+failproofai ダッシュボードは、AIエージェントセッションの監視とポリシー管理のためのローカルWebアプリケーションです。あなたが離れている間にエージェントが何をしたかを確認できます。
+
+---
+
+## ダッシュボードの起動
+
+```bash
+failproofai
+```
+
+`http://localhost:8020` で開きます。
+
+ダッシュボードはファイルシステムから直接読み取ります。Claude Code のプロジェクトフォルダと failproofai の設定ファイルを参照しており、リモートサービスへの書き込みは行いません。
+
+---
+
+## ページ
+
+### プロジェクト
+
+マシン上で見つかったすべての Claude Code プロジェクトを一覧表示します。プロジェクトは `~/.claude/projects/`（または `CLAUDE_PROJECTS_PATH` で設定されたパス）から検出されます。
+
+各プロジェクトには以下が表示されます：
+- プロジェクト名（フォルダパスから生成）
+- セッション数
+- 最新のセッションアクティビティの日時
+
+プロジェクトをクリックすると、そのセッション一覧が表示されます。
+
+### セッション
+
+プロジェクト内のすべてのセッションを一覧表示します。各セッションには以下が表示されます：
+- セッションID
+- 開始・終了タイムスタンプ
+- ツール呼び出し数
+- フックアクティビティ数（発動したポリシーの数）
+
+日付範囲フィルターとセッションID検索で絞り込みができます。セッションはページネーション表示されます。
+
+セッションをクリックすると、セッションビューアーが開きます。
+
+### セッションビューアー
+
+セッションビューアーは、自律型エージェントにおける核心的な問いに答えます。「エージェントは何をしたのか、そして正しく動作していたのか？」セッション内で起きたすべての出来事をタイムライン形式で表示します：
+
+- **メッセージ** - Claude のテキスト応答とユーザープロンプト
+- **ツール呼び出し** - Claude が呼び出したすべてのツールと、その入力・出力
+- **ポリシーアクティビティ** - 各ツール呼び出しに対して、どのポリシーが発動し、どの判断を返したか
+
+上部のステータスバーには、セッション時間、ツール呼び出しの合計数、フック判断の概要（allow / deny / instruct の件数）が表示されます。
+
+ダウンロードボタンを使って、セッションをZIPまたはJSONLファイルとしてエクスポートできます。
+
+### ポリシー
+
+ポリシーの管理とアクティビティ確認のための2タブページです。
+
+<Tabs>
+  <Tab title="Policies tab">
+  - ワンクリックで個別のポリシーのオン・オフを切り替え（`~/.failproofai/policies-config.json` に書き込まれます）
+  - ポリシーを展開してパラメーターを設定（`policyParams` に対応したポリシーの場合）
+  - 指定したスコープのフックをインストールまたは削除
+  - カスタムポリシーファイルのパスを設定
+  </Tab>
+  <Tab title="Activity tab">
+  - すべてのセッションにわたって発動したフックイベントの完全なページネーション履歴
+  - ポリシー名、セッションID、ツール名、判断内容で検索
+  - 各行には、タイムスタンプ、ポリシー名、判断内容、ツール名、セッションID、およびdeny/instructの理由が表示されます
+  </Tab>
+</Tabs>
+
+---
+
+## 自動更新
+
+ダッシュボードの上部ナビゲーションには自動更新のトグルがあります。有効にすると、現在のページが定期的に更新され、新しいセッションやポリシーアクティビティがリアルタイムで表示されます。長時間稼働する自律型エージェントセッションの監視に欠かせない機能です。
+
+---
+
+## ページの無効化
+
+ダッシュボードの一部のみ必要な場合は、`FAILPROOFAI_DISABLE_PAGES` にカンマ区切りのページ名を設定します：
+
+```bash
+FAILPROOFAI_DISABLE_PAGES=policies failproofai
+```
+
+有効な値：`policies`、`projects`
+
+---
+
+## テーマ
+
+ダッシュボードはライトモードとダークモードに対応しています。ナビゲーションバーのボタンで切り替えられます。設定はブラウザのローカルストレージに保存されます。
+
+---
+
+## プロジェクトパスの設定
+
+デフォルトでは、ダッシュボードは標準の Claude Code プロジェクトディレクトリを読み取ります。カスタム構成の場合は上書きできます：
+
+```bash
+CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
+```
+
+---
+
+## localhost 以外のホストからのアクセス
+
+**devモード**（`npm run dev`）でダッシュボードを起動し、`localhost` 以外のホスト名（カスタムドメイン、リモートIPアドレス、トンネリングURLなど）からアクセスすると、以下のような警告が表示されることがあります：
+
+```text
+⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
+```
+
+これは、Next.js がHMR（ホットモジュールリロード）WebSocketへのクロスオリジンアクセスをブロックしているためです。これはdev専用の機能です。対象のホストを許可するには、`--allowed-origins` フラグを使用します：
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com
+```
+
+複数のホストやIPアドレスを許可する場合は、カンマ区切りで指定します：
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
+```
+
+代わりに `FAILPROOFAI_ALLOWED_DEV_ORIGINS` 環境変数を設定することもできます：
+
+```bash
+FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
+```
+
+<Note>
+これはdevモードにのみ適用されます。`failproofai`（本番モード）を実行している場合、HMR WebSocketは存在しないため、クロスオリジンのdev用リソースの問題は発生しません。
+</Note>

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

@@ -0,0 +1,253 @@
+---
+title: 使用例
+description: "Claude Code と Agents SDK 向けフックの設定方法"
+icon: book-open
+---
+
+よくあるシナリオですぐに使える例を紹介します。各例では、インストール方法と期待される動作を説明します。
+
+---
+
+## Claude Code 向けフックの設定
+
+Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.com/en/docs/claude-code/hooks)を通じて統合されます。`failproofai policies --install` を実行すると、Claude Code の `settings.json` にフックコマンドが登録され、すべてのツール呼び出し時に実行されます。
+
+<Steps>
+  <Step title="failproofai をインストールする">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="組み込みポリシーをすべて有効にする">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="フックが登録されていることを確認する">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    `PreToolUse`、`PostToolUse`、`Notification`、`Stop` イベントのフックエントリが表示されるはずです。
+  </Step>
+  <Step title="Claude Code を起動する">
+    ```bash
+    claude
+    ```
+
+    これで、すべてのツール呼び出しに対してポリシーが自動的に実行されます。試しに Claude に `sudo rm -rf /` を実行するよう指示してみてください — ブロックされます。
+  </Step>
+</Steps>
+
+---
+
+## Agents SDK 向けフックの設定
+
+[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) を使って開発している場合、同じフックシステムをプログラムから利用できます。
+
+<Steps>
+  <Step title="プロジェクトに failproofai をインストールする">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="エージェントにフックを設定する">
+    エージェントプロセスの作成時にフックコマンドを渡します。フックは Claude Code と同じように、stdin/stdout の JSON を介して起動されます。
+
+    ```bash
+    failproofai --hook PreToolUse   # 各ツールの実行前に呼び出される
+    failproofai --hook PostToolUse  # 各ツールの実行後に呼び出される
+    ```
+  </Step>
+  <Step title="エージェント用のカスタムポリシーを作成する">
+    ```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="カスタムポリシーをインストールする">
+    ```bash
+    failproofai policies --install --custom ./my-agent-policies.js
+    ```
+  </Step>
+</Steps>
+
+---
+
+## 破壊的なコマンドをブロックする
+
+最もよく使われる設定 — エージェントが取り消し不可能な操作を行うのを防ぎます。
+
+```bash
+failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
+```
+
+この設定の効果:
+- `block-sudo` — すべての `sudo` コマンドをブロック
+- `block-rm-rf` — 再帰的なファイル削除をブロック
+- `block-force-push` — `git push --force` をブロック
+- `block-curl-pipe-sh` — リモートスクリプトのシェルへのパイプをブロック
+
+---
+
+## シークレットの漏洩を防ぐ
+
+ツールの出力に含まれる認証情報をエージェントが参照・漏洩するのを防ぎます。
+
+```bash
+failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
+```
+
+これらは `PostToolUse` で実行されます。ツールの実行後、エージェントが出力を受け取る前にスクラブ処理が行われます。
+
+---
+
+## エージェントの待機時に Slack へアラートを送信する
+
+通知フックを使って、アイドル状態のアラートを 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 {
+      // Slack に接続できない場合でもエージェントをブロックしない
+    }
+
+    return allow();
+  },
+});
+```
+
+インストール:
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
+```
+
+---
+
+## エージェントをブランチに固定する
+
+エージェントが他のブランチに切り替えたり、保護されたブランチにプッシュしたりするのを防ぎます。
+
+```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();
+  },
+});
+```
+
+---
+
+## コミット前にテストを要求する
+
+コミット前にテストを実行するようエージェントに促します。
+
+```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();
+  },
+});
+```
+
+---
+
+## 本番リポジトリをロックダウンする
+
+プロジェクトレベルの設定をコミットして、チーム全員が同じポリシーを適用できるようにします。
+
+リポジトリに `.failproofai/policies-config.json` を作成します:
+
+```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"]
+    }
+  }
+}
+```
+
+コミットします:
+
+```bash
+git add .failproofai/policies-config.json
+git commit -m "Add failproofai team policies"
+```
+
+failproofai をインストール済みのすべてのチームメンバーに、これらのルールが自動的に適用されます。
+
+---
+
+## その他の使用例
+
+リポジトリの [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) ディレクトリには以下が含まれています:
+
+| ファイル | 内容 |
+|------|---------------|
+| `policies-basic.js` | 基本ポリシー — 本番環境への書き込み、force-push、パイプスクリプトのブロック |
+| `policies-notification.js` | アイドル通知とセッション終了時の Slack アラート |
+| `policies-advanced/index.js` | トランジティブインポート、非同期フック、PostToolUse の出力スクラブ、Stop イベントの処理 |

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

@@ -0,0 +1,38 @@
+---
+title: "エージェント向け"
+description: "1つのコマンドでFailproof AIの知識をコーディングエージェントに追加できます。Claude Code、Cursor、Windsurfなどに対応しています。"
+---
+
+1つのコマンドで、Failproof AIのリファレンス全体をコーディングエージェントに追加できます。Claude Code、Cursor、Windsurf、その他スキルに対応しているエージェントであればどれでも利用可能です。
+
+```bash
+npx skills add https://docs.befailproof.ai
+```
+
+`npx skills` はインストール済みのエージェントを自動検出し、それぞれに適したフォーマットでスキルを追加します。
+
+## スキルがカバーする内容
+
+| エリア | 含まれる内容 |
+|------|----------------|
+| ポリシー | 組み込みポリシー名、イベントタイプ、パラメータ、有効化/無効化 |
+| カスタムポリシー | `customPolicies.add()`、マッチフィルター、`allow`/`deny`/`instruct` API |
+| コンテキストオブジェクト | `ctx.eventType`、`ctx.toolName`、`ctx.toolInput`、`ctx.session` |
+| 設定 | `policies-config.json` の構造、スコープのマージ、`policyParams` |
+| CLI | `failproofai policies --install`、`--uninstall`、`--custom`、スコープ |
+| ダッシュボード | セッションビューワー、ポリシーアクティビティ、環境変数 |
+| アーキテクチャ | フックハンドラーのフロー、終了コード、stdin/stdout コントラクト |
+
+## スキルの内容は完全ですか？
+
+Mintlify はナビゲーション内のすべてのページから `llms.txt` を生成します。Failproof AI のドキュメントは API 全体をカバーしており、すべてのポリシー、オプション、サンプルが含まれています。不足している内容が見つかった場合は、`https://docs.befailproof.ai/llms-full.txt` でソースを確認してください。
+
+特定のコンテキストに絞り込みたい場合は、対象ページに直接リンクしてください：
+
+```bash
+# カスタムポリシー API のみ
+npx skills add https://docs.befailproof.ai/custom-policies
+
+# 組み込みポリシーのみ
+npx skills add https://docs.befailproof.ai/built-in-policies
+```

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

@@ -0,0 +1,134 @@
+---
+title: はじめに
+description: "failproofai をインストールし、ポリシーを有効化して、エージェントを安定稼働させましょう"
+icon: rocket
+---
+
+## 必要環境
+
+- **Node.js** >= 20.9.0
+- **Bun** >= 1.3.0（オプション — ソースからビルドする場合のみ必要）
+
+---
+
+## インストール
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+---
+
+## クイックスタート
+
+<Steps>
+  <Step title="ポリシーを有効化する">
+    ポリシーとは、エージェントのツール呼び出しの前後に実行されるルールです。破壊的なコマンドの実行、シークレットの漏洩、その他の障害パターンを、実害が生じる前に検出します。
+
+    ```bash
+    failproofai policies --install
+    ```
+
+    このコマンドは Claude Code の `settings.json` にフックエントリを書き込みます。単一プロジェクト向けにインストールしたり、特定のポリシーだけを選択することも可能です。
+
+    ```bash
+    failproofai policies --install --scope project
+    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
+    ```
+  </Step>
+  <Step title="確認する">
+    ```bash
+    failproofai policies
+    ```
+
+    すべてのポリシー、その有効・無効の状態、および設定済みのパラメータを表示します。
+  </Step>
+  <Step title="ダッシュボードを起動する">
+    ```bash
+    failproofai
+    ```
+
+    `http://localhost:8020` にローカルダッシュボードを開きます。セッションの閲覧、ツール呼び出しの検査、ポリシーの管理が行えます。
+  </Step>
+  <Step title="エージェントを実行する">
+    通常通り Claude Code を起動してください。エージェントが危険な操作を試みた場合、failproofai が自動的に介入します。エージェントを無人で稼働させておき、何が起きたかをダッシュボードで後から確認できます。
+  </Step>
+</Steps>
+
+---
+
+## ポリシーの仕組み
+
+エージェントがツールを実行するたびに、Claude Code はサブプロセスとして failproofai を呼び出します。
+
+```text
+Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
+                                                 evaluates policies
+                                                 writes decision to stdout
+```
+
+各ポリシーは次の3つのいずれかの判定を返します。
+
+- **allow** — エージェントは通常通り処理を続行する
+- **deny** — アクションがブロックされ、エージェントにその理由が通知される
+- **instruct** — エージェントのプロンプトに追加のコンテキストが付加される
+
+<Note>
+ポリシーはローカルプロセス上で実行されます。リモートサービスへのデータ送信は一切行われません。
+</Note>
+
+---
+
+## データの保存場所
+
+すべての設定とログはお使いのマシン上に保存されます。
+
+| パス | 保存内容 |
+|------|----------------|
+| `~/.failproofai/policies-config.json` | グローバルポリシー設定 |
+| `~/.failproofai/hook-activity.jsonl` | フック実行履歴 |
+| `~/.failproofai/hook.log` | カスタムフックエラーのデバッグログ |
+| `.failproofai/policies-config.json` | プロジェクト別設定（コミット対象） |
+| `.failproofai/policies-config.local.json` | 個人用オーバーライド（gitignore 対象） |
+
+---
+
+## アンインストール
+
+```bash
+failproofai policies --uninstall
+```
+
+`~/.claude/settings.json` からフックエントリを削除します。`~/.failproofai/` 内の設定ファイルは保持されます。
+
+---
+
+## 次のステップ
+
+<CardGroup cols={2}>
+
+<Card title="設定" icon="gear" href="/ja/configuration">
+  スコープと設定ファイルのフォーマット
+</Card>
+
+<Card title="組み込みポリシー" icon="shield" href="/ja/built-in-policies">
+  パラメータ付き全 26 ポリシーの一覧
+</Card>
+
+<Card title="カスタムポリシー" icon="code" href="/ja/custom-policies">
+  JavaScript で独自のポリシーを作成する
+</Card>
+
+<Card title="エージェントモニター" icon="chart-line" href="/ja/dashboard">
+  セッションの監視とポリシーアクティビティの確認
+</Card>
+
+</CardGroup>

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

@@ -0,0 +1,57 @@
+---
+title: Failproof AI
+description: "AIエージェントの信頼性を保ち、自律的な動作を維持するフックとポリシーを管理する"
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+**Claude Code** および **Agents SDK** 向けの、AIエージェントの信頼性を保ち自律的な動作を維持するフックとポリシー。
+
+AIエージェントは予測可能な形で失敗します。破壊的なコマンドを実行したり、シークレットを漏洩させたり、タスクから逸脱したり、ループにはまったり、mainブランチに直接プッシュしたりします。放置すれば、小さな失敗が連鎖して大きな問題へと発展します。
+
+Failproof AI はこの問題を **ポリシー** によって解決します。ポリシーとは、エージェントのすべてのツール呼び出しにフックするルールであり、**障害の検出**、**軽減処置**（ブロック・指示・サニタイズ）、そして注意が必要な場合の **アラート通知** を行います。ローカルダッシュボードで後から内容を確認することもできます。
+
+すべてはローカルで動作します。データが外部に送信されることはありません。
+
+## はじめに
+
+<CardGroup cols={2}>
+
+<Card title="26個の組み込みポリシー" icon="shield" href="/ja/built-in-policies">
+  破壊的なコマンドのブロック、シークレットの漏洩防止、エージェントをプロジェクト境界内に制限するなど、すぐに使える機能が揃っています。
+</Card>
+
+<Card title="カスタムポリシー" icon="code" href="/ja/custom-policies">
+  シンプルな allow / deny / instruct APIを使って、JavaScriptで独自のルールを記述できます。
+</Card>
+
+<Card title="エージェントモニター" icon="chart-line" href="/ja/dashboard">
+  離席中にエージェントが何をしたか確認できます。セッションの閲覧、ツール呼び出しの検査、ポリシーが発動した箇所のレビューが可能です。
+</Card>
+
+<Card title="簡単な設定" icon="gear" href="/ja/configuration">
+  コードを書かずにポリシーを調整できます。許可リスト、保護ブランチ、しきい値をプロジェクト単位またはグローバルに設定できます。
+</Card>
+
+</CardGroup>
+
+## クイックスタート
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # enable policies
+failproofai                      # launch the dashboard
+```
+
+詳しい手順については、[入門ガイド](/ja/getting-started)をご覧ください。