failproofai 0.0.2 → 0.0.3

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)をご覧ください。

package/.next/standalone/docs/ja/package-aliases.mdx

@@ -0,0 +1,82 @@
+---
+title: パッケージエイリアス
+description: "登録済みのタイポスクワット防止エイリアスとその仕組み"
+icon: copy
+---
+
+## 公式パッケージ
+
+npmの正式パッケージは **`failproofai`** です：
+
+```bash
+npm install -g failproofai
+# または
+bun add -g failproofai
+```
+
+---
+
+## エイリアス名を所有している理由
+
+タイポスクワッティングは、攻撃者が人気パッケージ名から1文字違いのパッケージ名を登録するサプライチェーン攻撃の一般的な手口です。インストールコマンドをうっかり誤入力してしまったユーザーは、フルシステムアクセス権を持つ攻撃者制御のコードを実行してしまいます — これはまさに Failproof AI が防御を目的とした脅威の一種です。
+
+この攻撃対象を排除するために、**`failproofai` の一般的なスペルミスや表記バリアントをすべてnpm上で先回りして取得しています**。これらの名前はいずれも第三者に登録されることはありません。それぞれは実際の `failproofai` パッケージへインストール・委譲する薄いプロキシです。
+
+---
+
+## 登録済みエイリアス
+
+**表記バリアント** — 「failproof ai」のさまざまな書き方：
+
+| パッケージ | ステータス |
+|-----------|-----------|
+| `failproof` | ✅ 公開済み |
+| `failproof-ai` | ⏳ npmサポート対応待ち |
+| `fail-proof-ai` | ⏳ npmサポート対応待ち |
+| `failproof_ai` | ⏳ npmサポート対応待ち |
+| `fail_proof_ai` | ⏳ npmサポート対応待ち |
+| `fail-proofai` | ⏳ npmサポート対応待ち |
+
+**`failprof*` タイポ** — 「proof」から `o` が1文字抜けたもの：
+
+| パッケージ | ステータス |
+|-----------|-----------|
+| `failprof` | ✅ 公開済み |
+| `failprof-ai` | ✅ 公開済み |
+| `failprofai` | ⏳ npmサポート対応待ち |
+| `fail-prof-ai` | ⏳ npmサポート対応待ち |
+| `failprof_ai` | ⏳ npmサポート対応待ち |
+
+**`faliproof*` タイポ** — `a` と `i` が入れ替わったもの：
+
+| パッケージ | ステータス |
+|-----------|-----------|
+| `faliproof` | ✅ 公開済み |
+| `faliproof-ai` | ✅ 公開済み |
+| `faliproofai` | ⏳ npmサポート対応待ち |
+
+> **対応待ちの理由は？** npmのスパム防止ポリシーにより、句読点を除去して類似度チェックを行った際に既存パッケージと同一文字列に正規化される名前はブロックされます。アンチスクワッティング目的でこれらの名前を予約するよう、npmサポートに連絡済みです。承認され次第、順次有効化されます。
+
+公開済みのエイリアスが弊社所有であることは次のコマンドで確認できます：
+
+```bash
+npm info failproof
+# 確認ポイント：maintainersフィールドに "ExosphereHost Inc." があること
+```
+
+---
+
+## エイリアスの仕組み
+
+各エイリアスパッケージは：
+
+1. `failproofai` を依存関係として宣言しているため、インストール時に実際のパッケージ（`postinstall` フックのセットアップを含む）が実行されます
+2. 自身の名前に対応するバイナリ（例：`failprof-ai`）を公開しており、すべての引数を `failproofai` バイナリへプロキシします
+
+プロキシは2行のNodeスクリプトで構成されており、ロジックも、ネットワーク呼び出しも、`failproofai` 自体が行うもの以外のデータ収集も一切ありません。
+
+---
+
+## 見落としている名前を見つけた場合
+
+[exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues) にIssueを作成してください。登録対応いたします。