@kood/claude-code 0.6.6 → 0.7.0

package/templates/.claude/skills/tauri-react-best-practices/rules/react-optimistic-update.md

@@ -0,0 +1,211 @@
+# useOptimistic으로 IPC 대기 시간 마스킹
+
+## 왜 중요한가
+
+Tauri Command 호출은 Rust ↔ JS 직렬화 오버헤드가 있어 최소 수십 ms 지연이 발생합니다. React 19의 `useOptimistic`을 사용하면 서버 응답 대기 없이 UI를 즉시 업데이트하여 사용자 경험을 개선할 수 있습니다.
+
+## ❌ 잘못된 패턴
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useState } from 'react'
+
+function TodoList({ initialTodos }: { initialTodos: Todo[] }) {
+  const [todos, setTodos] = useState(initialTodos)
+  const [loading, setLoading] = useState(false)
+
+  const addTodo = async (title: string) => {
+    setLoading(true)
+    // ❌ invoke 응답까지 사용자는 대기해야 함
+    const newTodo = await invoke<Todo>('create_todo', { title })
+    setTodos(prev => [...prev, newTodo])
+    setLoading(false)
+  }
+
+  return (
+    <div>
+      {loading && <Spinner />}
+      {todos.map(todo => <TodoItem key={todo.id} todo={todo} />)}
+      <button onClick={() => addTodo('New Task')}>Add</button>
+    </div>
+  )
+}
+```
+
+**문제점:**
+- 사용자는 Rust 응답까지 대기 (느린 UX)
+- 네트워크/IPC 지연이 체감됨
+- 로딩 스피너로 인한 UI 깜빡임
+
+## ✅ 올바른 패턴
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useOptimistic, startTransition, useState } from 'react'
+
+type Todo = {
+  id: string
+  title: string
+  completed: boolean
+  pending?: boolean
+}
+
+function TodoList({ initialTodos }: { initialTodos: Todo[] }) {
+  const [todos, setTodos] = useState(initialTodos)
+  const [optimisticTodos, addOptimistic] = useOptimistic(
+    todos,
+    (current, newTodo: Todo) => [...current, { ...newTodo, pending: true }]
+  )
+
+  const addTodo = async (title: string) => {
+    const tempTodo: Todo = {
+      id: crypto.randomUUID(),
+      title,
+      completed: false
+    }
+
+    startTransition(async () => {
+      addOptimistic(tempTodo) // ✅ 즉시 UI에 반영
+
+      try {
+        const savedTodo = await invoke<Todo>('create_todo', { title })
+        setTodos(prev => [...prev, savedTodo])
+      } catch (error) {
+        // 실패 시 자동 롤백됨
+        console.error('Failed to create todo:', error)
+      }
+    })
+  }
+
+  return (
+    <div>
+      {optimisticTodos.map(todo => (
+        <TodoItem
+          key={todo.id}
+          todo={todo}
+          style={{ opacity: todo.pending ? 0.5 : 1 }}
+        />
+      ))}
+      <button onClick={() => addTodo('New Task')}>Add</button>
+    </div>
+  )
+}
+```
+
+**좋아요/투표 UI 예시:**
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useOptimistic, startTransition } from 'react'
+
+function LikeButton({ postId, liked, count }: {
+  postId: string
+  liked: boolean
+  count: number
+}) {
+  const [optimistic, setOptimistic] = useOptimistic(
+    { liked, count },
+    (curr) => ({
+      liked: !curr.liked,
+      count: curr.liked ? curr.count - 1 : curr.count + 1
+    })
+  )
+
+  const toggleLike = () => {
+    startTransition(async () => {
+      setOptimistic(null) // ✅ 즉시 UI 토글
+
+      try {
+        await invoke('toggle_like', { postId })
+      } catch (error) {
+        // 실패 시 자동 롤백
+        console.error('Failed to toggle like:', error)
+      }
+    })
+  }
+
+  return (
+    <button onClick={toggleLike}>
+      {optimistic.liked ? '❤️' : '🤍'} {optimistic.count}
+    </button>
+  )
+}
+```
+
+**삭제 액션 예시:**
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useOptimistic, startTransition, useState } from 'react'
+
+function FileList({ initialFiles }: { initialFiles: File[] }) {
+  const [files, setFiles] = useState(initialFiles)
+  const [optimisticFiles, removeOptimistic] = useOptimistic(
+    files,
+    (current, fileIdToRemove: string) =>
+      current.filter(f => f.id !== fileIdToRemove)
+  )
+
+  const deleteFile = (fileId: string) => {
+    startTransition(async () => {
+      removeOptimistic(fileId) // ✅ 즉시 제거
+
+      try {
+        await invoke('delete_file', { fileId })
+        setFiles(prev => prev.filter(f => f.id !== fileId))
+      } catch (error) {
+        // 실패 시 자동 롤백
+        alert('Failed to delete file')
+      }
+    })
+  }
+
+  return (
+    <div>
+      {optimisticFiles.map(file => (
+        <div key={file.id}>
+          {file.name}
+          <button onClick={() => deleteFile(file.id)}>Delete</button>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+## 추가 컨텍스트
+
+**사용 시점:**
+- 좋아요/투표 버튼
+- 댓글 추가/삭제
+- 장바구니 아이템 추가/제거
+- 토글 스위치 (완료/미완료)
+- 파일 업로드/삭제
+
+**주의사항:**
+- `startTransition` 내에서 사용해야 자동 롤백 작동
+- 복잡한 데이터 구조는 `immer` 같은 라이브러리 활용
+- 에러 발생 시 사용자에게 피드백 제공 (toast, alert)
+
+**React 19 미만 환경:**
+```tsx
+// React 18 이하에서는 수동 롤백 구현
+const [tempState, setTempState] = useState(null)
+
+const addTodo = async (title: string) => {
+  const tempTodo = { id: 'temp', title }
+  setTempState(tempTodo)
+
+  try {
+    const saved = await invoke('create_todo', { title })
+    setTodos(prev => [...prev, saved])
+  } catch {
+    // 수동 롤백
+    setTempState(null)
+  }
+}
+```
+
+**참고:** [React 19 useOptimistic](https://react.dev/reference/react/useOptimistic)
+
+영향도: MEDIUM-HIGH - 사용자 체감 응답 속도, UX 품질

package/templates/.claude/skills/tauri-react-best-practices/rules/security-capability-split.md

@@ -0,0 +1,205 @@
+# 윈도우별 Capability 분리
+
+## 왜 중요한가
+
+Tauri 애플리케이션은 여러 윈도우를 가질 수 있으며, 각 윈도우는 서로 다른 목적과 신뢰 수준을 가집니다. 모든 윈도우에 동일한 권한을 부여하면, 덜 신뢰할 수 있는 콘텐츠를 표시하는 윈도우(예: 외부 웹뷰, 플러그인 UI)가 과도한 권한을 갖게 됩니다. 윈도우별로 Capability를 분리하면 권한 상승 공격(Privilege Escalation)을 방지할 수 있습니다.
+
+## ❌ 잘못된 패턴
+
+```json
+// src-tauri/capabilities/default.json
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "default",
+  "description": "모든 윈도우에 동일한 권한",
+  "windows": ["main", "worker", "external-viewer"],
+  "permissions": [
+    "core:default",
+    "fs:allow-read-text-file",
+    "fs:allow-write-text-file",
+    "shell:allow-execute",
+    "http:allow-fetch"
+  ]
+}
+```
+
+```rust
+// src-tauri/src/main.rs
+fn main() {
+    tauri::Builder::default()
+        .setup(|app| {
+            // 외부 콘텐츠를 표시하는 윈도우도 동일한 권한
+            tauri::window::WindowBuilder::new(
+                app,
+                "external-viewer",
+                tauri::WindowUrl::External("https://untrusted.com".parse().unwrap())
+            ).build()?;
+            Ok(())
+        })
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+**문제점:**
+- 외부 웹사이트를 표시하는 윈도우가 파일 시스템, 셸 실행 권한을 갖음
+- XSS 공격 시 `shell:allow-execute`로 임의 명령 실행 가능
+- 신뢰할 수 없는 콘텐츠가 로컬 파일 읽기/쓰기 가능
+- 모든 윈도우가 동일한 공격 표면을 가짐
+
+## ✅ 올바른 패턴
+
+```json
+// src-tauri/capabilities/main-window.json
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "main-window",
+  "description": "메인 윈도우 전체 권한",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "core:window:allow-close",
+    "core:window:allow-minimize",
+    {
+      "identifier": "fs:allow-read-text-file",
+      "allow": [{ "path": "$APPDATA/my-app/*" }]
+    },
+    {
+      "identifier": "fs:allow-write-text-file",
+      "allow": [{ "path": "$APPDATA/my-app/*" }]
+    },
+    "shell:allow-open",
+    "http:allow-fetch"
+  ]
+}
+```
+
+```json
+// src-tauri/capabilities/worker-window.json
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "worker-window",
+  "description": "백그라운드 작업 윈도우 (읽기 전용)",
+  "windows": ["worker"],
+  "permissions": [
+    "core:default",
+    {
+      "identifier": "fs:allow-read-text-file",
+      "allow": [{ "path": "$APPDATA/my-app/queue/*" }]
+    },
+    "http:allow-fetch"
+  ]
+}
+```
+
+```json
+// src-tauri/capabilities/external-viewer.json
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "external-viewer",
+  "description": "외부 콘텐츠 뷰어 (최소 권한)",
+  "windows": ["external-viewer"],
+  "permissions": [
+    "core:default",
+    "core:window:allow-close"
+  ]
+}
+```
+
+```rust
+// src-tauri/src/main.rs
+fn main() {
+    tauri::Builder::default()
+        .setup(|app| {
+            // 각 윈도우는 자신의 capability를 가짐
+            tauri::window::WindowBuilder::new(
+                app,
+                "external-viewer",
+                tauri::WindowUrl::External("https://untrusted.com".parse().unwrap())
+            ).build()?;
+            Ok(())
+        })
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+**장점:**
+- 각 윈도우는 필요한 최소 권한만 가짐
+- 외부 콘텐츠 윈도우는 시스템 접근 불가
+- 백그라운드 워커는 쓰기 권한 없음 (데이터 손상 방지)
+- 공격 성공 시 피해 범위 제한
+
+## 추가 컨텍스트
+
+**Capability 병합 규칙:**
+
+Tauri는 여러 capability 파일을 자동으로 병합합니다. 윈도우는 자신의 이름이 `windows` 배열에 포함된 모든 capability의 권한을 받습니다.
+
+```json
+// capabilities/base.json
+{
+  "identifier": "base",
+  "windows": ["main", "worker"],
+  "permissions": ["core:default"]
+}
+
+// capabilities/main-only.json
+{
+  "identifier": "main-only",
+  "windows": ["main"],
+  "permissions": ["fs:allow-write-text-file"]
+}
+```
+
+결과:
+- `main` 윈도우: `core:default` + `fs:allow-write-text-file`
+- `worker` 윈도우: `core:default`만
+
+**일반적인 윈도우 타입별 권한 예시:**
+
+| 윈도우 타입 | 설명 | 필요한 권한 |
+|-----------|------|-----------|
+| `main` | 메인 애플리케이션 UI | 전체 파일 시스템, HTTP, 일부 셸 |
+| `settings` | 설정 창 | 설정 파일 읽기/쓰기만 |
+| `worker` | 백그라운드 작업 | HTTP, 임시 파일 읽기/쓰기 |
+| `preview` | 파일 미리보기 | 읽기 전용 파일 시스템 |
+| `external` | 외부 웹 콘텐츠 | 윈도우 제어만 (close/minimize) |
+| `admin` | 관리자 기능 | 전체 권한 (추가 인증 필요) |
+
+**보안 설계 패턴:**
+
+1. **신뢰 경계 식별**
+   ```
+   신뢰도: main > settings > worker > preview > external
+   권한:   많음 ←------------------------→ 적음
+   ```
+
+2. **기본 권한 + 확장 패턴**
+   ```json
+   // base.json: 모든 윈도우에 기본 권한
+   { "windows": ["*"], "permissions": ["core:default"] }
+
+   // main.json: 메인 윈도우만 확장
+   { "windows": ["main"], "permissions": ["fs:allow-*"] }
+   ```
+
+3. **명시적 윈도우 나열**
+   ```json
+   // ❌ 와일드카드 사용
+   { "windows": ["*"], "permissions": ["fs:allow-write-text-file"] }
+
+   // ✅ 필요한 윈도우만 명시
+   { "windows": ["main", "settings"], "permissions": ["fs:allow-write-text-file"] }
+   ```
+
+**체크리스트:**
+- [ ] 각 윈도우의 신뢰 수준을 평가함
+- [ ] 외부 콘텐츠를 표시하는 윈도우는 최소 권한만
+- [ ] 백그라운드 워커는 쓰기 권한 최소화
+- [ ] 관리자 기능은 별도 윈도우로 분리
+- [ ] Capability 파일 이름이 윈도우 이름과 일치 (가독성)
+
+**참조:**
+- [Tauri Multi-Window Security](https://tauri.app/v2/security/#multi-window-applications)
+- [Capability Configuration](https://tauri.app/v2/core/capability/)

package/templates/.claude/skills/tauri-react-best-practices/rules/security-csp.md

@@ -0,0 +1,207 @@
+# Content Security Policy 설정
+
+## 왜 중요한가
+
+Content Security Policy(CSP)는 웹 애플리케이션에서 실행 가능한 스크립트의 출처를 제한하여 XSS(Cross-Site Scripting) 공격을 방지합니다. Tauri 애플리케이션은 로컬 파일로 실행되지만, 외부 API 호출이나 사용자 입력을 처리할 때 여전히 XSS 위험이 있습니다. 강력한 CSP는 악의적인 스크립트가 실행되는 것을 원천 차단합니다.
+
+## ❌ 잘못된 패턴
+
+```html
+<!-- index.html: CSP 미설정 -->
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <title>My App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+```html
+<!-- index.html: 너무 관대한 CSP -->
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="Content-Security-Policy"
+          content="default-src *; script-src * 'unsafe-inline' 'unsafe-eval'; style-src * 'unsafe-inline';" />
+    <title>My App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+**문제점:**
+- CSP 미설정: 모든 출처의 스크립트 실행 가능
+- `unsafe-eval`: `eval()`, `Function()` 사용 가능 (동적 코드 실행)
+- `unsafe-inline`: 인라인 스크립트/스타일 허용 (XSS 주입 가능)
+- `default-src *`: 모든 리소스 출처 허용
+- 공격자가 임의의 스크립트를 주입하여 Tauri API 호출 가능
+
+## ✅ 올바른 패턴
+
+```html
+<!-- index.html: 기본 Tauri CSP -->
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="Content-Security-Policy"
+          content="default-src 'self' tauri:; script-src 'self' tauri:; style-src 'self' tauri: 'unsafe-inline'; img-src 'self' tauri: data: https:;" />
+    <title>My App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+**장점:**
+- `default-src 'self' tauri:`: 로컬 리소스와 Tauri 프로토콜만 허용
+- `script-src 'self' tauri:`: 외부 스크립트 차단
+- `img-src ... https:`: 이미지는 HTTPS 외부 출처 허용
+- `style-src ... 'unsafe-inline'`: CSS-in-JS 라이브러리 호환 (필요 시)
+- 인라인 스크립트 차단으로 XSS 방어
+
+**추가 예시 (외부 API 사용):**
+
+```html
+<!-- index.html: 외부 API와 nonce 사용 -->
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="Content-Security-Policy"
+          content="default-src 'self' tauri:;
+                   script-src 'self' tauri: 'nonce-random123';
+                   connect-src 'self' https://api.example.com;
+                   style-src 'self' tauri: 'unsafe-inline';
+                   img-src 'self' tauri: data: https:;" />
+    <title>My App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" nonce="random123" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+**추가 예시 (프로덕션 환경):**
+
+```json
+// tauri.conf.json
+{
+  "app": {
+    "security": {
+      "csp": "default-src 'self' tauri:; script-src 'self' tauri:; style-src 'self' tauri: 'unsafe-inline'; img-src 'self' tauri: data: https:; connect-src 'self' https://api.example.com"
+    }
+  }
+}
+```
+
+## 추가 컨텍스트
+
+**CSP 지시자 설명:**
+
+| 지시자 | 설명 | Tauri 권장값 |
+|-------|------|-------------|
+| `default-src` | 모든 리소스의 기본 정책 | `'self' tauri:` |
+| `script-src` | JavaScript 출처 | `'self' tauri:` (nonce 추가 가능) |
+| `style-src` | CSS 출처 | `'self' tauri: 'unsafe-inline'` |
+| `img-src` | 이미지 출처 | `'self' tauri: data: https:` |
+| `font-src` | 폰트 출처 | `'self' tauri: data:` |
+| `connect-src` | AJAX, WebSocket 출처 | `'self' https://api.example.com` |
+| `media-src` | 오디오/비디오 출처 | `'self' tauri:` |
+
+**특수 키워드:**
+
+| 키워드 | 의미 | 사용 권장 |
+|-------|------|----------|
+| `'self'` | 현재 도메인 (tauri://localhost) | ✅ 필수 |
+| `tauri:` | Tauri 프로토콜 (`asset:`, `ipc:`) | ✅ 필수 |
+| `'unsafe-inline'` | 인라인 스크립트/스타일 허용 | ❌ script-src에는 금지 |
+| `'unsafe-eval'` | eval() 허용 | ❌ 절대 금지 |
+| `'nonce-xxx'` | 특정 nonce를 가진 스크립트만 | ✅ 동적 스크립트 시 권장 |
+| `data:` | data: URI 허용 | ⚠️ img-src, font-src만 |
+| `https:` | 모든 HTTPS 출처 | ⚠️ img-src만 허용 |
+
+**React 앱 호환성:**
+
+```html
+<!-- Vite + React + Tauri -->
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <!-- Vite는 빌드 시 모듈 스크립트로 변환 -->
+    <meta http-equiv="Content-Security-Policy"
+          content="default-src 'self' tauri:;
+                   script-src 'self' tauri:;
+                   style-src 'self' tauri: 'unsafe-inline';
+                   img-src 'self' tauri: data: https:;
+                   connect-src 'self' https://api.example.com;" />
+    <title>My App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <!-- 모듈 스크립트는 기본적으로 안전 -->
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+**CSP 위반 디버깅:**
+
+```typescript
+// src/main.tsx
+// CSP 위반 시 콘솔에 에러 출력
+window.addEventListener('securitypolicyviolation', (e) => {
+  console.error('CSP Violation:', {
+    blockedURI: e.blockedURI,
+    violatedDirective: e.violatedDirective,
+    originalPolicy: e.originalPolicy,
+  });
+});
+```
+
+**점진적 강화 전략:**
+
+1. **개발 단계**: 관대한 CSP로 시작
+   ```
+   default-src 'self' tauri:;
+   script-src 'self' tauri: 'unsafe-inline';
+   style-src 'self' tauri: 'unsafe-inline';
+   ```
+
+2. **테스트 단계**: `unsafe-inline` 제거, nonce 추가
+   ```
+   script-src 'self' tauri: 'nonce-${random}';
+   ```
+
+3. **프로덕션**: 최소 권한 CSP
+   ```
+   default-src 'self' tauri:;
+   script-src 'self' tauri:;
+   connect-src 'self' https://api.example.com;
+   ```
+
+**체크리스트:**
+- [ ] CSP 헤더가 설정되어 있음
+- [ ] `unsafe-eval` 사용 안 함
+- [ ] `script-src`에 `unsafe-inline` 사용 안 함 (또는 nonce 사용)
+- [ ] `connect-src`로 API 엔드포인트 명시
+- [ ] 개발자 도구에서 CSP 위반 확인
+- [ ] 프로덕션 빌드에서 CSP 테스트
+
+**참조:**
+- [Tauri Security CSP Guide](https://tauri.app/v2/security/#content-security-policy)
+- [MDN CSP Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
+- [CSP Evaluator](https://csp-evaluator.withgoogle.com/)