failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,357 @@
+---
+title: カスタムポリシー
+description: "JavaScriptで独自のポリシーを記述する — 規約の強制、ドリフトの防止、失敗の検出、外部システムとの連携"
+icon: code
+---
+
+カスタムポリシーを使えば、あらゆるエージェントの動作に対してルールを定義できます。プロジェクト規約の強制、ドリフトの防止、破壊的な操作のゲート制御、スタックしたエージェントの検出、Slackや承認ワークフローとの連携などが実現できます。組み込みポリシーと同じフックイベントシステムおよび `allow`、`deny`、`instruct` の判定を使用します。
+
+---
+
+## クイック例
+
+```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();
+  },
+});
+```
+
+インストール:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## カスタムポリシーの読み込み方法（2通り）
+
+### 方法1: 規約ベース（推奨、v0.0.2-beta.7+）
+
+`*policies.{js,mjs,ts}` ファイルを `.failproofai/policies/` に置くだけで自動的に読み込まれます。フラグや設定変更は不要です。gitフックと同じ仕組みです。ファイルを置けばそのまま動きます。
+
+```
+# プロジェクトレベル — gitにコミットしてチームと共有
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# ユーザーレベル — 個人用、全プロジェクトに適用
+~/.failproofai/policies/my-policies.mjs
+```
+
+**動作の仕組み:**
+- プロジェクトディレクトリとユーザーディレクトリの両方がスキャンされます（どちらか一方ではなく、両方が適用されます）
+- 各ディレクトリ内ではファイルがアルファベット順に読み込まれます。順序を制御するには `01-`、`02-` などのプレフィックスを付けてください
+- `*policies.{js,mjs,ts}` に一致するファイルのみ読み込まれ、それ以外のファイルは無視されます
+- 各ファイルは独立して読み込まれます（ファイル単位でフェイルオープン）
+- 明示的な `--custom` や組み込みポリシーと共存できます
+
+<Tip>
+規約ポリシーはチーム全体でポリシーを共有する最も簡単な方法です。`.failproofai/policies/` をgitにコミットすれば、すべてのチームメンバーが自動的に適用されます。
+</Tip>
+
+### 方法2: 明示的なファイルパス
+
+```bash
+# カスタムポリシーファイルを指定してインストール
+failproofai policies --install --custom ./my-policies.js
+
+# ポリシーファイルのパスを変更
+failproofai policies --install --custom ./new-policies.js
+
+# 設定からカスタムポリシーのパスを削除
+failproofai policies --uninstall --custom
+```
+
+解決された絶対パスは `policies-config.json` の `customPoliciesPath` に保存されます。ファイルはフックイベントごとに新たに読み込まれます。イベント間でのキャッシュはありません。
+
+### 両方を併用する
+
+規約ポリシーと明示的な `--custom` ファイルは共存できます。読み込み順序:
+
+1. 明示的な `customPoliciesPath` ファイル（設定されている場合）
+2. プロジェクトの規約ファイル（`{cwd}/.failproofai/policies/`、アルファベット順）
+3. ユーザーの規約ファイル（`~/.failproofai/policies/`、アルファベット順）
+
+---
+
+## API
+
+### インポート
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+ポリシーを登録します。同一ファイル内で複数のポリシーを登録するために何度でも呼び出せます。
+
+```ts
+customPolicies.add({
+  name: string;                         // 必須 - 一意の識別子
+  description?: string;                 // `failproofai policies` の出力に表示される
+  match?: { events?: HookEventType[] }; // イベントタイプでフィルタリング。省略するとすべてにマッチ
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### 判定ヘルパー
+
+| 関数 | 効果 | 使用場面 |
+|----------|--------|----------|
+| `allow()` | 操作を静かに許可する | アクションが安全でメッセージが不要な場合 |
+| `deny(message)` | 操作をブロックする | エージェントがこのアクションを取るべきでない場合 |
+| `instruct(message)` | ブロックせずにコンテキストを追加する | エージェントに追加のコンテキストを与えて軌道を維持する場合 |
+
+`deny(message)` — メッセージは `"Blocked by failproofai:"` というプレフィックス付きでClaudeに表示されます。一つの `deny` が発生すると、以降の評価はすべてスキップされます。
+
+`instruct(message)` — メッセージは現在のツール呼び出しに対するClaudeのコンテキストに追記されます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。
+
+<Tip>
+`policyParams` の `hint` フィールドを追加することで、`deny` や `instruct` のメッセージに追加のガイダンスを付け加えられます。コードの変更は不要です。これはカスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）ポリシーでも機能します。詳細は [設定 → hint](/ja/configuration#hint-cross-cutting) を参照してください。
+</Tip>
+
+### 情報提供用のallowメッセージ（ベータ版）
+
+<Note>
+`allow(message)` はv0.0.2-beta.3から利用できるベータ機能です。APIは将来のリリースで変更される可能性があります。それ以前のバージョンでは引数なしの `allow()` のみサポートされています。
+</Note>
+
+`allow(message)` は操作を許可し**つつ**、情報提供のメッセージをClaudeに送信します。メッセージはフックハンドラーのstdoutレスポンスの `additionalContext` として配信されます。これは `instruct` と同じ仕組みですが、意味的に異なります。警告ではなくステータスの更新として扱われます。
+
+| 関数 | 効果 | 使用場面 |
+|----------|--------|----------|
+| `allow(message)` | 許可してClaudeにコンテキストを送信する | チェックが通ったことを確認する、またはチェックがスキップされた理由を説明する場合 |
+
+ユースケース:
+- **ステータス確認:** `allow("All CI checks passed.")` — すべて正常であることをClaudeに伝える
+- **フェイルオープンの説明:** `allow("GitHub CLI not installed, skipping CI check.")` — チェックがスキップされた理由をClaudeに伝え、完全なコンテキストを提供する
+- **複数メッセージの蓄積:** 複数のポリシーがそれぞれ `allow(message)` を返した場合、すべてのメッセージが改行で結合されてまとめて配信されます
+
+```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.");
+
+    // ... ブランチのステータスを確認 ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### `PolicyContext` フィールド
+
+| フィールド | 型 | 説明 |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`、`"PostToolUse"`、`"Notification"`、`"Stop"` |
+| `toolName` | `string \| undefined` | 呼び出されるツール（例: `"Bash"`、`"Write"`、`"Read"`） |
+| `toolInput` | `Record<string, unknown> \| undefined` | ツールの入力パラメータ |
+| `payload` | `Record<string, unknown>` | Claude Code からの生のイベントペイロード全体 |
+| `session` | `SessionMetadata \| undefined` | セッションコンテキスト（以下を参照） |
+
+### `SessionMetadata` フィールド
+
+| フィールド | 型 | 説明 |
+|-------|------|-------------|
+| `sessionId` | `string` | Claude Code セッション識別子 |
+| `cwd` | `string` | Claude Code セッションの作業ディレクトリ |
+| `transcriptPath` | `string` | セッションのJSONLトランスクリプトファイルへのパス |
+
+### イベントタイプ
+
+| イベント | 発火タイミング | `toolInput` の内容 |
+|-------|--------------|----------------------|
+| `PreToolUse` | Claudeがツールを実行する前 | ツールの入力（例: Bashの場合 `{ command: "..." }`） |
+| `PostToolUse` | ツールの完了後 | ツールの入力 + `tool_result`（出力） |
+| `Notification` | Claudeが通知を送信するとき | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - フックは常に `allow()` を返す必要があります。通知をブロックすることはできません |
+| `Stop` | Claudeセッションが終了するとき | 空 |
+
+---
+
+## 評価順序
+
+ポリシーは以下の順序で評価されます:
+
+1. 組み込みポリシー（定義順）
+2. `customPoliciesPath` から読み込まれた明示的なカスタムポリシー（`.add()` の呼び出し順）
+3. プロジェクトの `.failproofai/policies/` からの規約ポリシー（ファイルはアルファベット順、ファイル内は `.add()` の呼び出し順）
+4. ユーザーの `~/.failproofai/policies/` からの規約ポリシー（ファイルはアルファベット順、ファイル内は `.add()` の呼び出し順）
+
+<Note>
+最初の `deny` が発生すると、以降のすべてのポリシーはスキップされます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。
+</Note>
+
+---
+
+## 推移的インポート
+
+カスタムポリシーファイルは相対パスを使ってローカルモジュールをインポートできます:
+
+```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");
+  },
+});
+```
+
+エントリファイルから到達可能なすべての相対インポートが解決されます。これは `from "failproofai"` のインポートを実際のdistパスに書き換え、ESM互換性を確保するために一時的な `.mjs` ファイルを作成することで実装されています。
+
+---
+
+## イベントタイプのフィルタリング
+
+`match.events` を使ってポリシーが発火するタイミングを制限できます:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // セッション終了時にのみ発火する
+    // ctx.session.transcriptPath にセッションの完全なログが含まれる
+    return allow();
+  },
+});
+```
+
+`match` を完全に省略すると、すべてのイベントタイプで発火します。
+
+---
+
+## エラーハンドリングと失敗モード
+
+カスタムポリシーは**フェイルオープン**です。エラーが発生しても組み込みポリシーをブロックしたり、フックハンドラーをクラッシュさせたりすることはありません。
+
+| 失敗 | 動作 |
+|---------|----------|
+| `customPoliciesPath` が未設定 | 明示的なカスタムポリシーは実行されない。規約ポリシーと組み込みポリシーは通常通り継続 |
+| ファイルが見つからない | `~/.failproofai/hook.log` に警告を記録。組み込みポリシーは継続 |
+| 構文/インポートエラー（明示的） | `~/.failproofai/hook.log` にエラーを記録。明示的なカスタムポリシーをスキップ |
+| 構文/インポートエラー（規約） | エラーを記録。そのファイルをスキップし、他の規約ファイルは引き続き読み込まれる |
+| `fn` が実行時に例外をスロー | エラーを記録。そのフックは `allow` として扱われる。他のフックは継続 |
+| `fn` が10秒以上かかる | タイムアウトを記録。`allow` として扱われる |
+| 規約ディレクトリが存在しない | 規約ポリシーは実行されない。エラーなし |
+
+<Tip>
+カスタムポリシーのエラーをデバッグするには、ログファイルを監視してください:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## 完全な例: 複数ポリシー
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// エージェントがsecretsディレクトリへ書き込むのを防ぐ
+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();
+  },
+});
+
+// エージェントの軌道維持: コミット前にテストを検証する
+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();
+  },
+});
+
+// フリーズ期間中の計画外の依存関係変更を防ぐ
+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 };
+```
+
+---
+
+## サンプル
+
+`examples/` ディレクトリにはすぐに使えるポリシーファイルが含まれています:
+
+| ファイル | 内容 |
+|------|----------|
+| `examples/policies-basic.js` | エージェントのよくある失敗モードをカバーする5つのスターターポリシー |
+| `examples/policies-advanced/index.js` | 高度なパターン: 推移的インポート、非同期呼び出し、出力のスクラビング、セッション終了フック |
+| `examples/convention-policies/security-policies.mjs` | 規約ベースのセキュリティポリシー（.envへの書き込みをブロック、gitの履歴書き換えを防止） |
+| `examples/convention-policies/workflow-policies.mjs` | 規約ベースのワークフローポリシー（テストのリマインダー、ファイル書き込みの監査） |
+
+### 明示的なファイルのサンプルを使用する
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### 規約ベースのサンプルを使用する
+
+```bash
+# プロジェクトレベルにコピー
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# またはユーザーレベルにコピー
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+インストールコマンドは不要です。次のフックイベント時に自動的にファイルが読み込まれます。

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>