@choblue/claude-code-toolkit 1.1.0 → 1.1.2

package/.claude/skills/TypeScript/references/type-guards.md

@@ -0,0 +1,109 @@
+# 타입 가드 (Type Guards)
+
+이 문서는 TypeScript 타입 가드의 상세 패턴을 다룬다.
+기본 규칙은 [SKILL.md](../SKILL.md)를 참고한다.
+
+---
+
+## is 키워드 (사용자 정의 타입 가드)
+
+```typescript
+interface Admin {
+  role: 'admin';
+  permissions: string[];
+}
+
+interface Guest {
+  role: 'guest';
+}
+
+type AppUser = Admin | Guest;
+
+// Bad - 타입 단언
+function getPermissions(user: AppUser): string[] {
+  return (user as Admin).permissions ?? [];
+}
+
+// Good - 타입 가드
+function isAdmin(user: AppUser): user is Admin {
+  return user.role === 'admin';
+}
+
+function getPermissions(user: AppUser): string[] {
+  if (isAdmin(user)) {
+    return user.permissions; // Admin으로 좁혀짐
+  }
+  return [];
+}
+```
+
+---
+
+## in 연산자
+
+```typescript
+interface Dog {
+  bark: () => void;
+}
+
+interface Cat {
+  meow: () => void;
+}
+
+type Pet = Dog | Cat;
+
+function makeSound(pet: Pet): void {
+  if ('bark' in pet) {
+    pet.bark(); // Dog으로 좁혀짐
+  } else {
+    pet.meow(); // Cat으로 좁혀짐
+  }
+}
+```
+
+---
+
+## Discriminated Union (태그드 유니언)
+
+```typescript
+// 공통 판별 필드(type)를 가진 유니언
+type Shape =
+  | { type: 'circle'; radius: number }
+  | { type: 'rectangle'; width: number; height: number }
+  | { type: 'triangle'; base: number; height: number };
+
+function calculateArea(shape: Shape): number {
+  switch (shape.type) {
+    case 'circle':
+      return Math.PI * shape.radius ** 2;
+    case 'rectangle':
+      return shape.width * shape.height;
+    case 'triangle':
+      return (shape.base * shape.height) / 2;
+  }
+}
+```
+
+---
+
+## Exhaustive Check (never를 이용한 완전성 검사)
+
+```typescript
+// 모든 케이스를 처리했는지 컴파일 타임에 검증한다
+function assertNever(value: never): never {
+  throw new Error(`Unexpected value: ${value}`);
+}
+
+function getShapeLabel(shape: Shape): string {
+  switch (shape.type) {
+    case 'circle':
+      return '원';
+    case 'rectangle':
+      return '직사각형';
+    case 'triangle':
+      return '삼각형';
+    default:
+      return assertNever(shape); // 새로운 Shape 추가 시 컴파일 에러 발생
+  }
+}
+```

package/.claude/skills/Zustand/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: zustand
+description: Zustand 클라이언트 상태 관리 가이드. 스토어 설계, Selector 패턴, 미들웨어(persist, devtools, immer), Slice 패턴 등 클라이언트 상태 관리 시 참조한다.
+---
+
 # Zustand Skill - 클라이언트 상태 관리 규칙
 
 Zustand를 사용한 클라이언트 상태 관리 규칙을 정의한다.

package/install.sh

@@ -1,17 +1,18 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # install.sh - my-claude-code-toolkit을 .claude/에 설치한다
-# Usage: ./install.sh [--global] [--fe] [--be]
+# Usage: ./install.sh [--global] [--fe] [--be] [--force]
 #   기본값: 현재 디렉토리의 .claude/에 전체 설치 (프로젝트 로컬)
 #   --global: ~/.claude/에 설치 (글로벌)
 #   --fe: 공통 + 프론트엔드 스킬만 설치
 #   --be: 공통 + 백엔드 스킬만 설치
 #   --fe --be: 전체 설치 (= 기본값)
+#   --force: 사용자 수정 파일도 강제 덮어쓰기
 
 set -e
 
 # 도움말 출력
 usage() {
-  echo "Usage: $0 [--global] [--fe] [--be]"
+  echo "Usage: $0 [--global] [--fe] [--be] [--force]"
   echo ""
   echo "스택 선택:"
   echo "  (기본값)       전체 설치 (공통 + FE + BE)"
@@ -23,11 +24,15 @@ usage() {
   echo "  (기본값)       현재 디렉토리의 .claude/에 설치 (프로젝트 로컬)"
   echo "  --global       ~/.claude/에 설치 (글로벌)"
   echo ""
+  echo "옵션:"
+  echo "  --force        사용자 수정 파일도 강제 덮어쓰기"
+  echo ""
   echo "예시:"
   echo "  $0                    # 전체 설치 (로컬)"
   echo "  $0 --fe               # 공통 + FE만 (로컬)"
   echo "  $0 --be               # 공통 + BE만 (로컬)"
   echo "  $0 --global --fe      # 공통 + FE만 (글로벌)"
+  echo "  $0 --force            # 수정된 파일도 강제 덮어쓰기"
   exit 0
 }
 
@@ -35,6 +40,7 @@ usage() {
 INSTALL_MODE="local"
 INSTALL_FE=false
 INSTALL_BE=false
+FORCE_OVERWRITE=false
 
 for arg in "$@"; do
   case "$arg" in
@@ -47,6 +53,9 @@ for arg in "$@"; do
     --be)
       INSTALL_BE=true
       ;;
+    --force)
+      FORCE_OVERWRITE=true
+      ;;
     --help|-h)
       usage
       ;;
@@ -81,11 +90,9 @@ fi
 
 if [ "$INSTALL_MODE" = "global" ]; then
   TARGET_DIR="$HOME/.claude"
-  BACKUP_DIR="$HOME/.claude-backup-$(date +%Y%m%d_%H%M%S)"
   MODE_LABEL="글로벌 설치 (~/.claude/)"
 else
   TARGET_DIR="$(pwd)/.claude"
-  BACKUP_DIR="$(pwd)/.claude-backup-$(date +%Y%m%d_%H%M%S)"
   MODE_LABEL="로컬 설치 ($(pwd)/.claude/)"
 fi
 
@@ -103,52 +110,112 @@ if [ ! -d "$SOURCE_DIR" ]; then
   exit 1
 fi
 
-# 기존 파일 백업
-if [ -d "$TARGET_DIR" ]; then
-  # 백업할 파일이 있는지 확인 (agents, skills, hooks, CLAUDE.md, settings.json)
-  HAS_EXISTING=false
-  for item in CLAUDE.md settings.json agents skills hooks; do
-    if [ -e "$TARGET_DIR/$item" ]; then
-      HAS_EXISTING=true
-      break
-    fi
-  done
+# TARGET_DIR 생성
+mkdir -p "$TARGET_DIR"
+
+# === 해시 함수 ===
+file_hash() {
+  if command -v shasum &>/dev/null; then
+    shasum -a 256 "$1" | cut -d' ' -f1
+  elif command -v sha256sum &>/dev/null; then
+    sha256sum "$1" | cut -d' ' -f1
+  else
+    # fallback: md5
+    md5 -q "$1" 2>/dev/null || md5sum "$1" | cut -d' ' -f1
+  fi
+}
 
-  if [ "$HAS_EXISTING" = true ]; then
-    echo "기존 설정 파일이 발견되었습니다. 백업합니다..."
-    mkdir -p "$BACKUP_DIR"
-    for item in CLAUDE.md settings.json agents skills hooks; do
-      if [ -e "$TARGET_DIR/$item" ]; then
-        cp -r "$TARGET_DIR/$item" "$BACKUP_DIR/"
-        echo "  백업: $item → $BACKUP_DIR/$item"
-      fi
-    done
-    echo ""
-    echo "백업 완료: $BACKUP_DIR"
+# === 매니페스트 관리 ===
+MANIFEST_FILE="$TARGET_DIR/.toolkit-manifest"
+NEW_MANIFEST=""
+
+# 이전 매니페스트 로드 (grep 기반으로 bash 3.x 호환)
+# OLD_MANIFEST_CONTENT: 한 줄에 "<sha256hash> <relative_path>" 형식
+OLD_MANIFEST_CONTENT=""
+if [ -f "$MANIFEST_FILE" ]; then
+  OLD_MANIFEST_CONTENT="$(cat "$MANIFEST_FILE")"
+fi
+
+# 이전 매니페스트에서 특정 파일의 해시를 조회
+old_manifest_hash() {
+  local path="$1"
+  if [ -z "$OLD_MANIFEST_CONTENT" ]; then
     echo ""
+    return
   fi
-else
-  mkdir -p "$TARGET_DIR"
-fi
+  echo "$OLD_MANIFEST_CONTENT" | grep " ${path}$" | head -1 | cut -d' ' -f1
+}
 
 # === 헬퍼 함수 ===
 
-# 개별 파일 복사 (상대경로 기준)
+# 개별 파일 복사 (상대경로 기준, 매니페스트 체크섬 비교)
 copy_file() {
   local rel_path="$1"
   local dir
   dir="$(dirname "$rel_path")"
   mkdir -p "$TARGET_DIR/$dir"
-  cp "$SOURCE_DIR/$rel_path" "$TARGET_DIR/$rel_path"
-  echo "  복사: $rel_path"
+
+  local target_file="$TARGET_DIR/$rel_path"
+  local source_file="$SOURCE_DIR/$rel_path"
+
+  if [ -f "$target_file" ]; then
+    local old_hash
+    old_hash="$(old_manifest_hash "$rel_path")"
+
+    if [ -n "$old_hash" ]; then
+      # 매니페스트에 기록이 있음 → 사용자 수정 여부 확인
+      local current_hash
+      current_hash="$(file_hash "$target_file")"
+
+      if [ "$current_hash" = "$old_hash" ]; then
+        # 사용자가 수정하지 않음 → 새 버전으로 덮어씀
+        cp "$source_file" "$target_file"
+        echo "  복사: $rel_path"
+      else
+        # 사용자가 수정함
+        if [ "$FORCE_OVERWRITE" = true ]; then
+          cp "$target_file" "$target_file.bak"
+          cp "$source_file" "$target_file"
+          echo "  ⚠️  $rel_path - 사용자 수정 감지, 강제 덮어씀"
+        else
+          echo "  ⚠️  $rel_path - 사용자 수정 감지, 건너뜀 (강제: --force)"
+          # 건너뛴 파일도 매니페스트에는 현재 해시로 기록 (추적 유지)
+          NEW_MANIFEST="${NEW_MANIFEST}${current_hash} ${rel_path}"$'\n'
+          return
+        fi
+      fi
+    else
+      # 매니페스트에 기록 없음 (첫 설치 or 매니페스트 없음) → 그냥 복사
+      cp "$source_file" "$target_file"
+      echo "  복사: $rel_path"
+    fi
+  else
+    # 대상 파일이 존재하지 않음 → 그냥 복사
+    cp "$source_file" "$target_file"
+    echo "  복사: $rel_path"
+  fi
+
+  # 복사 성공한 파일의 해시를 새 매니페스트에 추가
+  local new_hash
+  new_hash="$(file_hash "$target_file")"
+  NEW_MANIFEST="${NEW_MANIFEST}${new_hash} ${rel_path}"$'\n'
 }
 
-# 디렉토리 전체 복사 (상대경로 기준)
+# 디렉토리 전체 복사 (개별 파일 단위로 처리하여 매니페스트에 기록)
 copy_dir() {
   local rel_path="$1"
-  mkdir -p "$TARGET_DIR/$rel_path"
-  cp -r "$SOURCE_DIR/$rel_path/"* "$TARGET_DIR/$rel_path/"
-  echo "  복사: $rel_path/"
+  local file
+  for file in "$SOURCE_DIR/$rel_path/"*; do
+    if [ -f "$file" ]; then
+      local filename
+      filename="$(basename "$file")"
+      copy_file "$rel_path/$filename"
+    elif [ -d "$file" ]; then
+      local dirname
+      dirname="$(basename "$file")"
+      copy_dir "$rel_path/$dirname"
+    fi
+  done
 }
 
 # === 복사 함수 ===
@@ -234,6 +301,25 @@ if [ "$INSTALL_BE" = true ]; then
   echo ""
 fi
 
+# === 오래된 파일 정리 ===
+# 이전 매니페스트에는 있지만 새 매니페스트에는 없는 파일 삭제
+if [ -n "$OLD_MANIFEST_CONTENT" ]; then
+  while IFS=' ' read -r old_hash old_path; do
+    [ -z "$old_path" ] && continue
+    # 새 매니페스트에 해당 경로가 없으면 삭제
+    if ! echo "$NEW_MANIFEST" | grep -q " ${old_path}$"; then
+      if [ -f "$TARGET_DIR/$old_path" ]; then
+        rm "$TARGET_DIR/$old_path"
+        echo "  🗑️  $old_path - 더 이상 사용하지 않는 파일 삭제"
+      fi
+    fi
+  done <<< "$OLD_MANIFEST_CONTENT"
+  echo ""
+fi
+
+# === 새 매니페스트 작성 ===
+printf '%s' "$NEW_MANIFEST" > "$MANIFEST_FILE"
+
 echo "=== 설치 완료 ($MODE_LABEL) ==="
 echo ""
 echo "스택: $STACK_LABEL"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@choblue/claude-code-toolkit",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Claude Code 서브에이전트 위임 툴킷 - npx로 바로 설치",
   "bin": {
     "claude-code-toolkit": "bin/cli.js"