@kood/claude-code 0.7.2 → 0.7.5

package/templates/tauri/docs/library/tauri/references/security-guide.md

@@ -0,0 +1,64 @@
+# Security Guide
+
+> Tauri v2 보안 상세 가이드
+
+---
+
+## Capabilities
+
+```json
+// src-tauri/capabilities/default.json
+{
+  "identifier": "default",
+  "description": "메인 윈도우 기본 권한",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "core:window:allow-set-title",
+    "core:window:allow-close",
+    "shell:allow-open"
+  ]
+}
+```
+
+```json
+// 플랫폼별 Capability
+{
+  "identifier": "mobile-features",
+  "description": "모바일 전용 권한",
+  "windows": ["main"],
+  "platforms": ["iOS", "android"],
+  "permissions": [
+    "nfc:default",
+    "biometric:default"
+  ]
+}
+```
+
+---
+
+## Permission 패턴
+
+```
+core:default                    # Core 기본 권한
+core:window:allow-<command>     # Window 개별 허용
+core:event:allow-listen         # Event 리스닝 허용
+<plugin>:default                # Plugin 기본 권한
+<plugin>:allow-<command>        # Plugin 개별 허용
+<plugin>:deny-<command>         # Plugin 개별 거부
+```
+
+---
+
+## CSP 설정
+
+```json
+// tauri.conf.json > app > security > csp
+{
+  "default-src": "'self' customprotocol: asset:",
+  "connect-src": "ipc: http://ipc.localhost",
+  "font-src": ["https://fonts.gstatic.com"],
+  "img-src": "'self' asset: http://asset.localhost blob: data:",
+  "style-src": "'unsafe-inline' 'self'"
+}
+```

package/templates/tauri/docs/library/tauri/references/state-guide.md

@@ -0,0 +1,49 @@
+# State Management Guide
+
+> Tauri Rust 상태 관리 상세 가이드
+
+---
+
+## State 패턴
+
+```rust
+use std::sync::Mutex;
+use tauri::{Builder, Manager, State};
+
+struct AppState {
+    counter: u32,
+    db_url: String,
+}
+
+#[tauri::command]
+async fn increment(state: State<'_, Mutex<AppState>>) -> Result<u32, String> {
+    let mut s = state.lock().map_err(|e| e.to_string())?;
+    s.counter += 1;
+    Ok(s.counter)
+}
+
+fn main() {
+    Builder::default()
+        .setup(|app| {
+            // 불변 상태
+            app.manage(String::from("config-value"));
+            // 가변 상태
+            app.manage(Mutex::new(AppState { counter: 0, db_url: String::new() }));
+            Ok(())
+        })
+        .invoke_handler(tauri::generate_handler![increment])
+        .run(tauri::generate_context!())
+        .unwrap();
+}
+```
+
+---
+
+## 규칙
+
+| 규칙 | 설명 |
+|------|------|
+| **Arc 불필요** | State<T>가 내부 처리 |
+| **가변 상태** | `Mutex<T>` 사용 (std::sync::Mutex 권장) |
+| **await 제한** | await 포인트 넘어 lock 유지 금지 |
+| **타입 별칭** | 잘못된 타입 접근 → 런타임 패닉 |

package/templates/tauri/docs/references/async-execution.md

@@ -0,0 +1,66 @@
+# Async Execution Model
+
+> Tauri Command의 비동기 실행 원리
+
+---
+
+## async vs non-async Command
+
+| 유형 | 실행 위치 | 사용 시점 |
+|------|----------|----------|
+| `async fn` | Tokio async runtime | IO 작업 (DB, HTTP, File) |
+| `fn` (non-async) | 별도 스레드풀 | CPU 작업 (계산, 변환) |
+
+```rust
+// ✅ async Command: Tokio runtime에서 실행
+// - await 사용 가능
+// - IO 작업에 적합 (non-blocking)
+#[tauri::command]
+async fn fetch_data(url: String) -> Result<String, String> {
+    let response = reqwest::get(&url).await.map_err(|e| e.to_string())?;
+    response.text().await.map_err(|e| e.to_string())
+}
+
+// ✅ non-async Command: 스레드풀에서 실행
+// - CPU 집약적 작업에 적합
+// - 메인 스레드 블로킹 방지
+#[tauri::command]
+fn heavy_computation(data: Vec<u8>) -> Vec<u8> {
+    // CPU 집약적 작업
+    data.iter().map(|x| x.wrapping_mul(2)).collect()
+}
+```
+
+---
+
+## Tokio Runtime 동작
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Tauri Application                       │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                   Tokio Runtime                      │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │    │
+│  │  │ async Task 1│  │ async Task 2│  │ async Task 3│ │    │
+│  │  │ (fetch_data)│  │ (read_file) │  │ (db_query)  │ │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘ │    │
+│  └─────────────────────────────────────────────────────┘    │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │              Thread Pool (sync commands)             │    │
+│  │  ┌─────────────┐  ┌─────────────┐                   │    │
+│  │  │ sync Task 1 │  │ sync Task 2 │                   │    │
+│  │  │ (compute)   │  │ (transform) │                   │    │
+│  │  └─────────────┘  └─────────────┘                   │    │
+│  └─────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 주의사항
+
+| 패턴 | 설명 |
+|------|------|
+| **async에서 blocking 금지** | `std::thread::sleep()` 대신 `tokio::time::sleep()` 사용 |
+| **sync에서 await 불가** | non-async 함수에서는 `.await` 사용 불가 |
+| **spawn_blocking** | async 내에서 blocking 작업 필요 시 `tokio::task::spawn_blocking` |

package/templates/tauri/docs/references/data-flow.md

@@ -0,0 +1,46 @@
+# Data Flow
+
+> Tauri 데이터 흐름 패턴
+
+---
+
+## Command Flow (읽기)
+
+```
+┌─────────┐   invoke   ┌─────────┐   validate   ┌─────────┐   execute   ┌─────────┐
+│ React   │───────────▶│  IPC    │─────────────▶│Capability│────────────▶│ Command │
+│ Hook    │            │ Bridge  │              │ Check   │             │ Handler │
+└─────────┘            └─────────┘              └─────────┘             └────┬────┘
+     ▲                                                                       │
+     │                                                                       ▼
+     │                                                                 ┌─────────┐
+     │◀────────────────────────────────────────────────────────────────│  State  │
+     │                           Result<T>                             │ / DB    │
+                                                                       └─────────┘
+```
+
+---
+
+## Event Flow (실시간 업데이트)
+
+```
+┌─────────┐                              ┌─────────┐
+│  Rust   │   app.emit("event", data)   │ Frontend│
+│  Core   │─────────────────────────────▶│ listen()│
+└─────────┘                              └─────────┘
+     │
+     │  Background Task (download, sync, etc.)
+     │
+     └──▶ Progress Event ──▶ UI Update
+```
+
+---
+
+## Plugin Data Flow
+
+```
+Frontend ──▶ invoke("plugin:fs|read") ──▶ Capability Check ──▶ Plugin Handler ──▶ OS API
+                                                                     │
+                                              ◀─────────────────────┘
+                                                   Result/Error
+```

package/templates/tauri/docs/references/error-handling.md

@@ -0,0 +1,113 @@
+# Error Handling
+
+> Rust Error → JSON → TypeScript Error 전파 메커니즘
+
+---
+
+## 커스텀 Error 타입 정의
+
+```rust
+// src-tauri/src/error.rs
+use serde::Serialize;
+
+#[derive(Debug, thiserror::Error)]
+pub enum AppError {
+    #[error("Not found: {0}")]
+    NotFound(String),
+
+    #[error("Unauthorized: {0}")]
+    Unauthorized(String),
+
+    #[error("Database error: {0}")]
+    Database(String),
+
+    #[error("Internal error: {0}")]
+    Internal(String),
+}
+
+// serde::Serialize 구현 필수 (JSON 직렬화)
+impl Serialize for AppError {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        serializer.serialize_str(self.to_string().as_ref())
+    }
+}
+
+// From 변환 구현 (다른 에러 타입 자동 변환)
+impl From<sqlx::Error> for AppError {
+    fn from(e: sqlx::Error) -> Self {
+        AppError::Database(e.to_string())
+    }
+}
+```
+
+---
+
+## Command에서 에러 반환
+
+```rust
+#[tauri::command]
+async fn get_user(id: u32, db: State<'_, DbPool>) -> Result<User, AppError> {
+    let user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id)
+        .fetch_optional(&**db)
+        .await?  // sqlx::Error → AppError 자동 변환
+        .ok_or_else(|| AppError::NotFound(format!("User {} not found", id)))?;
+
+    Ok(user)
+}
+```
+
+---
+
+## Frontend 에러 처리
+
+```typescript
+import { invoke } from '@tauri-apps/api/core';
+
+interface User {
+  id: number;
+  name: string;
+}
+
+async function getUser(id: number): Promise<User | null> {
+  try {
+    return await invoke<User>('get_user', { id });
+  } catch (error) {
+    // error는 Rust에서 직렬화된 문자열
+    const errorMessage = error as string;
+
+    if (errorMessage.includes('Not found')) {
+      console.warn('User not found:', id);
+      return null;
+    }
+
+    if (errorMessage.includes('Unauthorized')) {
+      // 인증 에러 처리
+      window.location.href = '/login';
+      return null;
+    }
+
+    // 기타 에러
+    console.error('Failed to get user:', errorMessage);
+    throw new Error(errorMessage);
+  }
+}
+```
+
+---
+
+## 에러 전파 흐름
+
+```
+┌─────────────┐    Result<T,E>    ┌─────────────┐    JSON     ┌─────────────┐
+│   Rust      │ ─────────────────▶│    IPC      │ ──────────▶ │  Frontend   │
+│  Command    │    Err(AppError)  │   Bridge    │  serialize  │   catch()   │
+└─────────────┘                   └─────────────┘             └─────────────┘
+       │                                                             │
+       │ #[error("...")] 메시지                                      │ error as string
+       │                                                             │
+       ▼                                                             ▼
+"Not found: User 1 not found"                      "Not found: User 1 not found"
+```

package/templates/tauri/docs/references/mobile-architecture.md

@@ -0,0 +1,64 @@
+# Mobile Architecture
+
+> Tauri v2 모바일 아키텍처 상세 가이드
+
+---
+
+## 엔트리포인트 구조
+
+```rust
+// lib.rs - 공유 로직 (데스크톱 + 모바일)
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    tauri::Builder::default()
+        .invoke_handler(tauri::generate_handler![...])
+        .run(tauri::generate_context!())
+        .expect("error");
+}
+
+// main.rs - 데스크톱 전용
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+fn main() {
+    my_app_lib::run()
+}
+```
+
+---
+
+## Mobile Plugin 구조
+
+```
+plugin/
+├── src/
+│   ├── lib.rs          # 공유 로직
+│   ├── desktop.rs      # 데스크톱 구현
+│   └── mobile.rs       # 모바일 브릿지 (Kotlin/Swift 호출)
+├── android/
+│   └── src/.../Plugin.kt   # Kotlin 구현
+└── ios/
+    └── Sources/Plugin.swift  # Swift 구현
+```
+
+---
+
+## 플랫폼 설정
+
+| 파일 | 용도 |
+|------|------|
+| `tauri.conf.json` | 공통 설정 |
+| `tauri.android.conf.json` | Android 오버라이드 |
+| `tauri.ios.conf.json` | iOS 오버라이드 |
+| `tauri.windows.conf.json` | Windows 오버라이드 |
+| `tauri.macos.conf.json` | macOS 오버라이드 |
+| `tauri.linux.conf.json` | Linux 오버라이드 |
+
+---
+
+## 모바일 개발 주의사항
+
+| 항목 | 설명 |
+|------|------|
+| **iOS 개발** | macOS에서만 가능 |
+| **Android 메인 스레드** | 블로킹 I/O → UI 프리징, Coroutine 사용 필수 |
+| **최소 Android SDK** | 24 (Android 7.0) |
+| **lib.rs 엔트리포인트** | 모바일은 라이브러리로 로드 |

package/templates/tauri/docs/references/security-model.md

@@ -0,0 +1,85 @@
+# Security Model
+
+> Tauri v2 보안 모델 상세 가이드
+
+---
+
+## Trust Boundaries
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    UNTRUSTED ZONE                            │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │                    WebView                             │  │
+│  │   • HTML/CSS/JS                                       │  │
+│  │   • 사용자 입력                                        │  │
+│  │   • 외부 콘텐츠 (제한적)                               │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────┬───────────────────────────────────┘
+                          │ IPC (Capabilities 검증)
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     TRUSTED ZONE                             │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │                   Rust Core                            │  │
+│  │   • 시스템 API 접근                                    │  │
+│  │   • 파일 시스템                                        │  │
+│  │   • 네트워크                                           │  │
+│  │   • 민감 데이터                                        │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Capabilities System
+
+```json
+// src-tauri/capabilities/default.json
+{
+  "identifier": "default",
+  "description": "메인 윈도우 기본 권한",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "core:window:allow-set-title",
+    "shell:allow-open"
+  ]
+}
+```
+
+| Permission 패턴 | 설명 |
+|----------------|------|
+| `core:default` | Core 기본 권한 |
+| `core:window:allow-<cmd>` | Window 개별 허용 |
+| `<plugin>:default` | Plugin 기본 권한 |
+| `<plugin>:allow-<cmd>` | Plugin 개별 허용 |
+| `<plugin>:deny-<cmd>` | Plugin 개별 거부 |
+
+---
+
+## CSP (Content Security Policy)
+
+```json
+// tauri.conf.json > app > security > csp
+{
+  "default-src": "'self' customprotocol: asset:",
+  "connect-src": "ipc: http://ipc.localhost",
+  "img-src": "'self' asset: http://asset.localhost blob: data:",
+  "style-src": "'unsafe-inline' 'self'"
+}
+```
+
+### CSP 프로토콜 설명
+
+| 프로토콜 | 설명 |
+|---------|------|
+| `'self'` | 같은 origin 리소스만 허용 |
+| `customprotocol:` | Tauri 커스텀 프로토콜 (앱 내부 통신) |
+| `asset:` | 로컬 파일 접근 프로토콜 (Tauri v2) |
+| `ipc:` | Frontend ↔ Rust IPC 통신 프로토콜 |
+| `http://ipc.localhost` | IPC 브릿지 localhost 접근 |
+| `http://asset.localhost` | 로컬 에셋 서빙 |
+| `'unsafe-inline'` | 인라인 스타일 허용 (CSS-in-JS 라이브러리 호환, style-src만) |
+| `blob:` | Blob URL 허용 (동적 이미지 생성) |
+| `data:` | Data URL 허용 (Base64 이미지) |

package/templates/tauri/docs/references/state-management.md

@@ -0,0 +1,117 @@
+# State Management
+
+> Tauri Rust 상태 관리 상세 가이드
+
+---
+
+## Rust State 패턴
+
+```rust
+use std::sync::Mutex;
+use tauri::{Builder, Manager, State};
+
+// 상태 정의
+struct AppState {
+    counter: u32,
+    db_url: String,
+}
+
+// Command에서 사용
+#[tauri::command]
+async fn increment(state: State<'_, Mutex<AppState>>) -> Result<u32, String> {
+    let mut s = state.lock().map_err(|e| e.to_string())?;
+    s.counter += 1;
+    Ok(s.counter)
+}
+
+// 등록
+fn main() {
+    Builder::default()
+        .setup(|app| {
+            app.manage(Mutex::new(AppState { counter: 0, db_url: String::new() }));
+            Ok(())
+        })
+        .invoke_handler(tauri::generate_handler![increment])
+        .run(tauri::generate_context!())
+        .unwrap();
+}
+```
+
+---
+
+## State 규칙
+
+| 규칙 | 설명 |
+|------|------|
+| **Arc 불필요** | State<T>가 내부적으로 Arc 처리 |
+| **가변 상태** | `Mutex<T>` 사용 |
+| **await 제한** | await 포인트 넘어 lock 유지 금지 (데드락) |
+| **타입 별칭** | 잘못된 타입 접근 → 런타임 패닉 |
+
+---
+
+## Mutex 선택 기준
+
+| Mutex 종류 | 사용 시점 | 예시 |
+|-----------|----------|------|
+| `std::sync::Mutex` | CPU 작업 (빠른 연산) | counter, config, cache |
+| `tokio::sync::Mutex` | IO 작업 (await 필요) | DB, HTTP, File |
+
+---
+
+## await 걸쳐 lock 유지 금지
+
+```rust
+// ❌ 잘못된 예시: await 걸쳐 lock 유지 → 데드락 위험
+#[tauri::command]
+async fn bad_example(state: State<'_, std::sync::Mutex<AppState>>) -> Result<(), String> {
+    let s = state.lock().unwrap();  // lock 획득
+    some_async_operation().await;   // await 포인트 → 다른 스레드 블로킹
+    s.counter += 1;                 // lock 아직 유지 중
+    Ok(())
+}
+
+// ✅ 올바른 예시 1: lock 범위 최소화
+#[tauri::command]
+async fn good_example_1(state: State<'_, std::sync::Mutex<AppState>>) -> Result<(), String> {
+    let data = {
+        let s = state.lock().unwrap();
+        s.get_data()  // lock 범위 내에서 필요한 작업만
+    };  // lock 해제
+    some_async_operation(data).await;  // await는 lock 밖에서
+    Ok(())
+}
+
+// ✅ 올바른 예시 2: IO 작업 시 tokio::sync::Mutex
+#[tauri::command]
+async fn good_example_2(state: State<'_, tokio::sync::Mutex<DbConnection>>) -> Result<(), String> {
+    let mut db = state.lock().await;  // tokio Mutex는 await 가능
+    db.query("SELECT * FROM users").await?;
+    Ok(())
+}
+```
+
+---
+
+## Frontend State (Zustand)
+
+```typescript
+// stores/app.ts
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+export const useAppStore = create(
+  persist(
+    (set) => ({
+      theme: 'dark' as 'light' | 'dark',
+      setTheme: (theme) => set({ theme }),
+    }),
+    { name: 'app-store' }
+  )
+);
+```
+
+| 상태 유형 | 위치 | 사용 |
+|----------|------|------|
+| **시스템 상태** | Rust State | DB 연결, 설정, 캐시 |
+| **UI 상태** | Zustand | 테마, 사이드바, 임시 데이터 |

package/templates/tauri/docs/references/tech-stack.md

@@ -0,0 +1,31 @@
+# Technology Stack
+
+> Tauri v2 기술 스택
+
+---
+
+## Core Technologies
+
+| Layer | Technology | Version |
+|-------|------------|---------|
+| Framework | Tauri | 2.x |
+| Backend | Rust | stable |
+| Frontend | React | 19.x |
+| Bundler | Vite | 6.x |
+| TypeScript | TS | 5.x |
+| State (Client) | Zustand | latest |
+| IPC API | @tauri-apps/api | 2.x |
+| Window | TAO | - |
+| WebView | WRY | - |
+
+---
+
+## WebView Engine
+
+| 플랫폼 | WebView |
+|--------|---------|
+| Windows | WebView2 (Chromium) |
+| macOS | WKWebView (WebKit) |
+| Linux | webkitgtk (WebKit) |
+| iOS | WKWebView (WebKit) |
+| Android | WebView (Chromium) |