@juho0719/cckit 0.2.4 → 0.2.6

package/assets/skills/plan-viewer/visual-guide.md

@@ -0,0 +1,234 @@
+# Visual Guide — Plan Viewer
+
+브라우저 기반 비주얼 뷰어 상세 가이드. 아키텍처 다이어그램, 플로우차트, 레이아웃 비교 등 시각 자료를 보여줄 때 참조한다.
+
+## 동작 원리
+
+서버가 `.plan-viewer/sessions/<session-id>` 디렉터리를 감시하고, 가장 최신 HTML 파일을 브라우저에 서빙한다. HTML 파일을 작성하면 사용자 브라우저에 자동 반영되고, 사용자의 클릭 이벤트는 `.events` 파일에 기록된다.
+
+**콘텐츠 프래그먼트 vs 풀 도큐먼트:** HTML 파일이 `<!DOCTYPE` 또는 `<html`로 시작하면 그대로 서빙한다. 그렇지 않으면 프레임 템플릿으로 자동 래핑한다. **기본적으로 콘텐츠 프래그먼트만 작성한다.**
+
+## 서버 시작
+
+```bash
+# 프로젝트 디렉터리에 영구 저장
+scripts/start-server.sh --project-dir /path/to/project
+
+# 반환 JSON:
+# {"type":"server-started","port":52341,"url":"http://localhost:52341",
+#  "screen_dir":"/path/to/project/.plan-viewer/sessions/12345-1706000000"}
+```
+
+`screen_dir`을 저장한다. 사용자에게 URL을 알려준다.
+
+## 루프
+
+1. **서버 활성 확인 후 HTML 작성** — `screen_dir`에 새 파일 작성
+   - 매번 `$SCREEN_DIR/.server-info` 존재 확인. 없으면 (또는 `.server-stopped` 있으면) 서버 재시작
+   - 시맨틱 파일명 사용: `architecture.html`, `data-flow.html`, `comparison.html`
+   - **파일명 재사용 금지** — 매 화면마다 새 파일
+   - Write 도구 사용 — cat/heredoc 금지
+   - 서버가 자동으로 최신 파일을 서빙
+
+2. **사용자에게 안내하고 턴 종료:**
+   - URL을 매번 상기 (첫 번째뿐 아니라 매번)
+   - 화면 내용을 간략히 텍스트로 요약
+   - 예: "3가지 아키텍처 접근안을 브라우저에서 확인하세요. 선호하는 옵션을 클릭하세요."
+
+3. **다음 턴** — 사용자 응답 후:
+   - `$SCREEN_DIR/.events` 읽기 (있으면) — 클릭/선택 이벤트 JSON
+   - 사용자의 터미널 텍스트와 병합
+   - 터미널 메시지가 주 피드백, `.events`는 보조
+
+4. **반복 또는 진행** — 피드백으로 현재 화면 수정 시 새 파일 작성 (예: `architecture-v2.html`)
+
+5. **터미널 복귀 시 대기 화면 표시** — 다음 단계가 브라우저 불필요할 때:
+
+   ```html
+   <!-- filename: waiting.html -->
+   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
+     <p class="subtitle">터미널에서 계속 진행 중...</p>
+   </div>
+   ```
+
+6. 반복.
+
+## 콘텐츠 프래그먼트 작성
+
+프레임 안에 들어갈 콘텐츠만 작성한다. 서버가 자동으로 프레임 템플릿(헤더, CSS, 선택 인디케이터 등)을 감싸준다.
+
+### 아키텍처 다이어그램 예시
+
+```html
+<h2>시스템 아키텍처</h2>
+<p class="subtitle">제안하는 전체 아키텍처 구성</p>
+
+<div class="mockup">
+  <div class="mockup-header">Architecture Diagram</div>
+  <div class="mockup-body">
+    <div style="display:flex;gap:2rem;justify-content:center;flex-wrap:wrap;">
+      <div class="placeholder" style="width:150px;padding:1.5rem;">
+        <strong>API Gateway</strong><br><small>인증, 라우팅</small>
+      </div>
+      <div class="placeholder" style="width:150px;padding:1.5rem;">
+        <strong>Service A</strong><br><small>비즈니스 로직</small>
+      </div>
+      <div class="placeholder" style="width:150px;padding:1.5rem;">
+        <strong>Service B</strong><br><small>데이터 처리</small>
+      </div>
+    </div>
+    <div style="text-align:center;margin:1rem 0;color:var(--text-secondary);">
+      ↕ REST / gRPC
+    </div>
+    <div style="display:flex;gap:2rem;justify-content:center;">
+      <div class="placeholder" style="width:150px;padding:1.5rem;">
+        <strong>PostgreSQL</strong>
+      </div>
+      <div class="placeholder" style="width:150px;padding:1.5rem;">
+        <strong>Redis</strong>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+### 접근안 비교 예시
+
+```html
+<h2>아키텍처 접근안 비교</h2>
+<p class="subtitle">각 접근안의 장단점을 비교하세요</p>
+
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>모놀리스</h3>
+      <p>단일 애플리케이션으로 빠른 개발, 단순한 배포</p>
+      <div class="pros-cons" style="margin-top:0.5rem;">
+        <div class="pros"><h4>Pros</h4><ul><li>빠른 초기 개발</li><li>단순한 인프라</li></ul></div>
+        <div class="cons"><h4>Cons</h4><ul><li>스케일링 제한</li><li>결합도 높음</li></ul></div>
+      </div>
+    </div>
+  </div>
+  <div class="option" data-choice="b" onclick="toggleSelect(this)">
+    <div class="letter">B</div>
+    <div class="content">
+      <h3>마이크로서비스</h3>
+      <p>독립적 서비스로 유연한 스케일링</p>
+      <div class="pros-cons" style="margin-top:0.5rem;">
+        <div class="pros"><h4>Pros</h4><ul><li>독립 배포</li><li>기술 스택 자유</li></ul></div>
+        <div class="cons"><h4>Cons</h4><ul><li>운영 복잡도</li><li>네트워크 오버헤드</li></ul></div>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+### 데이터 흐름 예시
+
+```html
+<h2>데이터 흐름</h2>
+<p class="subtitle">요청부터 응답까지의 데이터 흐름</p>
+
+<div class="mockup">
+  <div class="mockup-header">Data Flow</div>
+  <div class="mockup-body" style="font-family:monospace;font-size:0.85rem;line-height:2;">
+    <div>Client → API Gateway → Auth Middleware</div>
+    <div style="padding-left:2rem;">↓</div>
+    <div style="padding-left:2rem;">Route Handler → Service Layer</div>
+    <div style="padding-left:4rem;">↓</div>
+    <div style="padding-left:4rem;">Repository → Database</div>
+    <div style="padding-left:4rem;">↓</div>
+    <div style="padding-left:4rem;">Cache (Redis) ← Response</div>
+    <div style="padding-left:2rem;">↓</div>
+    <div>Client ← Serialized Response</div>
+  </div>
+</div>
+```
+
+## CSS 클래스 레퍼런스
+
+프레임 템플릿이 제공하는 CSS 클래스:
+
+### Options (A/B/C 선택)
+```html
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content"><h3>제목</h3><p>설명</p></div>
+  </div>
+</div>
+```
+
+**다중 선택:** 컨테이너에 `data-multiselect` 추가.
+
+### Cards (시각적 디자인)
+```html
+<div class="cards">
+  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+    <div class="card-image"><!-- 내용 --></div>
+    <div class="card-body"><h3>이름</h3><p>설명</p></div>
+  </div>
+</div>
+```
+
+### Mockup 컨테이너
+```html
+<div class="mockup">
+  <div class="mockup-header">제목</div>
+  <div class="mockup-body"><!-- 내용 --></div>
+</div>
+```
+
+### Split view (나란히 비교)
+```html
+<div class="split">
+  <div class="mockup"><!-- 왼쪽 --></div>
+  <div class="mockup"><!-- 오른쪽 --></div>
+</div>
+```
+
+### Pros/Cons
+```html
+<div class="pros-cons">
+  <div class="pros"><h4>Pros</h4><ul><li>장점</li></ul></div>
+  <div class="cons"><h4>Cons</h4><ul><li>단점</li></ul></div>
+</div>
+```
+
+### Placeholder (와이어프레임 블록)
+```html
+<div class="placeholder">영역 설명</div>
+```
+
+### Typography
+- `h2` — 페이지 제목
+- `h3` — 섹션 제목
+- `.subtitle` — 부제
+- `.section` — 콘텐츠 블록
+- `.label` — 소문자 라벨
+
+## 브라우저 이벤트 형식
+
+`$SCREEN_DIR/.events`에 JSON 라인으로 기록:
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - 모놀리스","timestamp":1706000101}
+{"type":"click","choice":"b","text":"Option B - 마이크로서비스","timestamp":1706000108}
+```
+
+마지막 이벤트가 최종 선택일 가능성이 높지만, 클릭 패턴에서 고민을 읽을 수 있다.
+
+## 파일 네이밍
+
+- 시맨틱 이름: `architecture.html`, `data-flow.html`, `comparison.html`
+- 파일명 재사용 금지 — 매 화면 새 파일
+- 반복 시: `architecture-v2.html`, `architecture-v3.html`
+
+## 서버 종료
+
+```bash
+scripts/stop-server.sh $SCREEN_DIR
+```
+
+`--project-dir` 사용 시 `.plan-viewer/sessions/`에 파일이 유지된다.

package/assets/skills/scaffold/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: scaffold
+description: Integrated project scaffolding launcher. Generates projects for various technology stacks based on presets. Use it when you receive requests such as “create a new project,” “initialize a project,” or “scaffold.”
+argument-hint: <project-name> [--preset nextjs-fullstack|monorepo] [--db sqlite|postgres] [--ui shadcn|none] [--pm bun|npm|pnpm] [--packages pkg1 pkg2 ...]
+allowed-tools: Bash, Read, Write, Edit, Glob
+---
+
+# scaffold
+
+Integrated project scaffolding skill. When you select a preset, it automatically generates a project structure that matches the chosen stack.
+
+---
+
+## Usage Examples
+
+```
+/scaffold my-app
+/scaffold my-app --preset nextjs-fullstack
+/scaffold my-app --preset nextjs-fullstack --db postgres --ui none --pm pnpm
+/scaffold my-mono --preset monorepo
+/scaffold my-mono --preset monorepo --packages core utils api --pm pnpm
+/scaffold .  --preset nextjs-fullstack
+```
+
+---
+
+## How to Parse $ARGUMENTS
+
+When this skill is invoked, Claude must:
+
+1. Parse `$ARGUMENTS` to extract:
+   - **Project name** — first positional argument (e.g., `my-app` or `.`)
+   - `--preset` — which preset to use (`nextjs-fullstack` | `monorepo`)
+   - `--db` — database choice (`sqlite` | `postgres`), only for nextjs-fullstack
+   - `--ui` — UI library choice (`shadcn` | `none`), only for nextjs-fullstack
+   - `--pm` — package manager (`bun` | `npm` | `pnpm`)
+   - `--packages` — space-separated list of package names, only for monorepo
+
+2. **If no arguments at all**: Ask the user:
+   - Which preset they want (`nextjs-fullstack` or `monorepo`)
+   - What the project name should be
+   - Any non-default options they want
+
+3. **If project name is given but no `--preset`**: Default to `nextjs-fullstack`.
+
+4. **Validate** the project name is provided before running any script. If missing, ask for it.
+
+---
+
+## Preset: nextjs-fullstack
+
+Full-stack Next.js app with TypeScript, Tailwind CSS, Drizzle ORM, and optionally shadcn/ui.
+
+**Defaults**: `--db sqlite --ui shadcn --pm bun`
+
+**Command to run**:
+```bash
+bash ~/.claude/skills/scaffold/scripts/nextjs-fullstack.sh <project-name> --db <db> --ui <ui> --pm <pm>
+```
+
+**Example**:
+```bash
+bash ~/.claude/skills/scaffold/scripts/nextjs-fullstack.sh my-app --db sqlite --ui shadcn --pm bun
+```
+
+**After-run guidance** (tell the user):
+- `cd <project-name>` (unless initialized in-place)
+- Run `<pm> run db:migrate` to apply the first migration
+- Run `<pm> run dev` to start the development server
+- Drizzle Studio available via `<pm> run db:studio`
+- For postgres: make sure to set `DATABASE_URL` in `.env.local` before migrating
+
+---
+
+## Preset: monorepo
+
+Turborepo monorepo with shared TypeScript config, shared ESLint config, Prettier, and optional extra packages.
+
+**Defaults**: `--pm bun` (no extra packages)
+
+**Command to run**:
+```bash
+bash ~/.claude/skills/scaffold/scripts/monorepo.sh <project-name> --pm <pm> [--packages pkg1 pkg2 ...]
+```
+
+**Example**:
+```bash
+bash ~/.claude/skills/scaffold/scripts/monorepo.sh my-mono --pm bun --packages core utils
+```
+
+**After-run guidance** (tell the user):
+- `cd <project-name>` (unless initialized in-place)
+- Run `<pm> run build` to build all packages
+- Run `<pm> run dev` to start development mode across all packages
+- Add new packages by creating a directory under `packages/` and following the pattern of existing packages
+- For pnpm: workspace config lives in `pnpm-workspace.yaml`
+
+---
+
+## Option Reference
+
+See `~/.claude/skills/scaffold/presets.md` for the full option matrix, DB-specific details, and planned future presets.
+
+---
+
+## Decision Flow
+
+```
+$ARGUMENTS empty?
+  YES → Ask user for preset + project name + options
+  NO  →
+    project name present?
+      NO  → Ask for project name
+      YES →
+        --preset specified?
+          NO  → default to nextjs-fullstack
+          YES → use specified preset
+        Run the appropriate script with all parsed flags
+```

package/assets/skills/scaffold/presets.md

@@ -0,0 +1,94 @@
+# Scaffold Presets
+
+This document describes all available presets, their options, and which script powers them.
+
+---
+
+## nextjs-fullstack
+
+**Description**: Full-stack Next.js app with TypeScript, Tailwind CSS, Drizzle ORM, and optionally shadcn/ui. Suitable for web applications that need a database and a modern component library out of the box.
+
+**Script**: `~/.claude/skills/scaffold/scripts/nextjs-fullstack.sh`
+
+**Default options**:
+- `--db sqlite`
+- `--ui shadcn`
+- `--pm bun`
+
+**Option matrix**:
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--db` | `sqlite`, `postgres` | `sqlite` | Database driver and Drizzle dialect |
+| `--ui` | `shadcn`, `none` | `shadcn` | UI component library |
+| `--pm` | `bun`, `npm`, `pnpm` | `bun` | Package manager |
+
+**DB details**:
+
+| | sqlite | postgres |
+|-|--------|----------|
+| Runtime dep | `drizzle-orm better-sqlite3` | `drizzle-orm pg` |
+| Dev dep | `drizzle-kit @types/better-sqlite3` | `drizzle-kit @types/pg` |
+| Schema import | `drizzle-orm/sqlite-core` | `drizzle-orm/pg-core` |
+| Column types | `int`, `text`, `sqliteTable` | `serial`, `text`, `timestamp`, `pgTable` |
+| DB connection | `drizzle-orm/better-sqlite3` | `drizzle-orm/node-postgres` with `Pool` |
+| Dialect in config | `sqlite` | `postgresql` |
+| `.env.local` | `DATABASE_URL=sqlite.db` | `DATABASE_URL=postgresql://localhost:5432/<name>` |
+| `.gitignore` extras | `*.db`, `*.db-shm`, `*.db-wal` | (none) |
+
+**Usage examples**:
+```bash
+# All defaults
+bash ~/.claude/skills/scaffold/scripts/nextjs-fullstack.sh my-app
+
+# Postgres + no UI
+bash ~/.claude/skills/scaffold/scripts/nextjs-fullstack.sh my-app --db postgres --ui none
+
+# npm + shadcn + sqlite
+bash ~/.claude/skills/scaffold/scripts/nextjs-fullstack.sh my-app --pm npm
+
+# In-place (current directory)
+bash ~/.claude/skills/scaffold/scripts/nextjs-fullstack.sh .
+```
+
+---
+
+## monorepo
+
+**Description**: Bun (or npm/pnpm) + Turborepo monorepo with shared TypeScript config, shared ESLint config, Prettier, and optional extra packages scaffolded under `packages/`.
+
+**Script**: `~/.claude/skills/scaffold/scripts/monorepo.sh`
+
+**Default options**:
+- `--pm bun`
+- `--packages` (none — only shared config packages are created)
+
+**Option matrix**:
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--pm` | `bun`, `npm`, `pnpm` | `bun` | Package manager |
+| `--packages` | space-separated names | (empty) | Extra packages to scaffold under `packages/` |
+
+**Usage examples**:
+```bash
+# Minimal monorepo
+bash ~/.claude/skills/scaffold/scripts/monorepo.sh my-mono
+
+# With extra packages
+bash ~/.claude/skills/scaffold/scripts/monorepo.sh my-mono --packages core utils api
+
+# pnpm with packages
+bash ~/.claude/skills/scaffold/scripts/monorepo.sh my-mono --pm pnpm --packages sdk cli
+```
+
+---
+
+## Planned Presets
+
+The following presets are on the roadmap and will be added in future versions:
+
+| Preset | Description |
+|--------|-------------|
+| `vite-react` | Vite + React + TypeScript + TailwindCSS, optionally with shadcn/ui |
+| `api-only` | Lightweight REST/RPC API server (Hono or Fastify), TypeScript, Drizzle ORM |

package/assets/skills/scaffold/scripts/common.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# common.sh — Shared utilities for scaffold scripts
+
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+RED='\033[0;31m'
+BOLD='\033[1m'
+RESET='\033[0m'
+
+info()    { echo -e "${BLUE}[INFO]${RESET} $*"; }
+success() { echo -e "${GREEN}[OK]${RESET}   $*"; }
+warn()    { echo -e "${YELLOW}[WARN]${RESET} $*"; }
+error()   { echo -e "${RED}[ERR]${RESET}  $*" >&2; }
+step()    { echo -e "\n${BOLD}${CYAN}==> $*${RESET}"; }
+
+# check_command <cmd> <install-hint>
+check_command() {
+  if ! command -v "$1" &>/dev/null; then
+    error "$1 이 설치되어 있지 않습니다."
+    echo "  설치: $2"
+    exit 1
+  fi
+  success "$1 $(command "$1" --version 2>&1 | head -1)"
+}
+
+# resolve_target_dir <project-arg>
+# Sets: TARGET_DIR, PROJECT_NAME, INIT_IN_PLACE
+resolve_target_dir() {
+  local project_arg="$1"
+
+  if [ "$project_arg" = "." ]; then
+    TARGET_DIR="$(pwd)"
+    PROJECT_NAME="$(basename "$TARGET_DIR")"
+    INIT_IN_PLACE=true
+    if [ "$(ls -A "$TARGET_DIR" 2>/dev/null)" ]; then
+      error "현재 디렉토리가 비어있지 않습니다: $TARGET_DIR"
+      exit 1
+    fi
+  else
+    TARGET_DIR="$(pwd)/$project_arg"
+    PROJECT_NAME="$project_arg"
+    INIT_IN_PLACE=false
+    if [ -d "$TARGET_DIR" ] && [ "$(ls -A "$TARGET_DIR" 2>/dev/null)" ]; then
+      error "디렉토리가 이미 존재하고 비어있지 않습니다: $TARGET_DIR"
+      exit 1
+    fi
+    mkdir -p "$TARGET_DIR"
+  fi
+
+  export TARGET_DIR PROJECT_NAME INIT_IN_PLACE
+  info "프로젝트: ${PROJECT_NAME} (${TARGET_DIR})"
+}
+
+# git_init_commit <commit-message>
+git_init_commit() {
+  local msg="$1"
+  if [ ! -d ".git" ]; then
+    git init -q
+    git add -A
+    git commit -q -m "$msg"
+    success "Git 초기화 및 첫 커밋 완료"
+  else
+    git add -A
+    if ! git diff --cached --quiet; then
+      git commit -q -m "$msg"
+      success "커밋 완료"
+    else
+      info "커밋할 변경사항 없음 — 건너뜀"
+    fi
+  fi
+}