failproofai 0.0.6-beta.2 → 0.0.6-beta.4

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

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

@@ -1,332 +0,0 @@
----
-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로 제한합니다. 이를 초과하는 페이로드는 폐기되며 모든 정책은 암묵적으로 허용됩니다.
-
-### 응답 형식
-
-**거부 (PreToolUse):**
-```json
-{
-  "hookSpecificOutput": {
-    "permissionDecision": "deny",
-    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
-  }
-}
-```
-
-**거부 (PostToolUse):**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Blocked by failproofai because: API key detected in output"
-  }
-}
-```
-
-**지시 (Stop 이벤트 제외한 모든 이벤트):**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
-  }
-}
-```
-
-**Stop 이벤트 지시:**
-- 종료 코드: `2`
-- 이유는 stdout이 아닌 stderr에 기록됨
-
-**허용:**
-- 종료 코드: `0`
-- stdout 비어 있음
-
-**메시지와 함께 허용:**
-
-`allow(message)`를 사용하면 작업이 허용되더라도 정책이 Claude에게 정보성 컨텍스트를 전송할 수 있습니다. 훅 핸들러는 다음 JSON을 **stdout**에 기록합니다 (설정 파일이 아닌, 위의 거부 및 지시 응답과 동일하게 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에서 커스텀 정책 로드 (설정된 경우)
-  → 커스텀 정책을 정책 레지스트리에 등록
-  → 모든 정책 평가 (내장 정책 먼저, 그 다음 커스텀)
-      → 첫 번째 거부가 단락(short-circuit)
-      → 지시 결정이 누적됨
-      → 허용 메시지가 누적됨
-  → JSON 결정을 stdout에 기록
-  → 이벤트를 ~/.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`가 반환된 경우 거부 응답을 내보냅니다.
-- `instruct` 반환이 수집된 경우 모든 메시지를 결합한 단일 지시 응답을 내보냅니다.
-- 그렇지 않으면 허용 응답을 내보냅니다 (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. 모든 `from "failproofai"` 임포트를 실제 dist 경로로 재작성하여 `customPolicies`가 동일한 `globalThis` 레지스트리로 해결되도록 합니다.
-4. ESM 호환성을 보장하기 위해 전이적 로컬 임포트를 재귀적으로 재작성합니다.
-5. 임시 `.mjs` 파일을 작성하고 엔트리 파일을 `import()`합니다.
-6. `getCustomHooks()`를 호출하여 등록된 훅을 가져옵니다.
-7. `finally` 블록에서 모든 임시 파일을 정리합니다.
-
-오류 발생 시(파일 없음, 구문 오류, 임포트 실패), 오류는 `~/.failproofai/hook.log`에 기록되고 로더는 빈 배열을 반환합니다. 내장 정책은 영향을 받지 않습니다.
-
-커스텀 정책은 모든 내장 정책 이후에 평가됩니다. 커스텀 정책의 `deny`는 이후 커스텀 정책의 실행을 단락(short-circuit)시키지만, 이 시점에서 모든 내장 정책은 이미 실행된 상태입니다.
-
----
-
-## 활동 로깅
-
-각 훅 이벤트 후, 핸들러는 `~/.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
-}
-```
-
-허용이 아닌 결정을 내린 정책당 한 줄씩 기록됩니다. 허용 결정은 기록하지 않습니다(파일 크기를 작게 유지하기 위함).
-
----
-
-## 대시보드 아키텍처
-
-대시보드는 App Router를 사용하는 **Next.js 16** 애플리케이션으로, React 서버 컴포넌트와 서버 액션을 활용합니다.
-
-```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 라우터 (훅 / 대시보드 / 설치 등)
-├── 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 테스트
-```