@kood/claude-code 0.6.6 → 0.7.0

package/templates/.claude/skills/tauri-react-best-practices/rules/ipc-binary-response.md

@@ -0,0 +1,198 @@
+---
+title: Use Response for Binary Data to Bypass JSON Serialization
+impact: HIGH
+impactDescription: 3-5x faster, no size overhead for binary data
+tags: ipc, performance, binary, response, tauri-v2
+---
+
+# Response로 바이너리 데이터 직렬화 우회
+
+## 왜 중요한가
+
+바이너리 데이터를 `Vec<u8>`로 반환하면 JSON으로 직렬화되어 크기가 증가하고 속도가 느립니다. `tauri::ipc::Response`를 사용하면 JSON 직렬화를 우회하여 raw 바이너리를 직접 전송할 수 있습니다.
+
+**영향도:**
+- 속도: 3-5배 향상
+- 크기: 30-40% 감소 (Base64 인코딩 없음)
+- 메모리: 복사 최소화
+
+## ❌ 잘못된 패턴
+
+**Vec<u8> 반환 (JSON 직렬화됨):**
+
+```rust
+use std::fs;
+
+// ❌ Vec<u8>는 JSON 배열로 직렬화됨
+#[tauri::command]
+fn read_image(path: String) -> Result<Vec<u8>, String> {
+  fs::read(&path).map_err(|e| e.to_string())
+}
+
+// 결과: [255, 216, 255, 224, ...] 형태로 직렬화
+// 1MB 이미지 → 1.3MB JSON 배열
+```
+
+```typescript
+// ❌ 프론트엔드에서 다시 Uint8Array로 변환 필요
+const imageBytes = await invoke<number[]>('read_image', { path });
+const blob = new Blob([new Uint8Array(imageBytes)]);
+```
+
+**문제점:**
+- JSON 직렬화 오버헤드
+- 크기 증가 (각 바이트가 숫자로 표현)
+- 메모리 복사 증가
+
+## ✅ 올바른 패턴
+
+**Response로 raw 바이너리 반환:**
+
+```rust
+use tauri::ipc::Response;
+use std::fs;
+
+// ✅ Response로 JSON 직렬화 우회
+#[tauri::command]
+fn read_image(path: String) -> Result<Response, String> {
+  let bytes = fs::read(&path).map_err(|e| e.to_string())?;
+  Ok(Response::new(bytes))
+}
+```
+
+```typescript
+// ✅ 프론트엔드: 자동으로 Uint8Array로 수신
+const imageBytes = await invoke<Uint8Array>('read_image', { path });
+const blob = new Blob([imageBytes], { type: 'image/png' });
+const url = URL.createObjectURL(blob);
+
+// 이미지 표시
+<img src={url} alt="Loaded from Rust" />
+```
+
+**스트리밍 대용량 파일:**
+
+```rust
+use tauri::ipc::{Channel, Response};
+use tokio::fs::File;
+use tokio::io::AsyncReadExt;
+
+// ✅ 작은 파일: Response 직접 반환
+#[tauri::command]
+async fn read_small_file(path: String) -> Result<Response, String> {
+  let bytes = tokio::fs::read(&path)
+    .await
+    .map_err(|e| e.to_string())?;
+  Ok(Response::new(bytes))
+}
+
+// ✅ 큰 파일: Channel로 청크 스트리밍
+#[tauri::command]
+async fn read_large_file(
+  path: String,
+  on_chunk: Channel<Response>,
+) -> Result<(), String> {
+  let mut file = File::open(&path)
+    .await
+    .map_err(|e| e.to_string())?;
+
+  let mut buffer = vec![0u8; 65536]; // 64KB 청크
+
+  loop {
+    let n = file.read(&mut buffer)
+      .await
+      .map_err(|e| e.to_string())?;
+
+    if n == 0 { break; }
+
+    on_chunk.send(Response::new(buffer[..n].to_vec()))
+      .map_err(|e| e.to_string())?;
+  }
+
+  Ok(())
+}
+```
+
+**바이너리 데이터 생성 예시:**
+
+```rust
+use image::{ImageBuffer, Rgb};
+
+#[tauri::command]
+fn generate_thumbnail(
+  path: String,
+  width: u32,
+  height: u32,
+) -> Result<Response, String> {
+  let img = image::open(&path)
+    .map_err(|e| e.to_string())?;
+
+  let thumbnail = img.resize(
+    width,
+    height,
+    image::imageops::FilterType::Lanczos3,
+  );
+
+  let mut bytes: Vec<u8> = Vec::new();
+  thumbnail.write_to(
+    &mut std::io::Cursor::new(&mut bytes),
+    image::ImageFormat::Png,
+  ).map_err(|e| e.to_string())?;
+
+  Ok(Response::new(bytes))
+}
+```
+
+## JavaScript에서 Blob 생성
+
+**다양한 바이너리 데이터 처리:**
+
+```typescript
+// 이미지 파일
+const imageBytes = await invoke<Uint8Array>('read_image', { path });
+const imageBlob = new Blob([imageBytes], { type: 'image/png' });
+const imageUrl = URL.createObjectURL(imageBlob);
+
+// PDF 파일
+const pdfBytes = await invoke<Uint8Array>('read_pdf', { path });
+const pdfBlob = new Blob([pdfBytes], { type: 'application/pdf' });
+
+// 비디오 스트리밍
+const videoChunks: Uint8Array[] = [];
+const onChunk = new Channel<Uint8Array>();
+onChunk.onmessage = (chunk) => videoChunks.push(chunk);
+await invoke('stream_video', { path, onChunk });
+const videoBlob = new Blob(videoChunks, { type: 'video/mp4' });
+
+// 다운로드 링크 생성
+const downloadUrl = URL.createObjectURL(videoBlob);
+const a = document.createElement('a');
+a.href = downloadUrl;
+a.download = 'video.mp4';
+a.click();
+
+// 메모리 정리
+URL.revokeObjectURL(downloadUrl);
+```
+
+## 추가 컨텍스트
+
+**언제 Response를 사용해야 하는가:**
+- 이미지, 비디오, 오디오 파일
+- PDF, 압축 파일 등 바이너리 문서
+- 암호화된 데이터
+- 프로토콜 버퍼, MessagePack 등 바이너리 형식
+
+**JSON 직렬화가 적합한 경우:**
+- 구조화된 데이터 (객체, 배열)
+- 작은 숫자 배열 (< 100 요소)
+- 타입 안전성이 중요한 경우
+
+**주의사항:**
+- `Response::new()`는 `Vec<u8>` 소유권을 가져감
+- 매우 큰 파일(100MB+)은 Channel 스트리밍 사용
+- `URL.createObjectURL()` 후 `URL.revokeObjectURL()`로 메모리 정리 필수
+
+**참고:**
+- [Tauri Response API](https://docs.rs/tauri/latest/tauri/ipc/struct.Response.html)
+- [MDN Blob API](https://developer.mozilla.org/en-US/docs/Web/API/Blob)

package/templates/.claude/skills/tauri-react-best-practices/rules/ipc-channel-streaming.md

@@ -0,0 +1,186 @@
+---
+title: Use Channels for Large Data Streaming
+impact: CRITICAL
+impactDescription: 5-10x faster than Events for continuous data streams
+tags: ipc, performance, channel, streaming, tauri-v2
+---
+
+# Channel로 대용량 데이터 스트리밍
+
+## 왜 중요한가
+
+대용량 데이터나 연속적인 진행률 업데이트를 전송할 때, Events는 각 메시지마다 오버헤드가 크고 느립니다. Tauri v2의 Channel은 스트리밍 최적화 프로토콜로 5-10배 빠른 처리량을 제공합니다.
+
+**영향도:**
+- 처리량: 5-10배 향상
+- 메모리: 버퍼링 최적화
+- 응답성: 실시간 진행률 표시
+
+## ❌ 잘못된 패턴
+
+**Events로 대용량 스트리밍:**
+
+```rust
+use tauri::{AppHandle, Emitter};
+
+// ❌ Events로 청크 전송 (느림, 오버헤드 큼)
+#[tauri::command]
+async fn download_file(app: AppHandle, url: String) -> Result<(), String> {
+  let mut downloaded = 0u64;
+  let total = 1_000_000u64;
+
+  for chunk in 0..1000 {
+    downloaded += 1000;
+    // 각 emit마다 이벤트 버스 오버헤드
+    app.emit("download-progress", (downloaded, total))
+      .map_err(|e| e.to_string())?;
+
+    // 실제 다운로드 로직...
+  }
+  Ok(())
+}
+```
+
+```typescript
+// ❌ 프론트엔드: Events 리스닝
+import { listen } from '@tauri-apps/api/event';
+
+listen<[number, number]>('download-progress', (event) => {
+  const [downloaded, total] = event.payload;
+  updateProgressBar(downloaded / total);
+});
+
+await invoke('download_file', { url: 'https://...' });
+```
+
+**문제점:**
+- Events는 브로드캐스트 방식 (모든 윈도우에 전송)
+- 각 메시지마다 이벤트 버스 오버헤드
+- 백프레셔(backpressure) 제어 없음
+
+## ✅ 올바른 패턴
+
+**Channel로 스트리밍:**
+
+```rust
+use tauri::ipc::Channel;
+
+// ✅ Channel로 스트리밍 (빠름, 직접 연결)
+#[tauri::command]
+async fn download_file(
+  url: String,
+  on_progress: Channel<(u64, u64)>,
+) -> Result<(), String> {
+  let mut downloaded = 0u64;
+  let total = 1_000_000u64;
+
+  for _chunk in 0..1000 {
+    downloaded += 1000;
+    // Channel은 단일 연결, 낮은 오버헤드
+    on_progress.send((downloaded, total))
+      .map_err(|e| e.to_string())?;
+
+    // 실제 다운로드 로직...
+  }
+  Ok(())
+}
+```
+
+```typescript
+// ✅ 프론트엔드: Channel 사용
+import { invoke, Channel } from '@tauri-apps/api/core';
+
+async function downloadFile(url: string) {
+  const onProgress = new Channel<[number, number]>();
+
+  onProgress.onmessage = ([downloaded, total]) => {
+    updateProgressBar(downloaded / total);
+  };
+
+  await invoke('download_file', { url, onProgress });
+}
+```
+
+**파일 스트리밍 예시:**
+
+```rust
+use tokio::fs::File;
+use tokio::io::AsyncReadExt;
+
+#[tauri::command]
+async fn stream_file_chunks(
+  path: String,
+  on_chunk: Channel<Vec<u8>>,
+) -> Result<(), String> {
+  let mut file = File::open(&path)
+    .await
+    .map_err(|e| e.to_string())?;
+
+  let mut buffer = vec![0u8; 8192]; // 8KB 청크
+
+  loop {
+    let n = file.read(&mut buffer)
+      .await
+      .map_err(|e| e.to_string())?;
+
+    if n == 0 { break; }
+
+    on_chunk.send(buffer[..n].to_vec())
+      .map_err(|e| e.to_string())?;
+  }
+
+  Ok(())
+}
+```
+
+```typescript
+import { Channel } from '@tauri-apps/api/core';
+
+const chunks: Uint8Array[] = [];
+const onChunk = new Channel<number[]>();
+
+onChunk.onmessage = (chunk) => {
+  chunks.push(new Uint8Array(chunk));
+};
+
+await invoke('stream_file_chunks', {
+  path: '/path/to/large-file.bin',
+  onChunk,
+});
+
+// 모든 청크 합치기
+const blob = new Blob(chunks);
+```
+
+## Channels vs Events 비교
+
+| 측면 | Channels | Events |
+|------|----------|--------|
+| **방향** | Rust → Frontend (단방향) | 양방향 브로드캐스트 |
+| **수신자** | 호출한 윈도우만 | 모든 윈도우 |
+| **처리량** | 높음 (5-10x) | 낮음 |
+| **오버헤드** | 낮음 (직접 연결) | 높음 (이벤트 버스) |
+| **백프레셔** | 지원 | 미지원 |
+| **사용 사례** | 대용량 스트리밍, 진행률 | 알림, 상태 브로드캐스트 |
+
+## 추가 컨텍스트
+
+**언제 Channel을 사용해야 하는가:**
+- 진행률 업데이트 (다운로드, 인코딩 등)
+- 파일 청크 스트리밍
+- 실시간 데이터 피드 (로그, 센서 데이터)
+- 100+ 메시지를 빠르게 전송해야 할 때
+
+**언제 Events를 사용해야 하는가:**
+- 모든 윈도우에 알림 필요
+- 간헐적인 이벤트 (클릭, 상태 변경)
+- 양방향 통신 필요
+
+**주의사항:**
+- Channel은 **타입 파라미터**를 반드시 명시해야 함: `Channel<T>`
+- 프론트엔드에서 `onmessage` 핸들러 설정 후 `invoke` 호출
+- Channel은 `invoke` 호출이 끝나면 자동으로 닫힘
+
+**참고:**
+- [Tauri Channels Guide](https://tauri.app/develop/calling-frontend/#channels)
+- [IPC Concept](https://tauri.app/concept/inter-process-communication/)

package/templates/.claude/skills/tauri-react-best-practices/rules/ipc-error-handling.md

@@ -0,0 +1,250 @@
+---
+title: Use Structured Error Types with thiserror
+impact: CRITICAL
+impactDescription: Debuggable errors, error code-based handling
+tags: ipc, error-handling, thiserror, serde, tauri-v2
+---
+
+# 구조화된 에러 타입으로 디버깅 향상
+
+## 왜 중요한가
+
+`Result<T, String>` 같은 단순 에러는 디버깅이 어렵고 프론트엔드에서 에러 종류별 처리가 불가능합니다. `thiserror`로 구조화된 에러를 정의하고 `serde::Serialize`를 구현하면 타입 안전하고 디버깅 가능한 에러 처리가 가능합니다.
+
+**영향도:**
+- 디버깅: 에러 종류, 원인 명확화
+- UX: 에러별 맞춤 메시지 표시
+- 유지보수: 에러 코드 기반 처리
+
+## ❌ 잘못된 패턴
+
+**단순 String 에러:**
+
+```rust
+// ❌ String 에러 (종류 구분 불가)
+#[tauri::command]
+fn read_file(path: String) -> Result<String, String> {
+  std::fs::read_to_string(&path)
+    .map_err(|e| e.to_string()) // 에러 타입 정보 손실
+}
+
+#[tauri::command]
+fn delete_file(path: String) -> Result<(), String> {
+  std::fs::remove_file(&path)
+    .map_err(|e| format!("Failed to delete: {}", e))
+}
+```
+
+```typescript
+// ❌ 프론트엔드: 에러 문자열 파싱으로 종류 판단
+try {
+  await invoke('read_file', { path: '/secret.txt' });
+} catch (err) {
+  // 문자열 파싱으로 에러 종류 추측 (취약함)
+  if (err.includes('permission')) {
+    alert('권한이 없습니다');
+  } else if (err.includes('not found')) {
+    alert('파일을 찾을 수 없습니다');
+  }
+}
+```
+
+**문제점:**
+- 에러 종류 구분 불가
+- 디버깅 정보 부족
+- 프론트엔드에서 일관된 처리 어려움
+
+## ✅ 올바른 패턴
+
+**thiserror로 구조화된 에러:**
+
+### 1. 의존성 추가
+
+```toml
+# src-tauri/Cargo.toml
+[dependencies]
+thiserror = "2.0"
+serde = { version = "1.0", features = ["derive"] }
+```
+
+### 2. 에러 타입 정의
+
+```rust
+use serde::{Serialize, Serializer};
+use thiserror::Error;
+
+// ✅ 구조화된 에러 enum
+#[derive(Debug, Error)]
+enum AppError {
+  #[error("File not found: {path}")]
+  FileNotFound { path: String },
+
+  #[error("Permission denied: {path}")]
+  PermissionDenied { path: String },
+
+  #[error("Invalid file format: expected {expected}, got {actual}")]
+  InvalidFormat { expected: String, actual: String },
+
+  #[error("Network error: {0}")]
+  Network(String),
+
+  #[error(transparent)]
+  Io(#[from] std::io::Error),
+}
+
+// ✅ Serialize 구현으로 JSON 변환
+impl Serialize for AppError {
+  fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+  where
+    S: Serializer,
+  {
+    use serde::ser::SerializeStruct;
+
+    let mut state = serializer.serialize_struct("AppError", 2)?;
+
+    // 에러 코드
+    let code = match self {
+      AppError::FileNotFound { .. } => "FILE_NOT_FOUND",
+      AppError::PermissionDenied { .. } => "PERMISSION_DENIED",
+      AppError::InvalidFormat { .. } => "INVALID_FORMAT",
+      AppError::Network(_) => "NETWORK_ERROR",
+      AppError::Io(_) => "IO_ERROR",
+    };
+    state.serialize_field("code", code)?;
+
+    // 에러 메시지
+    state.serialize_field("message", &self.to_string())?;
+
+    state.end()
+  }
+}
+```
+
+### 3. 커맨드에서 사용
+
+```rust
+#[tauri::command]
+fn read_file(path: String) -> Result<String, AppError> {
+  // 자동 변환: std::io::Error -> AppError::Io
+  let content = std::fs::read_to_string(&path)?;
+  Ok(content)
+}
+
+#[tauri::command]
+fn process_config(path: String) -> Result<Config, AppError> {
+  let content = std::fs::read_to_string(&path)
+    .map_err(|_| AppError::FileNotFound { path: path.clone() })?;
+
+  if !content.starts_with('[') {
+    return Err(AppError::InvalidFormat {
+      expected: "JSON".to_string(),
+      actual: "Plain text".to_string(),
+    });
+  }
+
+  // 파싱 로직...
+  Ok(Config::default())
+}
+```
+
+### 4. 프론트엔드에서 에러 처리
+
+```typescript
+// ✅ 에러 타입 정의
+interface AppError {
+  code: string;
+  message: string;
+}
+
+// ✅ 에러 코드 기반 처리
+async function loadFile(path: string) {
+  try {
+    const content = await invoke<string>('read_file', { path });
+    return content;
+  } catch (err) {
+    const error = err as AppError;
+
+    switch (error.code) {
+      case 'FILE_NOT_FOUND':
+        toast.error('파일을 찾을 수 없습니다');
+        break;
+      case 'PERMISSION_DENIED':
+        toast.error('파일 접근 권한이 없습니다');
+        break;
+      case 'INVALID_FORMAT':
+        toast.error(`잘못된 파일 형식: ${error.message}`);
+        break;
+      default:
+        toast.error(`오류: ${error.message}`);
+    }
+
+    // 로깅
+    console.error(`[${error.code}] ${error.message}`);
+  }
+}
+```
+
+## 고급 패턴: 에러 컨텍스트
+
+**anyhow로 에러 체인:**
+
+```rust
+use anyhow::{Context, Result};
+
+#[tauri::command]
+fn load_config(path: String) -> Result<Config, String> {
+  let content = std::fs::read_to_string(&path)
+    .context(format!("Failed to read config from {}", path))?;
+
+  let config: Config = serde_json::from_str(&content)
+    .context("Failed to parse JSON config")?;
+
+  Ok(config)
+}
+// 에러 메시지: "Failed to parse JSON config: unexpected character at line 5"
+```
+
+**tauri-specta와 통합:**
+
+```rust
+use specta::Type;
+
+#[derive(Debug, Error, Type)]
+#[serde(tag = "type", content = "data")]
+enum AppError {
+  #[error("File not found")]
+  FileNotFound { path: String },
+
+  #[error("Permission denied")]
+  PermissionDenied,
+}
+
+// TypeScript에서 자동 생성:
+// type AppError =
+//   | { type: "FileNotFound", data: { path: string } }
+//   | { type: "PermissionDenied" }
+```
+
+## 추가 컨텍스트
+
+**언제 구조화된 에러를 사용해야 하는가:**
+- 에러 종류가 2개 이상
+- 프론트엔드에서 에러별 처리 필요
+- 디버깅 정보 제공 필요
+- 에러 로깅/모니터링 시스템 연동
+
+**에러 설계 원칙:**
+- 에러 코드는 대문자 스네이크 케이스 (`FILE_NOT_FOUND`)
+- 메시지는 사용자 친화적으로
+- 민감 정보 (경로, 비밀번호 등) 제외
+- 복구 가능한 에러만 반환 (패닉 금지)
+
+**주의사항:**
+- `#[error(transparent)]`로 다른 에러 타입 자동 변환
+- `Serialize` 구현 시 순환 참조 주의
+- 에러 메시지는 국제화(i18n) 고려
+
+**참고:**
+- [thiserror Documentation](https://docs.rs/thiserror/)
+- [Rust Error Handling](https://doc.rust-lang.org/book/ch09-00-error-handling.html)
+- [anyhow for Application Errors](https://docs.rs/anyhow/)