@kood/claude-code 0.6.6 → 0.7.0

package/templates/.claude/skills/tauri-react-best-practices/rules/state-react-sync.md

@@ -0,0 +1,375 @@
+---
+title: Rust-React State Synchronization
+impact: HIGH
+impactDescription: ensures consistent state across boundaries
+tags: state, react, events, synchronization, ipc
+---
+
+# Rust 상태와 React 상태 동기화 패턴
+
+## 왜 중요한가
+
+Tauri 앱에서 **Rust 백엔드 상태**와 **React 프론트엔드 상태**가 독립적으로 관리되면 **불일치**가 발생합니다. Tauri Events를 사용하여 양방향 동기화를 구현해야 합니다.
+
+## ❌ 잘못된 패턴
+
+**Rust와 React 상태가 각각 독립적으로 관리:**
+
+```rust
+// ❌ src-tauri/src/main.rs - Rust 상태만 업데이트
+use std::sync::Mutex;
+use tauri::State;
+
+struct AppStateInner {
+    count: i32
+}
+
+type AppState = Mutex<AppStateInner>;
+
+#[tauri::command]
+fn increment(state: State<'_, AppState>) -> i32 {
+    let mut state = state.lock().unwrap();
+    state.count += 1;
+    state.count // React에 반환만 하고 끝
+}
+```
+
+```typescript
+// ❌ src/App.tsx - React 상태가 동기화되지 않음
+import { useState } from 'react'
+import { invoke } from '@tauri-apps/api/core'
+
+function App() {
+  const [count, setCount] = useState(0)
+
+  const handleIncrement = async () => {
+    const newCount = await invoke<number>('increment')
+    setCount(newCount) // ✅ 이 창에서는 동기화됨
+  }
+
+  // ❌ 다른 창이나 백그라운드 업데이트는 감지 못함
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={handleIncrement}>Increment</button>
+    </div>
+  )
+}
+```
+
+**문제:**
+- 다른 창에서 `increment` 호출 시 현재 창의 `count`가 업데이트되지 않음
+- Rust 상태 변경이 React에 전파되지 않음
+- 백그라운드 작업이 상태를 변경해도 UI가 업데이트 안됨
+
+## ✅ 올바른 패턴
+
+**Tauri Events로 Rust → React 동기화:**
+
+```rust
+// ✅ src-tauri/src/state.rs
+use std::sync::Mutex;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AppStateInner {
+    pub count: i32,
+    pub username: String
+}
+
+pub type AppState = Mutex<AppStateInner>;
+
+impl AppStateInner {
+    pub fn new() -> Self {
+        Self {
+            count: 0,
+            username: String::from("Guest")
+        }
+    }
+}
+```
+
+```rust
+// ✅ src-tauri/src/main.rs - 상태 변경 시 이벤트 발행
+mod state;
+
+use state::{AppState, AppStateInner};
+use tauri::{State, Manager, Emitter};
+
+#[tauri::command]
+fn increment(state: State<'_, AppState>, app: tauri::AppHandle) -> Result<i32, String> {
+    let new_count = {
+        let mut state = state.lock().unwrap();
+        state.count += 1;
+        state.count
+    };
+
+    // ✅ 모든 창에 상태 변경 알림
+    app.emit("state-changed", &new_count)
+        .map_err(|e| format!("Failed to emit event: {}", e))?;
+
+    Ok(new_count)
+}
+
+#[tauri::command]
+fn set_username(
+    state: State<'_, AppState>,
+    app: tauri::AppHandle,
+    username: String
+) -> Result<(), String> {
+    {
+        let mut state = state.lock().unwrap();
+        state.username = username.clone();
+    }
+
+    // ✅ username 변경 이벤트 발행
+    app.emit("username-changed", &username)
+        .map_err(|e| format!("Failed to emit event: {}", e))?;
+
+    Ok(())
+}
+
+#[tauri::command]
+fn get_state(state: State<'_, AppState>) -> Result<AppStateInner, String> {
+    let state = state.lock()
+        .map_err(|e| format!("Failed to lock state: {}", e))?;
+    Ok(state.clone())
+}
+
+fn main() {
+    tauri::Builder::default()
+        .manage(AppState::new(AppStateInner::new()))
+        .invoke_handler(tauri::generate_handler![
+            increment,
+            set_username,
+            get_state
+        ])
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+```typescript
+// ✅ src/App.tsx - 이벤트 리스너로 동기화
+import { useState, useEffect } from 'react'
+import { invoke } from '@tauri-apps/api/core'
+import { listen } from '@tauri-apps/api/event'
+
+interface AppState {
+  count: number
+  username: string
+}
+
+function App() {
+  const [state, setState] = useState<AppState>({
+    count: 0,
+    username: 'Guest'
+  })
+
+  useEffect(() => {
+    // ✅ 초기 상태 로드
+    invoke<AppState>('get_state').then(setState)
+
+    // ✅ Rust 상태 변경 감지
+    const unlistenCount = listen<number>('state-changed', (event) => {
+      setState(prev => ({ ...prev, count: event.payload }))
+    })
+
+    const unlistenUsername = listen<string>('username-changed', (event) => {
+      setState(prev => ({ ...prev, username: event.payload }))
+    })
+
+    // 클린업
+    return () => {
+      unlistenCount.then(fn => fn())
+      unlistenUsername.then(fn => fn())
+    }
+  }, [])
+
+  const handleIncrement = async () => {
+    await invoke('increment') // 이벤트로 상태 업데이트됨
+  }
+
+  const handleSetUsername = async (name: string) => {
+    await invoke('set_username', { username: name })
+  }
+
+  return (
+    <div>
+      <p>Count: {state.count}</p>
+      <p>Username: {state.username}</p>
+      <button onClick={handleIncrement}>Increment</button>
+      <button onClick={() => handleSetUsername('Alice')}>
+        Set Username
+      </button>
+    </div>
+  )
+}
+
+export default App
+```
+
+**React → Rust 동기화 (양방향):**
+
+```typescript
+// ✅ src/App.tsx - React 상태 변경 시 Rust에 동기화
+function App() {
+  const [localCount, setLocalCount] = useState(0)
+
+  const handleLocalIncrement = async () => {
+    // 낙관적 업데이트
+    const newCount = localCount + 1
+    setLocalCount(newCount)
+
+    // Rust 상태 동기화
+    try {
+      await invoke('increment')
+    } catch (error) {
+      // 실패 시 롤백
+      setLocalCount(localCount)
+      console.error('Failed to sync state:', error)
+    }
+  }
+
+  return (
+    <div>
+      <p>Local Count: {localCount}</p>
+      <button onClick={handleLocalIncrement}>Increment</button>
+    </div>
+  )
+}
+```
+
+**커스텀 훅으로 추상화:**
+
+```typescript
+// ✅ src/hooks/useTauriState.ts
+import { useState, useEffect } from 'react'
+import { invoke } from '@tauri-apps/api/core'
+import { listen } from '@tauri-apps/api/event'
+
+export function useTauriState<T>(
+  getCommand: string,
+  eventName: string
+): [T | null, (newValue: T) => Promise<void>] {
+  const [state, setState] = useState<T | null>(null)
+
+  useEffect(() => {
+    // 초기 상태 로드
+    invoke<T>(getCommand).then(setState)
+
+    // 이벤트 리스너
+    const unlisten = listen<T>(eventName, (event) => {
+      setState(event.payload)
+    })
+
+    return () => {
+      unlisten.then(fn => fn())
+    }
+  }, [getCommand, eventName])
+
+  const updateState = async (newValue: T) => {
+    setState(newValue)
+    await invoke('update_state', { newValue })
+  }
+
+  return [state, updateState]
+}
+
+// 사용 예시
+function App() {
+  const [count, setCount] = useTauriState<number>('get_count', 'count-changed')
+
+  return (
+    <div>
+      <p>Count: {count ?? 'Loading...'}</p>
+      <button onClick={() => setCount((count ?? 0) + 1)}>
+        Increment
+      </button>
+    </div>
+  )
+}
+```
+
+## 추가 컨텍스트
+
+**양방향 동기화 아키텍처:**
+
+```
+┌─────────────┐         invoke()        ┌─────────────┐
+│   React     │ ───────────────────────> │    Rust     │
+│   State     │                          │    State    │
+│             │ <─────────────────────── │             │
+└─────────────┘      emit() event        └─────────────┘
+```
+
+**동기화 패턴 비교:**
+
+| 패턴 | 장점 | 단점 | 권장 |
+|------|------|------|------|
+| **Poll (주기적 조회)** | 간단 | 비효율적, 지연 | ❌ |
+| **Event-driven** | 실시간, 효율적 | 복잡도 증가 | ✅ |
+| **낙관적 업데이트** | 빠른 UX | 실패 시 롤백 필요 | ⚠️ 선택 |
+
+**여러 창 동기화:**
+
+```rust
+// 모든 창에 브로드캐스트
+app.emit_all("state-changed", &new_count)?;
+
+// 특정 창에만 전송
+if let Some(window) = app.get_window("main") {
+    window.emit("state-changed", &new_count)?;
+}
+```
+
+**에러 처리:**
+
+```typescript
+useEffect(() => {
+  const unlisten = listen<number>('state-changed', (event) => {
+    setState(event.payload)
+  }).catch((error) => {
+    console.error('Failed to listen to events:', error)
+  })
+
+  return () => {
+    unlisten.then(fn => fn()).catch(console.error)
+  }
+}, [])
+```
+
+**성능 최적화:**
+
+```rust
+// 디바운싱으로 과도한 이벤트 방지
+use std::time::{Duration, Instant};
+
+struct StateEmitter {
+    last_emit: Mutex<Instant>
+}
+
+impl StateEmitter {
+    fn emit_throttled(&self, app: &tauri::AppHandle, count: i32) -> Result<(), String> {
+        let mut last = self.last_emit.lock().unwrap();
+        let now = Instant::now();
+
+        if now.duration_since(*last) > Duration::from_millis(100) {
+            app.emit("state-changed", &count)
+                .map_err(|e| e.to_string())?;
+            *last = now;
+        }
+
+        Ok(())
+    }
+}
+```
+
+**참고:**
+- Tauri Events: [Inter-Process Communication](https://tauri.app/v2/guides/features/events/)
+- React useEffect: [Synchronizing with Effects](https://react.dev/learn/synchronizing-with-effects)
+
+**영향도:**
+- 일관성: HIGH (상태 불일치 방지)
+- 실시간성: HIGH (즉시 동기화)
+- 복잡도: MEDIUM (이벤트 관리 필요)

package/templates/.claude/skills/tauri-react-best-practices/rules/state-single-container.md

@@ -0,0 +1,275 @@
+---
+title: Single Container for Multiple States
+impact: MEDIUM
+impactDescription: prevents state registration conflicts
+tags: state, container, tauri, type-map, rust
+---
+
+# 동일 타입 중복 등록 방지
+
+## 왜 중요한가
+
+Tauri의 상태 관리는 **타입 기반 의존성 주입** 시스템을 사용합니다. 동일한 타입을 여러 번 `manage()`로 등록하면 **두 번째 등록이 무시**되어 의도하지 않은 상태를 사용하게 됩니다.
+
+## ❌ 잘못된 패턴
+
+**동일 타입을 여러 번 manage() 호출:**
+
+```rust
+// ❌ src-tauri/src/main.rs
+use std::sync::Mutex;
+use tauri::State;
+
+type DatabaseState = Mutex<String>;
+type CacheState = Mutex<String>;
+
+#[tauri::command]
+fn get_db_connection(db: State<'_, DatabaseState>) -> String {
+    let db = db.lock().unwrap();
+    db.clone()
+}
+
+#[tauri::command]
+fn get_cache_connection(cache: State<'_, CacheState>) -> String {
+    let cache = cache.lock().unwrap();
+    cache.clone()
+}
+
+fn main() {
+    tauri::Builder::default()
+        .manage(DatabaseState::new(String::from("postgres://localhost")))
+        .manage(CacheState::new(String::from("redis://localhost")))
+        // ❌ 두 번째 manage()가 무시됨! (둘 다 Mutex<String> 타입)
+        .invoke_handler(tauri::generate_handler![
+            get_db_connection,
+            get_cache_connection
+        ])
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+**프론트엔드에서 호출:**
+
+```typescript
+// 둘 다 "postgres://localhost" 반환!
+const db = await invoke('get_db_connection') // "postgres://localhost"
+const cache = await invoke('get_cache_connection') // "postgres://localhost" (예상: "redis://localhost")
+```
+
+**문제:**
+- `CacheState`가 등록되지 않음
+- `get_cache_connection`이 `DatabaseState`를 반환
+- 런타임 에러는 발생하지 않지만 잘못된 상태 사용
+
+## ✅ 올바른 패턴
+
+**컨테이너 구조체로 여러 상태 통합:**
+
+```rust
+// ✅ src-tauri/src/state.rs
+use std::sync::Mutex;
+
+pub struct AppStateInner {
+    pub database_url: String,
+    pub cache_url: String,
+    pub api_key: String
+}
+
+pub type AppState = Mutex<AppStateInner>;
+
+impl AppStateInner {
+    pub fn new() -> Self {
+        Self {
+            database_url: String::from("postgres://localhost"),
+            cache_url: String::from("redis://localhost"),
+            api_key: String::from("secret")
+        }
+    }
+}
+```
+
+```rust
+// ✅ src-tauri/src/main.rs
+mod state;
+
+use state::{AppState, AppStateInner};
+use tauri::State;
+
+#[tauri::command]
+fn get_db_connection(state: State<'_, AppState>) -> String {
+    let state = state.lock().unwrap();
+    state.database_url.clone()
+}
+
+#[tauri::command]
+fn get_cache_connection(state: State<'_, AppState>) -> String {
+    let state = state.lock().unwrap();
+    state.cache_url.clone()
+}
+
+#[tauri::command]
+fn get_api_key(state: State<'_, AppState>) -> String {
+    let state = state.lock().unwrap();
+    state.api_key.clone()
+}
+
+fn main() {
+    tauri::Builder::default()
+        .manage(AppState::new(AppStateInner::new())) // 단일 컨테이너 등록
+        .invoke_handler(tauri::generate_handler![
+            get_db_connection,
+            get_cache_connection,
+            get_api_key
+        ])
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+**newtype 패턴 (타입 래핑):**
+
+```rust
+// ✅ src-tauri/src/state.rs - newtype 패턴
+use std::sync::Mutex;
+
+// 각각 고유한 타입으로 래핑
+pub struct DatabaseState(pub Mutex<String>);
+pub struct CacheState(pub Mutex<String>);
+
+impl DatabaseState {
+    pub fn new(url: String) -> Self {
+        Self(Mutex::new(url))
+    }
+}
+
+impl CacheState {
+    pub fn new(url: String) -> Self {
+        Self(Mutex::new(url))
+    }
+}
+```
+
+```rust
+// ✅ src-tauri/src/main.rs
+mod state;
+
+use state::{DatabaseState, CacheState};
+use tauri::State;
+
+#[tauri::command]
+fn get_db_connection(db: State<'_, DatabaseState>) -> String {
+    let db = db.0.lock().unwrap();
+    db.clone()
+}
+
+#[tauri::command]
+fn get_cache_connection(cache: State<'_, CacheState>) -> String {
+    let cache = cache.0.lock().unwrap();
+    cache.clone()
+}
+
+fn main() {
+    tauri::Builder::default()
+        .manage(DatabaseState::new(String::from("postgres://localhost")))
+        .manage(CacheState::new(String::from("redis://localhost")))
+        // ✅ 이제 각각 고유한 타입이므로 둘 다 등록됨
+        .invoke_handler(tauri::generate_handler![
+            get_db_connection,
+            get_cache_connection
+        ])
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+## 추가 컨텍스트
+
+**Tauri의 타입 기반 상태 시스템:**
+
+```rust
+// Tauri 내부적으로 TypeMap 사용
+// TypeMap<TypeId, Box<dyn Any>>
+// 각 타입당 하나의 값만 저장 가능
+
+.manage(value1) // TypeId::of::<T>() → value1
+.manage(value2) // TypeId::of::<T>() → value2 (value1 덮어쓰기 또는 무시)
+```
+
+**패턴 비교:**
+
+| 패턴 | 장점 | 단점 | 권장 |
+|------|------|------|------|
+| **단일 컨테이너** | 단순, 명확 | 큰 구조체 | ✅ 대부분의 경우 |
+| **Newtype** | 타입 안전 | 보일러플레이트 | ⚠️ 필요 시만 |
+| **여러 manage()** | - | ❌ 작동 안함 | ❌ 사용 금지 |
+
+**컨테이너 구조체 설계:**
+
+```rust
+// ✅ 도메인별 그룹화
+pub struct AppStateInner {
+    // 데이터베이스 관련
+    pub db_pool: DatabasePool,
+    pub db_url: String,
+
+    // 캐시 관련
+    pub cache_pool: CachePool,
+    pub cache_url: String,
+
+    // 인증 관련
+    pub jwt_secret: String,
+    pub api_key: String,
+
+    // 설정 관련
+    pub config: AppConfig
+}
+```
+
+**env 변수 로드:**
+
+```rust
+use std::env;
+
+impl AppStateInner {
+    pub fn from_env() -> Self {
+        Self {
+            database_url: env::var("DATABASE_URL")
+                .unwrap_or_else(|_| String::from("postgres://localhost")),
+            cache_url: env::var("REDIS_URL")
+                .unwrap_or_else(|_| String::from("redis://localhost")),
+            api_key: env::var("API_KEY")
+                .expect("API_KEY must be set"),
+        }
+    }
+}
+
+fn main() {
+    tauri::Builder::default()
+        .manage(AppState::new(AppStateInner::from_env()))
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+**디버깅 팁:**
+
+```rust
+// State를 찾을 수 없을 때 런타임 에러
+#[tauri::command]
+fn test_command(state: State<'_, WrongType>) {
+    // panic: no state of type `WrongType` is managed
+}
+
+// 등록된 상태 확인
+println!("Registered state: {:?}", std::any::type_name::<AppState>());
+```
+
+**참고:**
+- Tauri State Management: [Managing State](https://tauri.app/v2/guides/features/state-management/)
+- Rust TypeId: [std::any::TypeId](https://doc.rust-lang.org/std/any/struct.TypeId.html)
+
+**영향도:**
+- 타입 안전성: MEDIUM (타입 충돌 방지)
+- 버그 가능성: HIGH (잘못된 상태 사용 방지)
+- 유지보수: HIGH (명확한 구조)