@kood/claude-code 0.6.6 → 0.7.0

package/templates/.claude/skills/tauri-react-best-practices/rules/plugin-lifecycle.md

@@ -0,0 +1,265 @@
+# setup/on_event/on_drop 라이프사이클 관리
+
+## 왜 중요한가
+
+Tauri 플러그인의 리소스(DB 연결, 파일 핸들, 소켓 등)를 제대로 초기화하고 정리하지 않으면 메모리 누수, 파일 잠금, 좀비 프로세스가 발생합니다. 플러그인 라이프사이클을 명확히 관리해야 앱 안정성을 보장할 수 있습니다.
+
+## ❌ 잘못된 패턴
+
+```rust
+use tauri::{plugin::{Builder, TauriPlugin}, Runtime};
+
+pub fn init<R: Runtime>() -> TauriPlugin<R> {
+    Builder::new("my-plugin")
+        .invoke_handler(tauri::generate_handler![my_command])
+        .build()
+}
+
+#[tauri::command]
+fn my_command(db: State<Database>) -> Result<Vec<Item>, String> {
+    // ❌ Database 초기화 없음
+    // ❌ 앱 종료 시 DB 연결 정리 없음
+    db.query_items().map_err(|e| e.to_string())
+}
+```
+
+**문제점:**
+- 리소스 초기화 로직 없음
+- 앱 종료 시 cleanup 없음 (DB 연결 유지, 파일 잠금)
+- 상태 관리 누락
+
+## ✅ 올바른 패턴
+
+```rust
+use tauri::{
+    plugin::{Builder, TauriPlugin},
+    AppHandle, Manager, Runtime, State
+};
+use std::sync::Mutex;
+
+pub struct Database {
+    conn: Mutex<rusqlite::Connection>,
+}
+
+impl Database {
+    fn new(path: &str) -> Result<Self, rusqlite::Error> {
+        let conn = rusqlite::Connection::open(path)?;
+        Ok(Database {
+            conn: Mutex::new(conn),
+        })
+    }
+}
+
+pub fn init<R: Runtime>() -> TauriPlugin<R> {
+    Builder::new("my-plugin")
+        .invoke_handler(tauri::generate_handler![my_command])
+        .setup(|app_handle, _api| {
+            // ✅ 플러그인 초기화 시점
+            let app_data = app_handle.path().app_data_dir().unwrap();
+            let db_path = app_data.join("data.db");
+            let db = Database::new(db_path.to_str().unwrap())
+                .expect("Failed to init database");
+
+            app_handle.manage(db);
+            println!("Plugin initialized");
+
+            Ok(())
+        })
+        .on_event(|app_handle, event| {
+            // ✅ 앱 이벤트 핸들러
+            match event {
+                tauri::RunEvent::Exit => {
+                    println!("App exiting, cleaning up...");
+                }
+                tauri::RunEvent::ExitRequested { .. } => {
+                    println!("Exit requested");
+                }
+                _ => {}
+            }
+        })
+        .build()
+}
+
+#[tauri::command]
+fn my_command(db: State<Database>) -> Result<Vec<Item>, String> {
+    // ✅ 초기화된 Database 사용
+    let conn = db.conn.lock().unwrap();
+    conn.query_items().map_err(|e| e.to_string())
+}
+```
+
+**파일 핸들 정리 예시:**
+
+```rust
+use std::fs::File;
+use std::sync::Mutex;
+
+pub struct FileCache {
+    handles: Mutex<HashMap<String, File>>,
+}
+
+impl FileCache {
+    fn new() -> Self {
+        FileCache {
+            handles: Mutex::new(HashMap::new()),
+        }
+    }
+
+    fn cleanup(&self) {
+        let mut handles = self.handles.lock().unwrap();
+        for (path, _file) in handles.drain() {
+            println!("Closing file: {}", path);
+        }
+    }
+}
+
+impl Drop for FileCache {
+    fn drop(&mut self) {
+        // ✅ 자동 cleanup
+        self.cleanup();
+    }
+}
+
+pub fn init<R: Runtime>() -> TauriPlugin<R> {
+    Builder::new("file-cache")
+        .setup(|app_handle, _api| {
+            app_handle.manage(FileCache::new());
+            Ok(())
+        })
+        .on_event(|app_handle, event| {
+            if let tauri::RunEvent::Exit = event {
+                if let Some(cache) = app_handle.try_state::<FileCache>() {
+                    cache.cleanup();
+                }
+            }
+        })
+        .build()
+}
+```
+
+**비동기 리소스 정리 예시:**
+
+```rust
+use tokio::sync::RwLock;
+use reqwest::Client;
+
+pub struct ApiClient {
+    client: Client,
+    pending_requests: RwLock<Vec<tokio::task::JoinHandle<()>>>,
+}
+
+impl ApiClient {
+    fn new() -> Self {
+        ApiClient {
+            client: Client::new(),
+            pending_requests: RwLock::new(Vec::new()),
+        }
+    }
+
+    async fn shutdown(&self) {
+        let mut pending = self.pending_requests.write().await;
+        for handle in pending.drain(..) {
+            handle.abort();
+        }
+        println!("All pending requests aborted");
+    }
+}
+
+pub fn init<R: Runtime>() -> TauriPlugin<R> {
+    Builder::new("api-client")
+        .setup(|app_handle, _api| {
+            app_handle.manage(ApiClient::new());
+            Ok(())
+        })
+        .on_event(|app_handle, event| {
+            if let tauri::RunEvent::Exit = event {
+                if let Some(client) = app_handle.try_state::<ApiClient>() {
+                    tauri::async_runtime::block_on(client.shutdown());
+                }
+            }
+        })
+        .build()
+}
+```
+
+**커스텀 플러그인 구조 템플릿:**
+
+```rust
+use tauri::{plugin::{Builder, TauriPlugin}, Runtime, AppHandle, Manager};
+
+pub struct MyPluginState {
+    // 플러그인 상태
+}
+
+impl MyPluginState {
+    fn new() -> Self {
+        // 초기화 로직
+        Self {}
+    }
+
+    fn cleanup(&self) {
+        // 정리 로직
+    }
+}
+
+impl Drop for MyPluginState {
+    fn drop(&mut self) {
+        self.cleanup();
+    }
+}
+
+pub fn init<R: Runtime>() -> TauriPlugin<R> {
+    Builder::new("my-plugin")
+        .invoke_handler(tauri::generate_handler![
+            my_command_1,
+            my_command_2
+        ])
+        .setup(|app_handle, _api| {
+            // 플러그인 초기화
+            let state = MyPluginState::new();
+            app_handle.manage(state);
+            Ok(())
+        })
+        .on_event(|app_handle, event| {
+            // 이벤트 핸들러
+            match event {
+                tauri::RunEvent::Exit => {
+                    if let Some(state) = app_handle.try_state::<MyPluginState>() {
+                        state.cleanup();
+                    }
+                }
+                _ => {}
+            }
+        })
+        .build()
+}
+
+#[tauri::command]
+fn my_command_1(state: State<MyPluginState>) -> Result<String, String> {
+    // 커맨드 로직
+    Ok("Success".to_string())
+}
+```
+
+## 추가 컨텍스트
+
+**라이프사이클 단계:**
+1. `setup`: 플러그인 초기화 (앱 시작 시 한 번)
+2. `invoke_handler`: 커맨드 실행 (프론트엔드 호출 시)
+3. `on_event`: 앱 이벤트 처리 (Exit, ExitRequested 등)
+4. `Drop`: 자동 정리 (플러그인 상태가 drop될 때)
+
+**RunEvent 종류:**
+- `Exit`: 앱 종료 직전
+- `ExitRequested`: 앱 종료 요청 시 (취소 가능)
+- `WindowEvent`: 윈도우 이벤트
+- `Ready`: 앱 준비 완료
+
+**Tauri State 관리:**
+- `app_handle.manage()`: 전역 상태 등록
+- `State<T>`: 커맨드에서 상태 접근
+- `app_handle.try_state::<T>()`: 상태 가져오기 (Option)
+
+**참고:** [Tauri Plugin Development](https://beta.tauri.app/develop/plugins/)
+
+영향도: HIGH - 메모리 누수, 리소스 잠금, 앱 안정성

package/templates/.claude/skills/tauri-react-best-practices/rules/plugin-mobile-compat.md

@@ -0,0 +1,199 @@
+# 모바일 호환성 확인
+
+## 왜 중요한가
+
+Tauri v2는 iOS/Android를 지원하지만, 일부 플러그인과 API는 데스크톱 전용입니다. 모바일에서 미지원 API를 호출하면 런타임 에러나 크래시가 발생합니다. 플랫폼별 조건부 코드를 작성해야 크로스 플랫폼 앱을 안정적으로 배포할 수 있습니다.
+
+## ❌ 잘못된 패턴
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { open } from '@tauri-apps/plugin-dialog'
+
+function FilePicker() {
+  const selectFile = async () => {
+    // ❌ 모바일에서 dialog 플러그인 미지원 (크래시)
+    const file = await open({
+      multiple: false,
+      directory: false
+    })
+    console.log(file)
+  }
+
+  return <button onClick={selectFile}>Select File</button>
+}
+```
+
+**문제점:**
+- 플랫폼 구분 없이 데스크톱 전용 API 사용
+- 모바일에서 런타임 에러 발생
+- 플랫폼별 대체 로직 없음
+
+## ✅ 올바른 패턴
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { open } from '@tauri-apps/plugin-dialog'
+import { platform } from '@tauri-apps/plugin-os'
+
+function FilePicker() {
+  const selectFile = async () => {
+    const os = await platform()
+
+    if (os === 'android' || os === 'ios') {
+      // ✅ 모바일: 네이티브 파일 피커 사용
+      const result = await invoke<string>('mobile_pick_file')
+      console.log(result)
+    } else {
+      // ✅ 데스크톱: dialog 플러그인 사용
+      const file = await open({
+        multiple: false,
+        directory: false
+      })
+      console.log(file)
+    }
+  }
+
+  return <button onClick={selectFile}>Select File</button>
+}
+```
+
+**Rust 측 플랫폼 조건부 컴파일:**
+
+```rust
+#[tauri::command]
+fn get_system_info() -> String {
+    #[cfg(target_os = "android")]
+    {
+        "Android".to_string()
+    }
+
+    #[cfg(target_os = "ios")]
+    {
+        "iOS".to_string()
+    }
+
+    #[cfg(not(any(target_os = "android", target_os = "ios")))]
+    {
+        "Desktop".to_string()
+    }
+}
+```
+
+**모바일 전용 플러그인 사용:**
+
+```rust
+// Cargo.toml
+[dependencies]
+tauri-plugin-barcode-scanner = "2.0.0-beta"  // 모바일 전용
+
+// src/lib.rs
+#[cfg(mobile)]
+use tauri_plugin_barcode_scanner::BarcodeScanner;
+
+fn main() {
+    tauri::Builder::default()
+        .plugin(
+            #[cfg(mobile)]
+            tauri_plugin_barcode_scanner::init()
+        )
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+**React Native 스타일 플랫폼 분기:**
+
+```tsx
+import { platform } from '@tauri-apps/plugin-os'
+import { useEffect, useState } from 'react'
+
+function usePlatform() {
+  const [os, setOs] = useState<string>('unknown')
+
+  useEffect(() => {
+    platform().then(setOs)
+  }, [])
+
+  return {
+    os,
+    isDesktop: ['windows', 'macos', 'linux'].includes(os),
+    isMobile: ['android', 'ios'].includes(os),
+    isAndroid: os === 'android',
+    isIOS: os === 'ios'
+  }
+}
+
+function App() {
+  const { isDesktop, isMobile } = usePlatform()
+
+  return (
+    <div>
+      {isDesktop && <DesktopMenu />}
+      {isMobile && <MobileTabBar />}
+    </div>
+  )
+}
+```
+
+**파일 경로 처리:**
+
+```tsx
+import { appDataDir, join } from '@tauri-apps/api/path'
+import { platform } from '@tauri-apps/plugin-os'
+
+async function getConfigPath() {
+  const os = await platform()
+  const dataDir = await appDataDir()
+
+  if (os === 'android') {
+    // Android: /data/data/com.example.app/files
+    return await join(dataDir, 'config.json')
+  } else if (os === 'ios') {
+    // iOS: /var/mobile/Containers/Data/Application/.../Documents
+    return await join(dataDir, 'config.json')
+  } else {
+    // Desktop: ~/.local/share/com.example.app
+    return await join(dataDir, 'config.json')
+  }
+}
+```
+
+**모바일 미지원 플러그인 목록:**
+
+| 플러그인 | 데스크톱 | 모바일 | 대체 방법 |
+|---------|---------|--------|----------|
+| dialog | ✅ | ❌ | 네이티브 UI 사용 |
+| global-shortcut | ✅ | ❌ | 모바일은 제스처 사용 |
+| updater | ✅ | ❌ | Play Store/App Store 업데이트 |
+| window (일부) | ✅ | ⚠️ | 일부 API만 지원 |
+| shell (open) | ✅ | ✅ | URL 열기만 지원 |
+| fs | ✅ | ✅ | 전체 지원 |
+| http | ✅ | ✅ | 전체 지원 |
+
+## 추가 컨텍스트
+
+**모바일 개발 시 체크리스트:**
+1. `platform()` API로 플랫폼 구분
+2. 데스크톱 전용 플러그인 조건부 사용
+3. 파일 경로 플랫폼별 처리
+4. UI/UX 모바일 최적화 (터치, 작은 화면)
+5. 권한 요청 (카메라, 위치 등)
+
+**Rust cfg 속성:**
+```rust
+#[cfg(target_os = "android")]  // Android 전용
+#[cfg(target_os = "ios")]      // iOS 전용
+#[cfg(mobile)]                 // Android + iOS
+#[cfg(desktop)]                // Windows + macOS + Linux
+#[cfg(not(mobile))]            // 데스크톱만
+```
+
+**권장 사항:**
+- 플랫폼별 빌드 후 실제 기기에서 테스트
+- 에뮬레이터/시뮬레이터에서 미지원 API 확인
+- `try/catch`로 런타임 에러 처리
+
+**참고:** [Tauri Mobile Guide](https://beta.tauri.app/develop/mobile/)
+
+영향도: HIGH - 모바일 앱 안정성, 크로스 플랫폼 호환성

package/templates/.claude/skills/tauri-react-best-practices/rules/plugin-permission-scope.md

@@ -0,0 +1,193 @@
+# 플러그인별 최소 권한 + Scope
+
+## 왜 중요한가
+
+Tauri 플러그인은 기본적으로 모든 권한을 허용하지 않습니다. 필요한 커맨드만 명시하고 scope를 제한해야 보안 취약점을 방지할 수 있습니다. 과도한 권한은 악의적인 코드나 XSS 공격 시 시스템 접근을 허용할 수 있습니다.
+
+## ❌ 잘못된 패턴
+
+```json
+// tauri.conf.json
+{
+  "plugins": {
+    "fs": {
+      "all": true,  // ❌ 모든 파일 시스템 접근 허용
+      "scope": ["**"]  // ❌ 전체 디렉토리 접근 가능
+    },
+    "shell": {
+      "all": true  // ❌ 모든 셸 커맨드 실행 허용
+    }
+  }
+}
+```
+
+**문제점:**
+- 불필요한 권한 부여 (최소 권한 원칙 위반)
+- 악의적인 코드가 시스템 전체 접근 가능
+- XSS 공격 시 파일 삭제, 임의 명령 실행 가능
+
+## ✅ 올바른 패턴
+
+```json
+// tauri.conf.json
+{
+  "plugins": {
+    "fs": {
+      "scope": [
+        "$APPDATA/user-data/**",  // ✅ 앱 데이터 폴더만
+        "$RESOURCE/assets/**"     // ✅ 앱 리소스 폴더만
+      ],
+      "commands": {
+        "readFile": true,
+        "writeFile": true,
+        "readDir": true,
+        "exists": true
+      }
+    },
+    "shell": {
+      "scope": [
+        {
+          "name": "ffmpeg",
+          "cmd": "ffmpeg",
+          "args": [
+            "-i", { "validator": "\\.(mp4|avi|mov)$" },
+            "-o", { "validator": "^[^/\\\\]+$" }
+          ]
+        }
+      ]
+    },
+    "http": {
+      "scope": [
+        "https://api.example.com/*"  // ✅ 특정 도메인만
+      ],
+      "commands": {
+        "fetch": true
+      }
+    }
+  }
+}
+```
+
+**파일 시스템 플러그인 권한 예시:**
+
+```json
+{
+  "plugins": {
+    "fs": {
+      "scope": [
+        // 읽기 전용 리소스
+        {
+          "path": "$RESOURCE/**",
+          "permissions": ["read"]
+        },
+        // 읽기/쓰기 가능한 사용자 데이터
+        {
+          "path": "$APPDATA/config.json",
+          "permissions": ["read", "write"]
+        },
+        {
+          "path": "$APPDATA/cache/**",
+          "permissions": ["read", "write", "delete"]
+        }
+      ],
+      "commands": {
+        "readFile": true,
+        "writeFile": true,
+        "readDir": true,
+        "exists": true
+        // removeFile, renameFile 등 불필요한 커맨드 비활성화
+      }
+    }
+  }
+}
+```
+
+**HTTP 플러그인 권한 예시:**
+
+```json
+{
+  "plugins": {
+    "http": {
+      "scope": [
+        "https://api.example.com/*",
+        "https://cdn.example.com/assets/*"
+      ],
+      "commands": {
+        "fetch": true
+      }
+    }
+  }
+}
+```
+
+**Shell 플러그인 권한 예시:**
+
+```json
+{
+  "plugins": {
+    "shell": {
+      "scope": [
+        {
+          "name": "video-convert",
+          "cmd": "ffmpeg",
+          "args": [
+            "-i", { "validator": "^[a-zA-Z0-9_-]+\\.(mp4|avi)$" },
+            "-codec", "copy",
+            { "validator": "^output\\.mp4$" }
+          ],
+          "sidecar": false
+        }
+      ]
+    }
+  }
+}
+```
+
+**런타임 권한 요청 (Tauri v2.1+):**
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { requestPermission } from '@tauri-apps/plugin-fs'
+
+async function writeUserConfig(data: Config) {
+  const granted = await requestPermission({
+    path: '$APPDATA/config.json',
+    permissions: ['write']
+  })
+
+  if (!granted) {
+    throw new Error('Permission denied')
+  }
+
+  await invoke('write_config', { data })
+}
+```
+
+## 추가 컨텍스트
+
+**Scope 패턴:**
+- `$APPDATA`: 사용자 앱 데이터 디렉토리
+- `$RESOURCE`: 앱 리소스 디렉토리 (번들된 파일)
+- `$HOME`: 사용자 홈 디렉토리 (가급적 피하기)
+- `**`: 하위 디렉토리 포함 (주의해서 사용)
+
+**공식 플러그인 권한 체크리스트:**
+
+| 플러그인 | 최소 권한 예시 |
+|---------|---------------|
+| fs | 특정 디렉토리만 + read/write 구분 |
+| http | 특정 도메인만 허용 |
+| shell | 화이트리스트 커맨드 + args 검증 |
+| notification | 기본 권한 (OS 수준 허용 필요) |
+| clipboard | 기본 권한 |
+| dialog | 기본 권한 |
+
+**보안 원칙:**
+1. 최소 권한 원칙: 필요한 권한만 부여
+2. Scope 제한: 전체 파일 시스템 접근 금지
+3. 화이트리스트: 허용 목록 기반 권한 관리
+4. Validator: args에 정규식 검증 추가
+
+**참고:** [Tauri Security Best Practices](https://beta.tauri.app/security/best-practices/)
+
+영향도: CRITICAL - 보안, 권한 관리, XSS 공격 방어