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

package/.next/standalone/docs/ko/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
-```
-
----
-
-## 커스텀 정책을 로드하는 두 가지 방법
-
-### 방법 1: 컨벤션 기반 (권장)
-
-`*policies.{js,mjs,ts}` 파일을 `.failproofai/policies/` 디렉터리에 넣으면 자동으로 로드됩니다. 별도의 플래그나 설정 변경이 필요 없습니다. git 훅처럼 파일만 넣으면 바로 동작합니다.
-
-```
-# 프로젝트 레벨 — git에 커밋, 팀과 공유
-.failproofai/policies/security-policies.mjs
-.failproofai/policies/workflow-policies.mjs
-
-# 사용자 레벨 — 개인용, 모든 프로젝트에 적용
-~/.failproofai/policies/my-policies.mjs
-```
-
-**동작 방식:**
-- 프로젝트 디렉터리와 사용자 디렉터리 모두 스캔됩니다 (합집합 — 첫 번째 스코프 우선이 아님)
-- 각 디렉터리 내에서 파일은 알파벳 순으로 로드됩니다. 순서를 제어하려면 `01-`, `02-` 등의 접두사를 사용하세요
-- `*policies.{js,mjs,ts}` 패턴에 매칭되는 파일만 로드되며, 나머지 파일은 무시됩니다
-- 각 파일은 독립적으로 로드됩니다 (파일 단위로 fail-open)
-- 명시적 `--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에게 표시됩니다. 하나의 `deny`가 발생하면 이후의 모든 평가가 단락됩니다.
-
-`instruct(message)` - 메시지는 현재 도구 호출에 대한 Claude의 컨텍스트에 추가됩니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다.
-
-<Tip>
-`policyParams`의 `hint` 필드를 추가하면 코드 변경 없이 모든 `deny` 또는 `instruct` 메시지에 추가 안내를 덧붙일 수 있습니다. 이 기능은 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 정책 모두에서 동작합니다. 자세한 내용은 [Configuration → hint](/ko/configuration#hint-cross-cutting)를 참고하세요.
-</Tip>
-
-### 정보성 allow 메시지
-
-`allow(message)`는 작업을 허용하면서 **동시에** Claude에게 정보성 메시지를 전송합니다. 메시지는 훅 핸들러의 stdout 응답에서 `additionalContext`로 전달됩니다. `instruct`와 동일한 메커니즘을 사용하지만 의미론적으로 다릅니다. 경고가 아닌 상태 업데이트입니다.
-
-| 함수 | 효과 | 사용 시점 |
-|----------|--------|----------|
-| `allow(message)` | 허용하고 Claude에게 컨텍스트 전송 | 검사가 통과되었음을 확인하거나, 검사가 건너뛰어진 이유를 설명할 때 |
-
-사용 사례:
-- **상태 확인:** `allow("All CI checks passed.")` — Claude에게 모든 것이 정상임을 알림
-- **Fail-open 설명:** `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`를 완전히 생략하면 모든 이벤트 타입에서 실행됩니다.
-
----
-
-## 오류 처리 및 실패 모드
-
-커스텀 정책은 **fail-open** 방식으로 동작합니다. 오류가 발생해도 내장 정책이 차단되거나 훅 핸들러가 충돌하지 않습니다.
-
-| 실패 상황 | 동작 |
-|---------|----------|
-| `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/ko/dashboard.mdx

@@ -1,142 +0,0 @@
----
-title: 대시보드
-description: "에이전트 세션 모니터링, 툴 호출 검토, 정책 관리"
-icon: chart-line
----
-
-failproofai 대시보드는 AI 에이전트 세션을 모니터링하고 정책을 관리하기 위한 로컬 웹 애플리케이션입니다. 자리를 비운 사이 에이전트가 무엇을 했는지 확인하세요.
-
----
-
-## 대시보드 시작하기
-
-```bash
-failproofai
-```
-
-`http://localhost:8020`에서 열립니다.
-
-대시보드는 파일시스템에서 직접 데이터를 읽습니다 — Claude Code 프로젝트 폴더와 failproofai 설정 파일을 참조하며, 외부 서비스에는 아무것도 전송되지 않습니다.
-
----
-
-## 페이지
-
-### 프로젝트
-
-사용자 머신에서 발견된 모든 Claude Code 프로젝트를 나열합니다. 프로젝트는 `~/.claude/projects/` 경로(또는 `CLAUDE_PROJECTS_PATH`로 설정된 경로)에서 검색됩니다.
-
-각 프로젝트에 표시되는 정보:
-- 프로젝트 이름 (폴더 경로에서 파생)
-- 세션 수
-- 가장 최근 세션 활동 날짜
-
-프로젝트를 클릭하면 해당 세션 목록을 볼 수 있습니다.
-
-### 세션
-
-프로젝트 내 모든 세션을 나열합니다. 각 세션에 표시되는 정보:
-- 세션 ID
-- 시작 및 종료 타임스탬프
-- 툴 호출 수
-- 훅 활동 횟수 (실행된 정책 수)
-
-날짜 범위 필터와 세션 ID 검색을 사용해 목록을 좁힐 수 있습니다. 세션은 페이지네이션으로 표시됩니다.
-
-세션을 클릭하면 세션 뷰어가 열립니다.
-
-### 세션 뷰어
-
-세션 뷰어는 자율 에이전트에 대한 핵심 질문에 답합니다: 에이전트가 무엇을 했으며, 올바른 방향으로 동작했는가? 세션에서 발생한 모든 일의 타임라인을 보여줍니다:
-
-- **메시지** - Claude의 텍스트 응답과 사용자 프롬프트
-- **툴 호출** - Claude가 실행한 모든 툴과 입력 및 출력 내용
-- **정책 활동** - 각 툴 호출에 대해 어떤 정책이 실행되었고 어떤 결정을 내렸는지
-
-상단의 통계 바에는 세션 지속 시간, 총 툴 호출 수, 훅 결정 요약(allow / deny / instruct 횟수)이 표시됩니다.
-
-다운로드 버튼을 사용해 세션을 ZIP 또는 JSONL 파일로 내보낼 수 있습니다.
-
-### 정책
-
-정책 관리와 활동 검토를 위한 두 탭 페이지입니다.
-
-<Tabs>
-  <Tab title="정책 탭">
-  - 클릭 한 번으로 개별 정책을 켜거나 끄기 (`~/.failproofai/policies-config.json`에 저장됨)
-  - 정책을 펼쳐 파라미터 설정 (`policyParams`를 지원하는 정책의 경우)
-  - 지정된 스코프에 훅 설치 또는 제거
-  - 커스텀 정책 파일 경로 설정
-  </Tab>
-  <Tab title="활동 탭">
-  - 모든 세션에 걸쳐 실행된 모든 훅 이벤트의 전체 페이지네이션 히스토리
-  - 정책 이름, 세션 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가 아닌 호스트에서 접근하기
-
-**개발 모드**(`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(핫 모듈 리로드) 웹소켓에 대한 교차 출처 접근을 차단한 것으로, 개발 모드에서만 사용되는 기능입니다. 특정 호스트를 허용하려면 `--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>
-이 설정은 개발 모드에서만 적용됩니다. `failproofai`(프로덕션 모드)로 실행할 때는 HMR 웹소켓이 없으므로 교차 출처 개발 리소스 문제가 발생하지 않습니다.
-</Note>