failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/ko/agenteye/telemetry.mdx

@@ -0,0 +1,52 @@
+---
+title: "성능 메트릭"
+description: "모델, 도구, 훅이 느려지거나 비용이 급증하는 순간을 즉시 파악하고, 사용자가 체감하기 전에 테일 레이턴시 스파이크를 잡아내세요."
+---
+
+
+모델, 도구, 훅이 느려지거나 비용이 급증하는 순간을 즉시 파악하고, 사용자가 체감하기 전에 테일 레이턴시 스파이크를 잡아내세요. 세 개의 전용 페이지가 원시 타이밍 데이터를 한눈에 읽을 수 있는 p50, p95, p99 수치로 변환해 줍니다.
+
+![Models 페이지에 레이턴시 히트맵, 백분위 밴드, 모델별 토큰·비용·컨텍스트 윈도우 수치가 표시된 화면](/agenteye/images/models.png)
+*Models 페이지: 레이턴시 히트맵, 백분위 밴드, 모델별 토큰 수·예상 비용·컨텍스트 윈도우 사용률.*
+
+## 평균값이 최악의 실행을 숨기지 못하게 하세요
+
+평균 레이턴시 수치는 안심감을 주지만 실제로는 쓸모가 없습니다. 50번 중 한 번 멈춰서 새벽 2시에 온콜을 깨우는 그 호출을 평균이 덮어버리기 때문입니다. Models, Tools, Hooks 페이지는 그런 식으로 동작하지 않습니다. 세 페이지는 동일한 구조를 공유하므로 한 번만 익히면 됩니다.
+
+- **24구간 스파크라인**: 추세를 한눈에 파악 — 상황이 나빠지고 있는가?
+- **바이탈 스트립**: p50, p95, p99 레이턴시를 나란히 표시해 일반적인 실행과 테일을 함께 확인.
+- **레이턴시 히트맵**: 24개 시간 구간 × 레이턴시 버킷으로, 느린 호출이 *언제* 집중됐는지 시각화.
+- **백분위 밴드**: p50 선을 중심으로 p25~p75 및 p10~p90 음영 리본과 p99 점이 표시되어, 분포가 평균으로 묻히지 않고 그대로 드러남.
+
+히트맵과 밴드를 연결하는 공유 호버 크로스헤어가 있어, 테일 스파이크가 두 차트에서 동일한 시점으로 정렬됩니다. 단일 평균선 뒤에 숨지 않죠. 세 페이지 모두 대시보드의 **observe** 섹션에서 찾을 수 있으며, 조직 단위로 범위가 설정되고 날짜 범위·환경·에이전트·세션별로 필터링할 수 있습니다.
+
+## Models: 각 모델의 정확한 비용을 파악하세요
+
+Models 페이지(위 이미지 참고)는 청구서를 받을 때 항상 드는 두 가지 질문에 답합니다. 어떤 모델인가, 그리고 얼마인가. 공유 레이턴시 뷰 위에 **모델별 토큰 소비량**, **예상 비용**, **컨텍스트 윈도우 사용률**이 추가되므로, 프롬프트가 통제 불능으로 늘어나는 상황이나 임박한 압축(compaction)을 미리 감지할 수 있습니다.
+
+Failproof AI Observability는 일반적인 모델 ID를 자동으로 인식합니다. 윈도우 크기가 잘못 표시되거나 자체 프라이빗 모델을 사용하는 경우, **Settings**의 **model context windows**에서 수정하거나 추가하면 사용률 수치에 즉시 반영됩니다.
+
+## Tools: 느린 것과 고장난 것을 구분하세요
+
+도구 호출은 느릴 수도 있고, 조용히 실패하고 있을 수도 있습니다. 로그를 뒤지는 것이 아니라 몇 초 안에 어느 쪽인지 알아야 합니다.
+
+![Tools 페이지에 공유 레이턴시 히트맵과 백분위 밴드, 성공·실패 분류, 도구 분포 막대가 표시된 화면](/agenteye/images/tools.png)
+*Tools 페이지: 동일한 히트맵과 백분위 밴드에 성공·실패 분류 및 도구 분포 막대 추가.*
+
+공유 레이턴시 뷰와 함께 Tools 페이지는 **성공·실패 분류**와 **도구 분포 막대**를 제공합니다. 어떤 도구를 가장 많이 사용하는지, 어떤 도구가 에러 버짓을 갉아먹고 있는지 한눈에 확인할 수 있습니다.
+
+## Hooks: 문제의 훅과 트리거를 정확히 찾아내세요
+
+라이프사이클 훅이 실행을 지연시킬 때, "훅이 느리다"는 말만으로는 조치를 취할 수 없습니다. Hooks 페이지는 문제가 되는 바로 그 훅으로 곧장 안내합니다.
+
+![Hooks 페이지에 훅 이름과 트리거 이벤트별로 분류된 레이턴시가 공유 히트맵과 백분위 밴드 위에 표시된 화면](/agenteye/images/hooks.png)
+*Hooks 페이지: 훅 이름과 트리거 이벤트별로 분류된 레이턴시.*
+
+동일한 레이턴시 히트맵과 백분위 밴드 위에서, Hooks 페이지는 활동을 **훅 이름**과 **트리거 이벤트**별로 세분화합니다. 주의가 필요한 단 하나의 훅과 단 하나의 이벤트를 바로 찾아낼 수 있습니다.
+
+## 관련 문서
+
+- [이벤트 스트림](/ko/agenteye/event-stream): 모든 이벤트의 실시간 컬러 코딩 추적.
+- [세션](/ko/agenteye/sessions): 이벤트를 실행 단위의 단일 행으로 집계하고 실행 그래프를 열람.
+- [에러 트래킹](/ko/agenteye/error-tracking): 대시보드에서 빨간색으로 표시된 모든 항목을 위한 단일 트리아지 화면.
+- [대시보드](/ko/agenteye/dashboards): 전체 플릿에 걸친 롤업 뷰.

package/.next/standalone/docs-old/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로 제한합니다. 이를 초과하는 페이로드는 폐기되며 모든 정책이 암묵적으로 허용됩니다.
+
+### 응답 형식
+
+**거부 (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에게 정보성 컨텍스트를 전달할 수 있게 해줍니다. 훅 핸들러는 **stdout**에 다음 JSON을 작성합니다 (설정 파일이 아닌, 위의 거부 및 지시 응답과 마찬가지로 핸들러가 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에서 커스텀 정책 로드 (설정된 경우)
+  → 커스텀 정책을 정책 레지스트리에 등록
+  → 모든 정책 평가 (빌트인 먼저, 이후 커스텀)
+      → 첫 번째 거부에서 단락 평가
+      → 지시 결정은 누적
+      → 허용 메시지는 누적
+  → JSON 결정을 stdout에 기록
+  → ~/.failproofai/hook-activity/current.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`는 39개의 빌트인 정책을 `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`는 이후 커스텀 정책을 단락 평가하지만 (빌트인 정책은 이미 모두 실행된 상태입니다).
+
+---
+
+## 활동 로깅
+
+각 훅 이벤트 후 핸들러는 `~/.failproofai/hook-activity/current.jsonl`에 JSONL 행을 추가하며, 지정된 페이지 크기에 도달하면 `page-<timestamp>-<seq>.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, 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   ← CLI 세션별 내보내기 (JSONL 또는 JSON)
+```
+
+**데이터 흐름:**
+
+- 페이지 컴포넌트는 `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       # 39개 정책 정의
+│   ├── 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 / remove / list 작업
+│   ├── install-prompt.ts         # 대화형 정책 선택 프롬프트
+│   ├── hook-logger.ts            # hook.log에 로깅
+│   ├── hook-activity-store.ts    # hook-activity/에 활동 영속화
+│   └── 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 테스트
+```