@kood/claude-code 0.5.10 → 0.6.0

package/templates/.claude/skills/crawler/references/document-templates.md

@@ -0,0 +1,147 @@
+# 분석 결과 문서 템플릿
+
+> `.claude/crawler/[사이트명]/` 폴더 구조
+
+---
+
+## 폴더 구조
+
+```
+.claude/crawler/example-com/
+├── ANALYSIS.md      # 사이트 구조
+├── SELECTORS.md     # DOM selector
+├── API.md           # API endpoint
+├── NETWORK.md       # 인증 정보
+└── CRAWLER.ts       # 생성 코드
+```
+
+---
+
+## ANALYSIS.md
+
+```markdown
+# [사이트명] 크롤링 분석
+
+생성: {{TIMESTAMP}}
+URL: {{BASE_URL}}
+
+## 페이지 타입
+
+| 타입 | URL | 비고 |
+|------|-----|------|
+| 목록 | /items | |
+| 상세 | /items/[id] | |
+| 검색 | /search?q= | |
+
+## 데이터 로딩
+
+- [ ] SSR
+- [ ] CSR (API 기반)
+- [ ] 무한 스크롤
+- [ ] 페이지네이션
+
+## 인증
+
+- [ ] 공개
+- [ ] 로그인 필요
+- [ ] API 키
+
+## 발견사항
+
+[특이사항, 제약, 주의점]
+```
+
+---
+
+## SELECTORS.md
+
+```markdown
+# [사이트명] Selector
+
+## 목록 페이지
+
+| 요소 | Selector | 비고 |
+|------|----------|------|
+| 컨테이너 | `.item-list` | |
+| 카드 | `.item-card` | |
+| 제목 | `.item-card h2` | |
+| 링크 | `.item-card a` | |
+| 다음 | `button[aria-label="Next"]` | |
+
+## aria-ref 매핑
+
+| ref | Selector | 설명 |
+|-----|----------|------|
+| e14 | `getByRole('button', { name: 'Load more' })` | 더보기 |
+```
+
+---
+
+## API.md
+
+```markdown
+# [사이트명] API
+
+## GET /api/items
+
+**Parameters:**
+
+| 파라미터 | 타입 | 설명 |
+|----------|------|------|
+| page | number | 페이지 |
+| limit | number | 개수 |
+
+**Headers:**
+
+```json
+{ "Authorization": "Bearer ..." }
+```
+
+**Response:**
+
+```typescript
+interface Response {
+  data: Item[];
+  pagination: { page: number; total: number; hasNext: boolean };
+}
+```
+
+## Rate Limiting
+
+[제한사항]
+```
+
+---
+
+## NETWORK.md
+
+```markdown
+# [사이트명] Network
+
+## 인증 정보
+
+| 항목 | 값 | 만료 |
+|------|-----|------|
+| Cookie | `session=...` | 24h |
+| Token | `Bearer ...` | 1h |
+
+## 필수 헤더
+
+```json
+{
+  "Cookie": "...",
+  "Authorization": "Bearer ...",
+  "User-Agent": "Mozilla/5.0 ..."
+}
+```
+
+## Rate Limit
+
+- 제한: 60 req/min
+- 딜레이: 1000ms
+
+## 봇 탐지
+
+- [ ] Cloudflare
+- [ ] reCAPTCHA
+```

package/templates/.claude/skills/crawler/references/network-crawling.md

@@ -0,0 +1,141 @@
+# Network 분석
+
+> Playwriter로 인증 정보 추출 → NETWORK.md 문서화
+
+---
+
+<workflow>
+
+```text
+1. Playwriter로 페이지 탐방
+2. API 인터셉트 → 엔드포인트/헤더/쿠키/토큰 추출
+3. NETWORK.md에 문서화
+4. 크롤러 코드 작성 시 활용
+```
+
+</workflow>
+
+---
+
+<cookie>
+
+## 쿠키 추출
+
+```bash
+# 모든 쿠키
+playwriter -s 1 -e "console.log(JSON.stringify(await context.cookies(), null, 2))"
+
+# 인증 쿠키만
+playwriter -s 1 -e $'
+const cookies = await context.cookies();
+console.log(cookies.filter(c =>
+  ["session","token","auth","sid"].some(n => c.name.toLowerCase().includes(n))
+));
+'
+```
+
+</cookie>
+
+---
+
+<token>
+
+## 토큰 추출
+
+```bash
+# localStorage
+playwriter -s 1 -e "console.log(await state.page.evaluate(() => localStorage.getItem('token')))"
+
+# sessionStorage
+playwriter -s 1 -e "console.log(await state.page.evaluate(() => sessionStorage.getItem('accessToken')))"
+
+# Authorization 헤더
+playwriter -s 1 -e $'
+state.page.on("request", req => {
+  const auth = req.headers()["authorization"];
+  if (auth) console.log("Auth:", auth);
+});
+'
+```
+
+</token>
+
+---
+
+<headers>
+
+## 헤더 캡처
+
+```bash
+playwriter -s 1 -e $'
+state.page.on("request", req => {
+  if (req.url().includes("/api/"))
+    console.log(JSON.stringify(req.headers(), null, 2));
+});
+'
+```
+
+</headers>
+
+---
+
+<bot_check>
+
+## 봇 탐지 확인
+
+```bash
+playwriter -s 1 -e "console.log(await state.page.content().then(c => c.includes('cf-')))"
+
+playwriter -s 1 -e $'
+state.page.on("response", res => {
+  if ([403, 429].includes(res.status()))
+    console.log("차단:", res.status(), res.url());
+});
+'
+```
+
+</bot_check>
+
+---
+
+<template>
+
+## NETWORK.md 템플릿
+
+```markdown
+# [사이트명] Network
+
+## 인증
+
+| 항목 | 값 | 만료 |
+|------|-----|------|
+| Cookie | `session=...` | 24h |
+| Token | `Bearer ...` | 1h |
+
+## 필수 헤더
+
+\`\`\`json
+{
+  "Cookie": "...",
+  "Authorization": "Bearer ...",
+  "User-Agent": "Mozilla/5.0 ..."
+}
+\`\`\`
+
+## Rate Limit
+
+- 제한: 60 req/min
+- 딜레이: 1000ms
+
+## 봇 탐지
+
+- [ ] Cloudflare
+- [ ] reCAPTCHA
+
+## 참고
+
+- 봇 탐지 강함 → Nstbrowser
+- 쿠키 만료 짧음 → 갱신 로직
+```
+
+</template>

package/templates/.claude/skills/crawler/references/playwriter-commands.md

@@ -0,0 +1,172 @@
+# Playwriter 명령어
+
+> 크롤링 분석용 핵심 명령어
+
+---
+
+<session>
+
+## 세션
+
+```bash
+playwriter session new      # 생성 → ID 반환
+playwriter session list     # 목록
+playwriter session reset 1  # 리셋
+```
+
+</session>
+
+---
+
+<execution>
+
+## 실행
+
+```bash
+playwriter -s 1 -e "<code>"
+playwriter -s 1 --timeout 20000 -e "<code>"  # 타임아웃 증가
+```
+
+</execution>
+
+---
+
+<page>
+
+## 페이지
+
+```javascript
+// 생성 + 이동
+state.page = await context.newPage();
+await state.page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
+
+// 기존 페이지 찾기
+state.page = context.pages().find(p => p.url().includes('example.com'));
+```
+
+</page>
+
+---
+
+<structure>
+
+## 구조 파악
+
+```javascript
+// 접근성 트리 (권장)
+await accessibilitySnapshot({ page: state.page })
+await accessibilitySnapshot({ page: state.page, search: /button|link/ })
+
+// 시각적 확인
+await screenshotWithAccessibilityLabels({ page: state.page })
+
+// HTML
+await getCleanHTML({ locator: state.page.locator('body') })
+```
+
+</structure>
+
+---
+
+<interaction>
+
+## 상호작용
+
+```javascript
+// 클릭
+await page.locator('aria-ref=e14').click()
+await page.getByRole('button', { name: 'Submit' }).click()
+
+// 입력
+await page.locator('input[name="email"]').fill('test@example.com')
+
+// 스크롤
+await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight))
+```
+
+</interaction>
+
+---
+
+<selector>
+
+## Selector 추출
+
+```javascript
+// aria-ref → Playwright selector
+const sel = await getLocatorStringForElement(page.locator('aria-ref=e14'));
+// => "getByRole('button', { name: 'Save' })"
+```
+
+</selector>
+
+---
+
+<network>
+
+## 네트워크 인터셉트
+
+```javascript
+state.requests = []; state.responses = [];
+page.on('request', req => {
+  if (req.url().includes('/api/'))
+    state.requests.push({ url: req.url(), method: req.method(), headers: req.headers() });
+});
+page.on('response', async res => {
+  if (res.url().includes('/api/'))
+    try { state.responses.push({ url: res.url(), body: await res.json() }); } catch {}
+});
+
+// 분석
+state.responses.forEach(r => console.log(r.url));
+
+// 정리
+page.removeAllListeners('request');
+page.removeAllListeners('response');
+```
+
+</network>
+
+---
+
+<screenshot>
+
+## 스크린샷
+
+```javascript
+await page.screenshot({ path: 'shot.png', scale: 'css' })
+await page.screenshot({ path: 'full.png', scale: 'css', fullPage: true })
+await page.locator('.card').screenshot({ path: 'card.png', scale: 'css' })
+```
+
+</screenshot>
+
+---
+
+<wait>
+
+## 대기
+
+```javascript
+await page.waitForLoadState('domcontentloaded')
+await page.waitForSelector('.loaded')
+await waitForPageLoad({ page: state.page, timeout: 5000 })
+```
+
+</wait>
+
+---
+
+<utils>
+
+## 유틸리티
+
+| 함수 | 용도 |
+|------|------|
+| `accessibilitySnapshot({ page })` | 접근성 트리 |
+| `screenshotWithAccessibilityLabels({ page })` | 레이블 스크린샷 |
+| `getCleanHTML({ locator })` | 정제된 HTML |
+| `getLocatorStringForElement(locator)` | Selector 추출 |
+| `waitForPageLoad({ page })` | 로드 대기 |
+
+</utils>

package/templates/.claude/skills/crawler/references/pre-crawl-checklist.md

@@ -0,0 +1,221 @@
+# 크롤링 전 분석 체크리스트
+
+> Playwriter 사이트 분석 시 확인 항목
+
+---
+
+<rendering_check>
+
+## 렌더링 방식
+
+```bash
+playwriter -s 1 -e $'
+const html = await state.page.content();
+console.log("HTML:", html.length, "| SSR:", html.length > 5000 ? "가능" : "CSR");
+'
+```
+
+| 방식 | 특징 | 전략 |
+|------|------|------|
+| SSR | HTML에 데이터 포함 | DOM 파싱 |
+| CSR | JS로 로딩 | API 인터셉트 |
+| Hybrid | 초기 SSR + 추가 CSR | 혼합 |
+
+</rendering_check>
+
+---
+
+<bot_detection>
+
+## 봇 탐지 확인
+
+```bash
+playwriter -s 1 -e $'
+const html = await state.page.content();
+console.log({
+  cloudflare: html.includes("cf-ray") || html.includes("cf-challenge"),
+  recaptcha: html.includes("recaptcha"),
+  hcaptcha: html.includes("hcaptcha"),
+  datadome: html.includes("datadome"),
+  akamai: html.includes("_abck"),
+});
+'
+```
+
+```bash
+# 차단 응답 모니터링
+playwriter -s 1 -e $'
+state.page.on("response", res => {
+  if ([403, 429, 503].includes(res.status()))
+    console.log("차단:", res.status(), res.url());
+});
+'
+```
+
+| 코드 | 의미 | 대응 |
+|------|------|------|
+| 403 | 접근 차단 | Anti-Detect |
+| 429 | Rate Limit | 딜레이 증가 |
+| 503 | 일시 차단 | 대기 후 재시도 |
+
+</bot_detection>
+
+---
+
+<honeypot>
+
+## 허니팟 탐지
+
+```bash
+playwriter -s 1 -e $'
+const hidden = await state.page.$$eval("a", links =>
+  links.filter(a => {
+    const s = getComputedStyle(a);
+    return s.display==="none" || s.visibility==="hidden" || s.opacity==="0" || a.offsetWidth===0;
+  }).map(a => a.href)
+);
+console.log("숨겨진 링크:", hidden.length);
+'
+```
+
+| 유형 | 탐지 | 대응 |
+|------|------|------|
+| 숨김 링크 | `display:none`, `visibility:hidden` | 클릭 금지 |
+| 함정 필드 | `name*=honeypot`, `name*=trap` | 입력 금지 |
+| 0x0 요소 | `offsetWidth===0` | 무시 |
+
+</honeypot>
+
+---
+
+<rate_limit>
+
+## Rate Limiting
+
+```bash
+playwriter -s 1 -e $'
+state.page.on("response", res => {
+  const h = res.headers();
+  if (h["x-ratelimit-limit"]) console.log("Limit:", h["x-ratelimit-limit"]);
+  if (h["retry-after"]) console.log("Retry:", h["retry-after"]);
+});
+'
+```
+
+| 헤더 | 설명 |
+|------|------|
+| `X-RateLimit-Limit` | 최대 요청 수 |
+| `X-RateLimit-Remaining` | 남은 요청 수 |
+| `Retry-After` | 대기 시간 (초) |
+
+</rate_limit>
+
+---
+
+<auth_check>
+
+## 인증 분석
+
+```bash
+# 쿠키
+playwriter -s 1 -e $'
+const cookies = await context.cookies();
+console.log(cookies.filter(c =>
+  ["session","token","auth","jwt"].some(k => c.name.toLowerCase().includes(k))
+));
+'
+
+# 토큰
+playwriter -s 1 -e $'
+const storage = await state.page.evaluate(() => ({
+  local: Object.keys(localStorage).filter(k => k.match(/token|auth|jwt/i)),
+  session: Object.keys(sessionStorage).filter(k => k.match(/token|auth|jwt/i))
+}));
+console.log(storage);
+'
+
+# Authorization 헤더
+playwriter -s 1 -e $'
+state.page.on("request", req => {
+  const auth = req.headers()["authorization"];
+  if (auth) console.log("Auth:", auth.slice(0, 50));
+});
+'
+```
+
+</auth_check>
+
+---
+
+<api_discovery>
+
+## API 발견
+
+```bash
+playwriter -s 1 -e $'
+state.apis = [];
+state.page.on("request", req => {
+  if (req.url().includes("/api/") || req.resourceType()==="fetch")
+    state.apis.push({ method: req.method(), url: req.url().split("?")[0] });
+});
+'
+# 페이지 탐색 후
+playwriter -s 1 -e $'
+const unique = [...new Map(state.apis.map(a => [a.url, a])).values()];
+console.log(unique);
+'
+```
+
+</api_discovery>
+
+---
+
+<dynamic_content>
+
+## 동적 콘텐츠
+
+```bash
+# Lazy loading
+playwriter -s 1 -e $'
+const lazy = await state.page.$$eval("img", imgs =>
+  imgs.filter(i => i.dataset.src || i.loading==="lazy").length
+);
+console.log("Lazy 이미지:", lazy);
+'
+
+# Shadow DOM / iframe
+playwriter -s 1 -e $'
+const shadow = await state.page.$$eval("*", els => els.filter(e => e.shadowRoot).length);
+const iframes = await state.page.$$eval("iframe", f => f.length);
+console.log("Shadow:", shadow, "| iframe:", iframes);
+'
+```
+
+</dynamic_content>
+
+---
+
+<decision_table>
+
+## 전략 결정
+
+| 항목 | 결과 | 권장 |
+|------|------|------|
+| 렌더링 | SSR / CSR | DOM / API |
+| 봇 탐지 | 없음 / 있음 | 일반 / Anti-Detect |
+| 인증 | 공개 / 필요 | 직접 / 쿠키·토큰 |
+| Rate Limit | 없음 / 있음 | 병렬 / 딜레이 |
+
+</decision_table>
+
+---
+
+<warnings>
+
+```text
+⚠️ 허니팟 클릭 금지
+⚠️ Rate Limit 초과 시 중단
+⚠️ robots.txt 확인
+```
+
+</warnings>