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

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

@@ -1,353 +0,0 @@
----
-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: 規約ベース（推奨）
-
-`.failproofai/policies/` に `*policies.{js,mjs,ts}` ファイルを配置するだけで自動的にロードされます — フラグや設定変更は不要です。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 に表示されます。1つの `deny` で以降のすべての評価がショートサーキットされます。
-
-`instruct(message)` — メッセージは現在のツール呼び出しに対する Claude のコンテキストに追加されます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。
-
-<Tip>
-`policyParams` の `hint` フィールドを追加することで、コード変更なしに `deny` または `instruct` メッセージに追加のガイダンスを付加できます。これはカスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）ポリシーでも機能します。詳しくは[設定 → hint](/ja/configuration#hint-cross-cutting)をご覧ください。
-</Tip>
-
-### 情報提供用のallowメッセージ
-
-`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.");
-
-    // ... check branch status ...
-    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

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