failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,260 @@
+---
+title: テスト
+description: "ユニットテスト、E2Eテスト、テストヘルパー"
+icon: flask-vial
+---
+
+failproofai には2種類のテストスイートがあります：**ユニットテスト**（高速、モック使用）と**エンドツーエンドテスト**（実際のサブプロセス呼び出し）です。
+
+---
+
+## テストの実行
+
+```bash
+# ユニットテストを一度だけ実行
+bun run test:run
+
+# ウォッチモードでユニットテストを実行
+bun run test
+
+# E2Eテストを実行（事前セットアップが必要 - 下記参照）
+bun run test:e2e
+
+# ビルドせずに型チェック
+bunx tsc --noEmit
+
+# リント
+bun run lint
+```
+
+---
+
+## ユニットテスト
+
+ユニットテストは `__tests__/` に配置され、`happy-dom` を使った [Vitest](https://vitest.dev) で動作します。
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # 各組み込みポリシーのロジック
+    hooks-config.test.ts          # 設定の読み込みとスコープのマージ
+    policy-evaluator.test.ts      # パラメーター注入と評価順序
+    custom-hooks-registry.test.ts # globalThis レジストリの追加/取得/クリア
+    custom-hooks-loader.test.ts   # ESM ローダー、推移的インポート、エラーハンドリング
+    manager.test.ts               # インストール/削除/一覧表示の操作
+  components/
+    sessions-list.test.tsx        # セッションリストコンポーネント
+    project-list.test.tsx         # プロジェクトリストコンポーネント
+    ...
+  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
+```
+
+### ポリシーのユニットテストの書き方
+
+```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());
+  });
+});
+```
+
+---
+
+## エンドツーエンドテスト
+
+E2Eテストは実際の `failproofai` バイナリをサブプロセスとして起動し、JSON ペイロードを stdin にパイプして、stdout の出力と終了コードを検証します。これにより、Claude Code が使用する完全な統合パスをテストできます。
+
+### セットアップ
+
+E2Eテストはリポジトリのソースから直接バイナリを実行します。初回実行の前に、カスタムフックファイルが `'failproofai'` からインポートする際に使用する CJS バンドルをビルドしてください：
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+その後、テストを実行します：
+
+```bash
+bun run test:e2e
+```
+
+公開フック API（`src/hooks/custom-hooks-registry.ts`、`src/hooks/policy-helpers.ts`、または `src/hooks/policy-types.ts`）を変更した場合は、`dist/` を再ビルドしてください。
+
+### E2Eテストの構成
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # バイナリを起動し、ペイロード JSON をパイプして終了コード・stdout・stderr をキャプチャ
+    fixture-env.ts      # テストごとに独立した一時ディレクトリと設定ファイル
+    payloads.ts         # 各イベントタイプ向けの Claude 準拠ペイロードファクトリー
+  hooks/
+    builtin-policies.e2e.test.ts   # 実際のサブプロセスで各組み込みポリシーをテスト
+    custom-hooks.e2e.test.ts       # カスタムフックの読み込みと評価
+    config-scopes.e2e.test.ts      # プロジェクト/ローカル/グローバル間の設定マージ
+    policy-params.e2e.test.ts      # パラメーター付きポリシーへのパラメーター注入
+```
+
+### E2Eヘルパーの使い方
+
+**`FixtureEnv`** - テストごとに独立した環境：
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - 一時ディレクトリ。payload.cwd として渡すと .failproofai/policies-config.json を読み込む
+// env.home   - 独立したホームディレクトリ。実際の ~/.failproofai が混入しない
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` は `afterEach` クリーンアップを自動的に登録します。
+
+**`runHook`** - バイナリを呼び出す：
+
+```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`** - すぐに使えるペイロードファクトリー：
+
+```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)
+```
+
+### 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 は空
+  });
+});
+```
+
+### E2Eレスポンスの形式
+
+| 判定 | 終了コード | stdout |
+|----------|-----------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct（Stop 以外） | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop instruct | `2` | stdout は空、理由は stderr に出力 |
+| Allow | `0` | 空文字列 |
+
+### Vitest の設定
+
+E2Eテストは `vitest.config.e2e.mts` を使用し、以下の設定が適用されます：
+
+- `environment: "node"` - ブラウザのグローバル変数は不要
+- `pool: "forks"` - 真のプロセス分離（テストがサブプロセスを起動）
+- `testTimeout: 20_000` - 1テストあたり20秒（バイナリ起動 + フック評価）
+
+`forks` プールは重要です。スレッドベースのワーカーは `globalThis` を共有するため、サブプロセスを起動するテストに干渉する可能性があります。プロセスベースの forks ではこの問題を回避できます。
+
+---
+
+## CI
+
+マージ前に `bun run lint && bunx tsc --noEmit && bun run test:run && bun run build` の完全な CI 実行がパスする必要があります。E2Eスイートは別の CI ジョブとして並行して実行されます。
+
+マージ前チェックリストの全内容は [Contributing](../CONTRIBUTING.md) を参照してください。

package/.next/standalone/docs/ko/architecture.mdx

@@ -0,0 +1,332 @@
+---
+title: 아키텍처
+description: "훅 핸들러, 설정 로딩, 정책 평가가 내부적으로 동작하는 방식"
+icon: sitemap
+---
+
+이 문서는 failproofai가 내부적으로 어떻게 동작하는지 설명합니다. 훅 시스템이 에이전트 툴 호출을 가로채는 방식, 설정이 로드되고 병합되는 방식, 정책이 평가되는 방식, 그리고 대시보드가 에이전트 활동을 모니터링하는 방식을 다룹니다.
+
+---
+
+## 개요
+
+failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다:
+
+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 (베타):**
+
+v0.0.2-beta.3부터 `allow(message)`를 통해 정책이 작업을 허용하면서도 Claude에게 정보성 컨텍스트를 전달할 수 있습니다. 훅 핸들러는 다음 JSON을 **stdout**에 씁니다 (설정 파일이 아니라 deny 및 instruct 응답과 마찬가지로 Claude Code에 대한 핸들러의 응답입니다):
+
+```json
+// 훅 핸들러 프로세스가 stdout에 씁니다
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- 종료 코드: `0` (작업이 허용됨)
+- 여러 정책이 메시지와 함께 `allow`를 반환하면, 해당 메시지들이 줄바꿈으로 연결되어 하나의 `additionalContext` 문자열로 합쳐집니다
+- 어떤 정책도 메시지를 제공하지 않으면 stdout은 비어 있습니다 (기존 동작과 동일)
+
+### 처리 파이프라인
+
+`src/hooks/handler.ts`가 전체 파이프라인을 구현합니다:
+
+```text
+stdin JSON
+  → 페이로드 파싱 (최대 1 MB)
+  → 세션 메타데이터 추출 (session_id, cwd, tool_name, tool_input 등)
+  → readMergedHooksConfig(cwd)    ← 프로젝트 + 로컬 + 전역 설정 병합
+  → 해결된 파라미터로 활성화된 내장 정책 등록
+  → customPoliciesPath에서 커스텀 정책 로드 (설정된 경우)
+  → 커스텀 정책을 정책 레지스트리에 등록
+  → 모든 정책 평가 (내장 정책 먼저, 그 다음 커스텀)
+      → 첫 번째 deny가 나오면 즉시 중단
+      → instruct 결정은 누적됨
+      → allow 메시지는 누적됨
+  → stdout에 JSON 결정 출력
+  → ~/.failproofai/hook-activity.jsonl에 이벤트 저장
+  → 종료
+```
+
+LLM 호출 없이 일반적인 페이로드 기준으로 전체 프로세스가 100ms 이내에 완료됩니다.
+
+---
+
+## 설정 로딩
+
+`src/hooks/hooks-config.ts`가 세 단계 범위의 설정 로딩을 구현합니다.
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← 프로젝트  (최우선)
+[2] {cwd}/.failproofai/policies-config.local.json  ← 로컬
+[3] ~/.failproofai/policies-config.json             ← 전역   (최하위 우선순위)
+```
+
+병합 로직:
+- `enabledPolicies` - 세 파일 전체에서 중복 제거 후 합집합
+- `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. `customPolicies`가 동일한 `globalThis` 레지스트리로 해결될 수 있도록 모든 `from "failproofai"` 임포트를 실제 dist 경로로 재작성합니다.
+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
+}
+```
+
+non-allow 결정을 내린 정책당 한 줄이 기록됩니다. allow 결정은 파일 크기를 줄이기 위해 기록하지 않습니다.
+
+---
+
+## 대시보드 아키텍처
+
+대시보드는 App Router와 React 서버 컴포넌트 및 서버 액션을 사용하는 **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 레이어 없음).
+- 정책 페이지는 모든 변경 작업(토글, 파라미터 업데이트, 설치/제거)에 서버 액션을 사용합니다.
+- 세션 뷰어는 Claude의 JSONL 트랜스크립트 형식을 파싱하고 메시지와 툴 호출의 타임라인을 렌더링합니다.
+
+**주요 설계 결정:**
+
+- 데이터베이스 없음 - 모든 영구 상태는 일반 파일에 저장됩니다 (`~/.failproofai/`, `~/.claude/projects/`).
+- 변경 작업에 서버 액션 사용 - CRUD 작업에 REST API가 필요 없습니다.
+- 읽기 페이지에 React 서버 컴포넌트 사용 - 초기 로드 속도 향상, 데이터 패칭을 위한 클라이언트 번들 불필요.
+- 상호작용이 필요한 곳에서만 클라이언트 컴포넌트 사용 (정책 토글, 활동 검색, 로그 뷰어).
+
+---
+
+## 파일 구조
+
+```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 테스트
+```