@kood/claude-code 0.6.6 → 0.7.0

package/templates/.claude/skills/tauri-react-best-practices/rules/deploy-updater.md

@@ -0,0 +1,226 @@
+# 자동 업데이트 서명 키 관리
+
+## 왜 중요한가
+
+Tauri의 자동 업데이트는 서명된 업데이트 파일만 설치합니다. 서명 키를 올바르게 생성하고 환경 변수로 관리하지 않으면 업데이트가 실패하거나 보안 취약점이 발생합니다. 키를 하드코딩하면 소스 코드 유출 시 악의적인 업데이트 배포가 가능합니다.
+
+## ❌ 잘못된 패턴
+
+```json
+// tauri.conf.json
+{
+  "bundle": {
+    "updater": {
+      "active": true,
+      "endpoints": ["https://example.com/updates/{{target}}/{{current_version}}"],
+      // ❌ 공개 키를 하드코딩 (private 키는 더 위험)
+      "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDEyMzQ1Njc4OTBBQkNERUYKUldRZEdzV3RQNjNiUEsxL0ZyQWt4SUVGQldRcVFRSkRYRFFRWENnPT0K"
+    }
+  }
+}
+```
+
+```bash
+# ❌ private 키를 프로젝트 디렉토리에 보관 (Git에 커밋 위험)
+ls ~/.tauri/myapp.key
+```
+
+**문제점:**
+- 서명 키 미설정 또는 하드코딩
+- private 키가 Git에 커밋될 위험
+- CI/CD에서 키 관리 없음
+- 업데이트 서명 실패
+
+## ✅ 올바른 패턴
+
+### 1. 서명 키 생성
+
+```bash
+# Tauri CLI로 서명 키 생성
+pnpm tauri signer generate -- -w ~/.tauri/myapp.key
+
+# 출력:
+# Private key: ~/.tauri/myapp.key
+# Public key: dW50cnVzdGVkIGNvbW1lbnQ6...
+# Password: (비워두면 비밀번호 없음)
+```
+
+### 2. 환경 변수로 키 관리
+
+```bash
+# .env (Git에 커밋하지 않음)
+TAURI_SIGNING_PRIVATE_KEY="dW50cnVzdGVkIGNvbW1lbnQ6IHJzaWduIGVuY3J5cHRlZCBzZWNyZXQga2V5ClJXUlRZMEl5T0ZraGtUcjVVU28ybmNaNFN0Y1lHSzc0TVh4MkJiUGREN2xrPQo="
+TAURI_SIGNING_PRIVATE_KEY_PASSWORD=""  # 비밀번호가 있으면 설정
+```
+
+```bash
+# .gitignore
+.env
+*.key
+```
+
+### 3. tauri.conf.json 설정
+
+```json
+{
+  "bundle": {
+    "identifier": "com.example.app",
+    "version": "1.0.0",
+    "updater": {
+      "active": true,
+      "endpoints": [
+        "https://example.com/updates/{{target}}/{{current_version}}"
+      ],
+      "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDEyMzQ1Njc4OTBBQkNERUYKUldRZEdzV3RQNjNiUEsxL0ZyQWt4SUVGQldRcVFRSkRYRFFRWENnPT0K"
+    }
+  }
+}
+```
+
+### 4. 빌드 시 서명
+
+```bash
+# private 키 환경 변수로 주입
+export TAURI_SIGNING_PRIVATE_KEY=$(cat ~/.tauri/myapp.key)
+export TAURI_SIGNING_PRIVATE_KEY_PASSWORD=""
+
+# 빌드 (자동으로 서명됨)
+pnpm tauri build
+```
+
+### 5. 업데이트 서버 응답 형식
+
+```json
+{
+  "version": "1.0.1",
+  "date": "2024-02-09T12:00:00Z",
+  "platforms": {
+    "darwin-aarch64": {
+      "url": "https://example.com/releases/MyApp-1.0.1-arm64.app.tar.gz",
+      "signature": "dW50cnVzdGVkIGNvbW1lbnQ6IHNpZ25hdHVyZSBmcm9tIHRhdXJpIHNlY3JldCBrZXkKUldRZEdzV3RQNjNiUEsxL0ZyQWt4SUVGQldRcVFRSkRYRFFRWENnPT0K"
+    },
+    "darwin-x86_64": {
+      "url": "https://example.com/releases/MyApp-1.0.1-x64.app.tar.gz",
+      "signature": "..."
+    },
+    "windows-x86_64": {
+      "url": "https://example.com/releases/MyApp-1.0.1-x64.msi.zip",
+      "signature": "..."
+    }
+  }
+}
+```
+
+### 6. GitHub Actions CI/CD
+
+```yaml
+name: Release
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: ${{ matrix.platform }}
+    strategy:
+      matrix:
+        platform: [macos-latest, windows-latest, ubuntu-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build with signing
+        env:
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+        run: pnpm tauri build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: app-${{ matrix.platform }}
+          path: ./target/release/bundle/**/*
+```
+
+**GitHub Secrets 설정:**
+1. GitHub 저장소 → Settings → Secrets and variables → Actions
+2. New repository secret:
+   - `TAURI_SIGNING_PRIVATE_KEY`: `cat ~/.tauri/myapp.key` 출력값
+   - `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`: 비밀번호 (없으면 빈 문자열)
+
+### 7. 프론트엔드에서 업데이트 확인
+
+```tsx
+import { check, installUpdate } from '@tauri-apps/plugin-updater'
+import { relaunch } from '@tauri-apps/plugin-process'
+import { useEffect, useState } from 'react'
+
+function UpdateChecker() {
+  const [updateAvailable, setUpdateAvailable] = useState(false)
+  const [loading, setLoading] = useState(false)
+
+  useEffect(() => {
+    check().then(update => {
+      if (update?.available) {
+        setUpdateAvailable(true)
+      }
+    })
+  }, [])
+
+  const handleUpdate = async () => {
+    setLoading(true)
+    try {
+      await installUpdate()
+      await relaunch()
+    } catch (error) {
+      console.error('Update failed:', error)
+      setLoading(false)
+    }
+  }
+
+  if (!updateAvailable) return null
+
+  return (
+    <div className="update-banner">
+      <p>새 버전이 있습니다!</p>
+      <button onClick={handleUpdate} disabled={loading}>
+        {loading ? 'Updating...' : 'Update Now'}
+      </button>
+    </div>
+  )
+}
+```
+
+## 추가 컨텍스트
+
+**서명 키 관리 원칙:**
+1. private 키는 절대 Git에 커밋하지 않음
+2. 환경 변수로만 관리 (`.env`, GitHub Secrets)
+3. public 키는 `tauri.conf.json`에 하드코딩 가능
+4. private 키는 팀 내 안전한 저장소에 백업
+
+**Updater 엔드포인트 변수:**
+- `{{target}}`: 플랫폼 식별자 (darwin-aarch64, windows-x86_64 등)
+- `{{current_version}}`: 현재 앱 버전
+- `{{arch}}`: CPU 아키텍처
+
+**서명 파일 위치:**
+- macOS: `*.app.tar.gz.sig`
+- Windows: `*.msi.zip.sig`
+- Linux: `*.AppImage.tar.gz.sig`
+
+**권장 업데이트 서버:**
+- GitHub Releases (무료, 간단)
+- AWS S3 + CloudFront
+- Cloudflare R2
+- 자체 서버 (Nginx/Caddy)
+
+**참고:** [Tauri Updater Guide](https://beta.tauri.app/plugin/updater/)
+
+영향도: CRITICAL - 보안, 자동 업데이트 기능, 배포 신뢰성

package/templates/.claude/skills/tauri-react-best-practices/rules/ipc-async-commands.md

@@ -0,0 +1,172 @@
+---
+title: Use async Commands for Non-Blocking Operations
+impact: CRITICAL
+impactDescription: Prevent UI freezes with async Rust commands
+tags: ipc, async, tokio, performance, tauri-v2
+---
+
+# async 커맨드로 UI 차단 방지
+
+## 왜 중요한가
+
+Rust 커맨드가 동기(blocking) 작업을 수행하면 Tauri 런타임이 차단되어 UI가 멈춥니다. `async` 커맨드를 사용하면 I/O, 네트워크, 파일 작업을 비차단(non-blocking) 방식으로 실행하여 UI 응답성을 유지할 수 있습니다.
+
+**영향도:**
+- UI 응답성: 차단 방지
+- 동시성: 여러 작업 병렬 처리
+- 사용자 경험: 부드러운 인터랙션
+
+## ❌ 잘못된 패턴
+
+**동기 커맨드에서 blocking 작업:**
+
+```rust
+use std::fs;
+use std::thread::sleep;
+use std::time::Duration;
+
+// ❌ 동기 커맨드에서 파일 I/O (UI 차단)
+#[tauri::command]
+fn read_large_file(path: String) -> Result<String, String> {
+  // 메인 스레드 차단
+  let content = fs::read_to_string(&path)
+    .map_err(|e| e.to_string())?;
+  Ok(content)
+}
+
+// ❌ 동기 커맨드에서 sleep (UI 멈춤)
+#[tauri::command]
+fn slow_operation() -> String {
+  sleep(Duration::from_secs(5)); // 5초 동안 UI 멈춤
+  "Done".to_string()
+}
+```
+
+**문제점:**
+- 커맨드 실행 중 UI 완전히 멈춤
+- 다른 IPC 요청도 차단됨
+- 사용자 경험 저하
+
+## ✅ 올바른 패턴
+
+**async 커맨드로 비차단 실행:**
+
+```rust
+use tokio::fs;
+use tokio::time::{sleep, Duration};
+
+// ✅ async 커맨드로 파일 I/O (UI 차단 없음)
+#[tauri::command]
+async fn read_large_file(path: String) -> Result<String, String> {
+  // tokio 비동기 파일 I/O
+  let content = fs::read_to_string(&path)
+    .await
+    .map_err(|e| e.to_string())?;
+  Ok(content)
+}
+
+// ✅ async 커맨드로 지연 작업 (UI 응답 유지)
+#[tauri::command]
+async fn slow_operation() -> String {
+  sleep(Duration::from_secs(5)).await; // 다른 작업 진행 가능
+  "Done".to_string()
+}
+```
+
+**HTTP 요청 예시:**
+
+```rust
+use reqwest;
+
+// ✅ 비동기 HTTP 요청
+#[tauri::command]
+async fn fetch_data(url: String) -> Result<String, String> {
+  let response = reqwest::get(&url)
+    .await
+    .map_err(|e| e.to_string())?
+    .text()
+    .await
+    .map_err(|e| e.to_string())?;
+  Ok(response)
+}
+```
+
+**병렬 작업 실행:**
+
+```rust
+use tokio::task::spawn;
+
+#[tauri::command]
+async fn process_multiple_files(paths: Vec<String>) -> Result<Vec<String>, String> {
+  let mut tasks = vec![];
+
+  for path in paths {
+    // 각 파일을 별도 태스크로 처리
+    let task = spawn(async move {
+      fs::read_to_string(&path).await
+    });
+    tasks.push(task);
+  }
+
+  // 모든 태스크 완료 대기
+  let results = futures::future::try_join_all(tasks)
+    .await
+    .map_err(|e| e.to_string())?;
+
+  results
+    .into_iter()
+    .collect::<Result<Vec<_>, _>>()
+    .map_err(|e| e.to_string())
+}
+```
+
+## async에서 &str 사용 제한
+
+**❌ async 함수에서 &str 파라미터 불가:**
+
+```rust
+// ❌ 컴파일 에러: async 함수는 'static 라이프타임 필요
+#[tauri::command]
+async fn process_text(text: &str) -> String {
+  // Error: `text` has an incompatible lifetime
+  text.to_uppercase()
+}
+```
+
+**✅ String 사용:**
+
+```rust
+// ✅ String으로 소유권 확보
+#[tauri::command]
+async fn process_text(text: String) -> String {
+  text.to_uppercase()
+}
+```
+
+**이유:**
+- async 함수는 Future로 변환되어 나중에 실행됨
+- 참조(&str)는 원본 데이터가 유효함을 보장할 수 없음
+- String은 소유권을 가져 'static 라이프타임 요구사항 충족
+
+## 추가 컨텍스트
+
+**언제 async 커맨드를 사용해야 하는가:**
+- 파일 I/O (`tokio::fs`)
+- 네트워크 요청 (`reqwest`, `tokio::net`)
+- 데이터베이스 쿼리 (`sqlx`, `tokio-postgres`)
+- 타이머/지연 (`tokio::time::sleep`)
+- CPU 집약적이지 않은 모든 작업
+
+**동기 커맨드를 사용해도 되는 경우:**
+- 즉시 완료되는 간단한 계산
+- 상태 읽기/쓰기 (Mutex)
+- 메모리 작업만 수행하는 경우
+
+**주의사항:**
+- `Cargo.toml`에 `tokio` 의존성 추가 필요: `tokio = { version = "1", features = ["full"] }`
+- CPU 집약적 작업은 `tokio::task::spawn_blocking` 사용
+- async 커맨드 내부에서 std 동기 함수 호출 시 주의
+
+**참고:**
+- [Tauri Async Commands](https://tauri.app/develop/calling-rust/#async-commands)
+- [Tokio Documentation](https://tokio.rs/)

package/templates/.claude/skills/tauri-react-best-practices/rules/ipc-batch-commands.md

@@ -0,0 +1,133 @@
+---
+title: Batch Multiple invoke Calls into Single Command
+impact: CRITICAL
+impactDescription: Reduce IPC round-trips from N to 1
+tags: ipc, performance, batch, tauri-v2
+---
+
+# 배치 커맨드로 IPC 왕복 최소화
+
+## 왜 중요한가
+
+여러 개의 `invoke` 호출을 순차적으로 실행하면 각각 IPC 왕복(round-trip)이 발생하여 성능이 저하됩니다. 특히 루프 안에서 `invoke`를 호출하면 N번의 IPC 오버헤드가 발생합니다. 배치 커맨드로 통합하면 IPC 왕복을 1회로 줄여 처리 속도를 크게 향상시킬 수 있습니다.
+
+**영향도:**
+- IPC 왕복: N회 → 1회
+- 지연 시간: 누적 감소
+- 처리량: 5-10배 향상 (데이터 크기에 따라)
+
+## ❌ 잘못된 패턴
+
+**프론트엔드에서 개별 호출:**
+
+```typescript
+// ❌ 루프에서 N번 invoke 호출
+import { invoke } from '@tauri-apps/api/core';
+
+async function processItems(items: string[]) {
+  const results = [];
+  for (const item of items) {
+    // 각 호출마다 IPC 왕복 발생
+    const result = await invoke<string>('process_item', { item });
+    results.push(result);
+  }
+  return results;
+}
+```
+
+**문제점:**
+- 100개 아이템 = 100번 IPC 왕복
+- 각 호출마다 직렬화/역직렬화 오버헤드
+- 네트워크 레이턴시와 유사한 누적 지연
+
+## ✅ 올바른 패턴
+
+**배치 커맨드로 통합:**
+
+```rust
+// ✅ Rust: 배치 처리 커맨드
+#[tauri::command]
+fn process_batch(items: Vec<String>) -> Result<Vec<String>, String> {
+  items
+    .iter()
+    .map(|item| process_item(item))
+    .collect::<Result<Vec<_>, _>>()
+}
+
+fn process_item(item: &str) -> Result<String, String> {
+  // 실제 처리 로직
+  Ok(item.to_uppercase())
+}
+```
+
+```typescript
+// ✅ 프론트엔드: 1번 호출
+import { invoke } from '@tauri-apps/api/core';
+
+async function processItems(items: string[]) {
+  // 단일 IPC 왕복
+  const results = await invoke<string[]>('process_batch', { items });
+  return results;
+}
+
+// 사용 예시
+const items = ['apple', 'banana', 'cherry'];
+const results = await processItems(items); // ['APPLE', 'BANANA', 'CHERRY']
+```
+
+**병렬 처리가 필요한 경우:**
+
+```rust
+use rayon::prelude::*;
+
+#[tauri::command]
+fn process_batch_parallel(items: Vec<String>) -> Result<Vec<String>, String> {
+  items
+    .par_iter()  // 병렬 반복자
+    .map(|item| process_item(item))
+    .collect::<Result<Vec<_>, _>>()
+}
+```
+
+**부분 실패 처리:**
+
+```rust
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize)]
+struct BatchResult {
+  success: Vec<String>,
+  failed: Vec<(String, String)>, // (item, error)
+}
+
+#[tauri::command]
+fn process_batch_resilient(items: Vec<String>) -> BatchResult {
+  let mut success = Vec::new();
+  let mut failed = Vec::new();
+
+  for item in items {
+    match process_item(&item) {
+      Ok(result) => success.push(result),
+      Err(err) => failed.push((item, err)),
+    }
+  }
+
+  BatchResult { success, failed }
+}
+```
+
+## 추가 컨텍스트
+
+**언제 배치 커맨드를 사용해야 하는가:**
+- 같은 커맨드를 3회 이상 호출해야 할 때
+- 루프 안에서 `invoke`를 호출할 때
+- 배열 데이터를 개별 처리해야 할 때
+
+**주의사항:**
+- 배치 크기가 매우 큰 경우(10,000+ 아이템) 청크 단위로 분할 호출
+- 메모리 사용량 모니터링 필요
+- 진행률 표시가 필요하면 [Channel 스트리밍](./ipc-channel-streaming.md) 패턴 사용
+
+**참고:**
+- [Tauri IPC Guide](https://tauri.app/concept/inter-process-communication/)
+- [Calling Rust from Frontend](https://tauri.app/develop/calling-rust/)