@kood/claude-code 0.6.6 → 0.7.0

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

@@ -0,0 +1,239 @@
+# invoke 실패에 대한 ErrorBoundary 처리
+
+## 왜 중요한가
+
+Tauri Command 호출은 Rust panic, 권한 거부, 타입 불일치 등 다양한 이유로 실패할 수 있습니다. ErrorBoundary 없이는 전체 앱이 크래시되거나 사용자에게 불친절한 에러 메시지가 노출됩니다.
+
+## ❌ 잘못된 패턴
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useEffect, useState } from 'react'
+
+function DataViewer() {
+  const [data, setData] = useState(null)
+
+  useEffect(() => {
+    // ❌ 에러 처리 없음, 실패 시 앱 크래시
+    invoke('fetch_data').then(setData)
+  }, [])
+
+  // data가 null이면 렌더링 에러 발생 가능
+  return <div>{data.items.map(...)}</div>
+}
+```
+
+**문제점:**
+- try/catch 없는 invoke 호출
+- 에러 상태 관리 없음
+- 사용자에게 피드백 없음
+
+## ✅ 올바른 패턴
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useEffect, useState } from 'react'
+import { ErrorBoundary } from 'react-error-boundary'
+
+function DataViewer() {
+  const [data, setData] = useState<DataType | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    invoke<DataType>('fetch_data')
+      .then(setData)
+      .catch(err => setError(err))
+      .finally(() => setLoading(false))
+  }, [])
+
+  if (loading) return <div>Loading...</div>
+  if (error) throw error // ErrorBoundary로 전파
+  if (!data) return <div>No data</div>
+
+  return (
+    <div>
+      {data.items.map(item => (
+        <div key={item.id}>{item.name}</div>
+      ))}
+    </div>
+  )
+}
+
+function App() {
+  return (
+    <ErrorBoundary
+      fallback={<ErrorFallback />}
+      onError={(error, errorInfo) => {
+        console.error('Caught by ErrorBoundary:', error, errorInfo)
+      }}
+    >
+      <DataViewer />
+    </ErrorBoundary>
+  )
+}
+
+function ErrorFallback({ error, resetErrorBoundary }: {
+  error: Error
+  resetErrorBoundary: () => void
+}) {
+  return (
+    <div role="alert">
+      <h2>Something went wrong</h2>
+      <pre>{error.message}</pre>
+      <button onClick={resetErrorBoundary}>Try again</button>
+    </div>
+  )
+}
+```
+
+**Tauri 특화 에러 타입 처리:**
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+
+type TauriError = {
+  message: string
+  kind?: 'PermissionDenied' | 'NotFound' | 'InvalidData' | 'Unknown'
+}
+
+function parseTauriError(error: unknown): TauriError {
+  if (typeof error === 'string') {
+    // Rust에서 String 에러
+    return { message: error, kind: 'Unknown' }
+  }
+
+  if (error instanceof Error) {
+    // JS Error 객체
+    const message = error.message
+
+    if (message.includes('permission denied')) {
+      return { message, kind: 'PermissionDenied' }
+    }
+    if (message.includes('not found')) {
+      return { message, kind: 'NotFound' }
+    }
+    if (message.includes('invalid')) {
+      return { message, kind: 'InvalidData' }
+    }
+
+    return { message, kind: 'Unknown' }
+  }
+
+  return { message: 'Unknown error', kind: 'Unknown' }
+}
+
+function DataViewer() {
+  const [error, setError] = useState<TauriError | null>(null)
+
+  useEffect(() => {
+    invoke('fetch_data')
+      .then(setData)
+      .catch(err => setError(parseTauriError(err)))
+  }, [])
+
+  if (error) {
+    if (error.kind === 'PermissionDenied') {
+      return <div>권한이 필요합니다. 설정에서 권한을 허용해주세요.</div>
+    }
+    if (error.kind === 'NotFound') {
+      return <div>데이터를 찾을 수 없습니다.</div>
+    }
+    return <div>오류: {error.message}</div>
+  }
+
+  return <div>{/* ... */}</div>
+}
+```
+
+**재시도 로직:**
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useState, useCallback } from 'react'
+
+function useInvokeWithRetry<T>(
+  command: string,
+  args?: Record<string, unknown>,
+  maxRetries = 3
+) {
+  const [data, setData] = useState<T | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [retries, setRetries] = useState(0)
+
+  const execute = useCallback(async () => {
+    setLoading(true)
+    setError(null)
+
+    for (let i = 0; i <= maxRetries; i++) {
+      try {
+        const result = await invoke<T>(command, args)
+        setData(result)
+        setRetries(i)
+        return
+      } catch (err) {
+        if (i === maxRetries) {
+          setError(err as Error)
+          setRetries(i)
+        } else {
+          await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)))
+        }
+      }
+    }
+
+    setLoading(false)
+  }, [command, args, maxRetries])
+
+  return { data, error, loading, retries, execute }
+}
+
+// 사용 예시
+function DataViewer() {
+  const { data, error, loading, retries, execute } = useInvokeWithRetry<Data>(
+    'fetch_data'
+  )
+
+  useEffect(() => {
+    execute()
+  }, [execute])
+
+  if (loading) return <div>Loading... (Attempt {retries + 1})</div>
+  if (error) return <div>Failed after {retries} retries: {error.message}</div>
+  return <div>{data && JSON.stringify(data)}</div>
+}
+```
+
+## 추가 컨텍스트
+
+**ErrorBoundary 라이브러리:**
+- [react-error-boundary](https://github.com/bvaughn/react-error-boundary): 가장 인기
+- React 19+ 내장 ErrorBoundary (계획 중)
+
+**Rust 에러를 사용자 친화적으로 변환:**
+
+```rust
+// Rust 측에서 에러 메시지 커스터마이징
+#[tauri::command]
+fn fetch_data() -> Result<Data, String> {
+    match load_data() {
+        Ok(data) => Ok(data),
+        Err(_) => Err("데이터를 불러올 수 없습니다. 나중에 다시 시도해주세요.".to_string())
+    }
+}
+```
+
+**전역 에러 처리:**
+```tsx
+function App() {
+  return (
+    <ErrorBoundary fallback={<GlobalError />}>
+      <Router />
+    </ErrorBoundary>
+  )
+}
+```
+
+**참고:** [Error Handling in Tauri](https://beta.tauri.app/develop/calling-rust/#error-handling)
+
+영향도: HIGH - 사용자 경험, 앱 안정성, 에러 복구 가능성

package/templates/.claude/skills/tauri-react-best-practices/rules/react-event-listener.md

@@ -0,0 +1,151 @@
+# listen/unlisten 라이프사이클 관리
+
+## 왜 중요한가
+
+Tauri의 이벤트 리스너는 수동으로 등록 해제하지 않으면 메모리에 남아 누수를 일으킵니다. 컴포넌트가 여러 번 마운트/언마운트되는 경우 리스너가 중복 등록되어 동일 이벤트에 여러 핸들러가 실행될 수 있습니다.
+
+## ❌ 잘못된 패턴
+
+```tsx
+import { listen } from '@tauri-apps/api/event'
+import { useEffect, useState } from 'react'
+
+function NotificationPanel() {
+  const [messages, setMessages] = useState<string[]>([])
+
+  useEffect(() => {
+    // ❌ unlisten 호출 없음 (메모리 누수)
+    listen<string>('notification', event => {
+      setMessages(prev => [...prev, event.payload])
+    })
+  }, [])
+
+  return (
+    <div>
+      {messages.map((msg, i) => <div key={i}>{msg}</div>)}
+    </div>
+  )
+}
+```
+
+**문제점:**
+- cleanup에서 unlisten 호출 안 함 (리스너 계속 활성 상태)
+- 컴포넌트 재마운트 시 리스너 중복 등록
+- 언마운트된 컴포넌트에서 setState 호출 위험
+
+## ✅ 올바른 패턴
+
+```tsx
+import { listen, UnlistenFn } from '@tauri-apps/api/event'
+import { useEffect, useState } from 'react'
+
+function NotificationPanel() {
+  const [messages, setMessages] = useState<string[]>([])
+
+  useEffect(() => {
+    let unlisten: UnlistenFn | undefined
+
+    listen<string>('notification', event => {
+      setMessages(prev => [...prev, event.payload])
+    }).then(unlistenFn => {
+      unlisten = unlistenFn
+    })
+
+    return () => {
+      unlisten?.()
+    }
+  }, [])
+
+  return (
+    <div>
+      {messages.map((msg, i) => <div key={i}>{msg}</div>)}
+    </div>
+  )
+}
+```
+
+**once() 패턴 (일회성 이벤트):**
+
+```tsx
+import { once } from '@tauri-apps/api/event'
+
+function WelcomeScreen() {
+  const [ready, setReady] = useState(false)
+
+  useEffect(() => {
+    let unlisten: UnlistenFn | undefined
+
+    once<void>('app-ready', () => {
+      setReady(true)
+    }).then(unlistenFn => {
+      unlisten = unlistenFn
+    })
+
+    return () => unlisten?.()
+  }, [])
+
+  return ready ? <MainApp /> : <SplashScreen />
+}
+```
+
+**커스텀 hook 패턴:**
+
+```tsx
+import { listen, Event, UnlistenFn } from '@tauri-apps/api/event'
+import { useEffect, useState } from 'react'
+
+function useEvent<T>(
+  eventName: string,
+  handler: (event: Event<T>) => void
+) {
+  useEffect(() => {
+    let unlisten: UnlistenFn | undefined
+
+    listen<T>(eventName, handler).then(unlistenFn => {
+      unlisten = unlistenFn
+    })
+
+    return () => unlisten?.()
+  }, [eventName, handler])
+}
+
+// 사용 예시
+function StatusBar() {
+  const [status, setStatus] = useState('idle')
+
+  useEvent<string>('status-update', event => {
+    setStatus(event.payload)
+  })
+
+  return <div>Status: {status}</div>
+}
+```
+
+## 추가 컨텍스트
+
+**cleanup 타이밍:**
+- useEffect return 함수는 언마운트 시 또는 의존성 변경 시 실행
+- 리스너는 항상 cleanup에서 제거해야 메모리 누수 방지
+
+**글로벌 이벤트 vs 로컬 이벤트:**
+- `listen()`: 모든 윈도우에서 수신
+- `emit()`: 현재 윈도우로 전송
+- `once()`: 한 번만 실행 후 자동 제거
+
+**타입 안정성:**
+```tsx
+type NotificationPayload = {
+  title: string
+  body: string
+  level: 'info' | 'warning' | 'error'
+}
+
+listen<NotificationPayload>('notification', event => {
+  // event.payload는 타입 안전하게 추론됨
+  console.log(event.payload.title)
+})
+```
+
+**참고:** [Tauri Events Guide](https://beta.tauri.app/develop/calling-rust/#events)
+
+영향도: HIGH - 메모리 누수, 중복 핸들러 실행 방지

package/templates/.claude/skills/tauri-react-best-practices/rules/react-file-src.md

@@ -0,0 +1,155 @@
+# convertFileSrc()로 로컬 파일 렌더링
+
+## 왜 중요한가
+
+Tauri 앱에서 로컬 파일을 브라우저에서 렌더링하려면 `asset:` 프로토콜 URL로 변환해야 합니다. 직접 파일 경로를 사용하면 CORS 에러가 발생하고, base64 변환은 메모리 낭비와 성능 저하를 일으킵니다.
+
+## ❌ 잘못된 패턴
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useState, useEffect } from 'react'
+
+function ImageViewer({ filePath }: { filePath: string }) {
+  const [imageData, setImageData] = useState('')
+
+  useEffect(() => {
+    // ❌ 파일을 base64로 읽어서 메모리에 전체 로드
+    invoke<string>('read_file_as_base64', { path: filePath })
+      .then(base64 => setImageData(`data:image/png;base64,${base64}`))
+  }, [filePath])
+
+  return <img src={imageData} alt="Local file" />
+}
+```
+
+**문제점:**
+- 파일 전체를 메모리에 로드 (큰 파일 시 느림)
+- Rust ↔ JS 직렬화 오버헤드
+- 비디오/오디오 스트리밍 불가능
+
+## ✅ 올바른 패턴
+
+```tsx
+import { convertFileSrc } from '@tauri-apps/api/core'
+
+function ImageViewer({ filePath }: { filePath: string }) {
+  // ✅ 파일 경로를 asset: 프로토콜 URL로 변환
+  const assetUrl = convertFileSrc(filePath)
+
+  return <img src={assetUrl} alt="Local file" />
+}
+```
+
+**비디오/오디오 예시:**
+
+```tsx
+import { convertFileSrc } from '@tauri-apps/api/core'
+
+function VideoPlayer({ videoPath }: { videoPath: string }) {
+  const videoUrl = convertFileSrc(videoPath)
+
+  return (
+    <video controls>
+      <source src={videoUrl} type="video/mp4" />
+      Your browser does not support video playback.
+    </video>
+  )
+}
+
+function AudioPlayer({ audioPath }: { audioPath: string }) {
+  const audioUrl = convertFileSrc(audioPath)
+
+  return (
+    <audio controls>
+      <source src={audioUrl} type="audio/mpeg" />
+    </audio>
+  )
+}
+```
+
+**PDF 뷰어 예시:**
+
+```tsx
+import { convertFileSrc } from '@tauri-apps/api/core'
+
+function PDFViewer({ pdfPath }: { pdfPath: string }) {
+  const pdfUrl = convertFileSrc(pdfPath)
+
+  return (
+    <iframe
+      src={pdfUrl}
+      width="100%"
+      height="600px"
+      title="PDF Viewer"
+    />
+  )
+}
+```
+
+**동적 파일 목록:**
+
+```tsx
+import { convertFileSrc } from '@tauri-apps/api/core'
+import { readDir } from '@tauri-apps/plugin-fs'
+import { useEffect, useState } from 'react'
+
+function ImageGallery({ dirPath }: { dirPath: string }) {
+  const [images, setImages] = useState<string[]>([])
+
+  useEffect(() => {
+    readDir(dirPath).then(entries => {
+      const imageUrls = entries
+        .filter(e => /\.(png|jpg|jpeg|gif)$/i.test(e.name))
+        .map(e => convertFileSrc(e.path))
+      setImages(imageUrls)
+    })
+  }, [dirPath])
+
+  return (
+    <div className="gallery">
+      {images.map((url, i) => (
+        <img key={i} src={url} alt={`Image ${i}`} />
+      ))}
+    </div>
+  )
+}
+```
+
+## 추가 컨텍스트
+
+**asset: 프로토콜 작동 방식:**
+- `convertFileSrc('/path/to/file.png')` → `asset://localhost/path/to/file.png`
+- Tauri 런타임이 프로토콜 요청을 가로채서 파일 스트림 제공
+- 브라우저는 일반 HTTP 리소스처럼 처리 (캐싱, 부분 로드 지원)
+
+**권한 설정 (tauri.conf.json):**
+
+```json
+{
+  "app": {
+    "security": {
+      "assetProtocol": {
+        "enable": true,
+        "scope": [
+          "$APPDATA/**",
+          "$RESOURCE/**"
+        ]
+      }
+    }
+  }
+}
+```
+
+**파일 경로 타입:**
+- 절대 경로: `/Users/name/file.png`, `C:\Users\name\file.png`
+- 앱 리소스 경로: `$RESOURCE/assets/image.png`
+- AppData 경로: `$APPDATA/cache/thumb.png`
+
+**브라우저 캐싱:**
+- asset: URL은 브라우저 캐시 활용 (동일 파일 재요청 방지)
+- base64 Data URL은 캐싱 불가
+
+**참고:** [Asset Protocol Scope](https://beta.tauri.app/develop/calling-rust/#asset-protocol-scope)
+
+영향도: HIGH - 성능, 메모리 사용량, 스트리밍 지원

package/templates/.claude/skills/tauri-react-best-practices/rules/react-invoke-hook.md

@@ -0,0 +1,139 @@
+# useEffect + invoke 패턴으로 Tauri Command 호출
+
+## 왜 중요한가
+
+Tauri의 `invoke()` 호출은 비동기 IPC이므로 React 컴포넌트 라이프사이클과 통합 시 cleanup이 필수입니다. 컴포넌트 언마운트 후 응답이 도착하면 "Can't perform state update on unmounted component" 경고와 메모리 누수가 발생합니다.
+
+## ❌ 잘못된 패턴
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useState } from 'react'
+
+function UserProfile({ userId }: { userId: string }) {
+  const [user, setUser] = useState(null)
+
+  // ❌ cleanup 없음, 언마운트 후 setState 위험
+  invoke('get_user', { userId })
+    .then(setUser)
+    .catch(console.error)
+
+  return user ? <div>{user.name}</div> : <div>Loading...</div>
+}
+```
+
+**문제점:**
+- useEffect 없이 invoke 호출 (매 렌더링마다 실행)
+- cleanup 로직 없음 (언마운트 후 setState)
+- 에러 처리 불충분
+
+## ✅ 올바른 패턴
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useEffect, useState } from 'react'
+
+function UserProfile({ userId }: { userId: string }) {
+  const [user, setUser] = useState<User | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    let cancelled = false
+
+    setLoading(true)
+    setError(null)
+
+    invoke<User>('get_user', { userId })
+      .then(data => {
+        if (!cancelled) setUser(data)
+      })
+      .catch(err => {
+        if (!cancelled) setError(err.message)
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [userId])
+
+  if (loading) return <div>Loading...</div>
+  if (error) return <div>Error: {error}</div>
+  return user ? <div>{user.name}</div> : null
+}
+```
+
+**개선된 커스텀 hook 패턴:**
+
+```tsx
+import { invoke } from '@tauri-apps/api/core'
+import { useEffect, useState } from 'react'
+
+function useInvoke<T>(
+  command: string,
+  args?: Record<string, unknown>
+) {
+  const [data, setData] = useState<T | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    let cancelled = false
+
+    setLoading(true)
+    setError(null)
+
+    invoke<T>(command, args)
+      .then(result => !cancelled && setData(result))
+      .catch(err => !cancelled && setError(err))
+      .finally(() => !cancelled && setLoading(false))
+
+    return () => {
+      cancelled = true
+    }
+  }, [command, JSON.stringify(args)])
+
+  return { data, error, loading }
+}
+
+// 사용 예시
+function UserProfile({ userId }: { userId: string }) {
+  const { data: user, error, loading } = useInvoke<User>(
+    'get_user',
+    { userId }
+  )
+
+  if (loading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+  return user ? <div>{user.name}</div> : null
+}
+```
+
+## 추가 컨텍스트
+
+**AbortController 패턴 (Tauri v2.1+):**
+
+```tsx
+useEffect(() => {
+  const controller = new AbortController()
+
+  invoke('long_running_task', { signal: controller.signal })
+    .then(setResult)
+    .catch(err => {
+      if (err.name !== 'AbortError') setError(err)
+    })
+
+  return () => controller.abort()
+}, [])
+```
+
+**권장 의존성 관리:**
+- 원시 값 (`userId`, `query`): 직접 의존성 배열에 추가
+- 객체/배열 args: `JSON.stringify(args)` 또는 `useMemo`로 안정화
+
+**참고:** TanStack Query와 함께 사용 시 `queryFn`에서 invoke 호출하면 자동 cleanup 제공.
+
+영향도: HIGH - 메모리 누수, 상태 버그, 콘솔 경고 방지