sppurt 0.0.0-stage → 0.6.0

package/dist/skills/status-check/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: sppt-status-check
+description: |
+  전채널 연결 상태 + API 건강 체크 + 스토어 브리핑.
+  Use when asked to "상태 확인", "채널 연결 돼있어?", "헬스체크", "지금 상황 알려줘".
+---
+
+# status-check
+
+전체 채널 연결 상태를 점검하고 스토어 운영 현황을 브리핑하는 워크플로우.
+
+## When to use
+
+- "지금 상태 어때?", "채널 다 연결돼있어?", "헬스체크 해줘"
+- 작업 시작 전 환경 점검
+- 오류 발생 후 연결 상태 진단
+
+## Steps
+
+### 1. 채널 연결 상태
+
+```bash
+sppt status
+```
+
+각 판매/소싱 채널의 연결 상태, 토큰 만료 여부, API 레이턴시를 확인합니다.
+
+### 2. 스토어 브리핑
+
+```bash
+sppt context
+```
+
+AI용 스토어 정보를 확인합니다:
+- 스토어 프로필 (브랜드, 포지셔닝)
+- 상품 분류 규칙
+- 판매 인사이트
+
+### 3. API 기능 현황
+
+```bash
+sppt cap
+```
+
+채널별로 어떤 API 기능이 사용 가능한지 확인합니다.
+
+### 4. API 사용량
+
+```bash
+sppt budget
+```
+
+채널별 API 호출량과 한도를 확인합니다.
+
+### 5. 진단 결과 요약
+
+```
+🏥 Sppurt 헬스체크
+────────────────────────────────────
+채널          상태    토큰     레이턴시
+cafe24        ✅     유효     120ms
+coupang       ✅     유효     85ms
+smartstore    ⚠️     만료임박  200ms
+shopify       ❌     미설정   -
+────────────────────────────────────
+소싱 채널: domeggook ✅ | specialoffer ✅
+```
+
+문제가 있는 채널은 해결 방법을 안내합니다:
+- 토큰 만료 → `sppt auth <channel>`
+- 미설정 → `sppt init <channel>`
+- 레이턴시 높음 → API 상태 모니터링 권장
+
+## Notes
+
+- 작업 시작 전 `sppt status` 습관화 권장
+- cafe24 토큰은 2시간마다 자동 갱신됩니다
+- `--json` 플래그로 프로그래밍적 활용 가능

package/dist/skills/status-check/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "채널 상태 체크"
+  short_description: "전채널 API 연결 상태 + 스토어 브리핑"
+  brand_color: "#2563EB"
+  default_prompt: "$sppt-status-check 채널 상태 확인해줘"
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/trend-research/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: sppt-trend-research
+description: |
+  트렌드 키워드 리서치 — 검색량 조회, 키워드 비교, 전문몰 랭킹.
+  Use when asked to "트렌드 확인", "키워드 검색량", "뭐가 잘 팔려", "시장 조사".
+---
+
+# trend-research
+
+트렌드 키워드를 리서치하고 시장 수요를 파악하는 워크플로우.
+
+## When to use
+
+- "이 키워드 검색량 어때?", "뭐가 잘 팔려?", "트렌드 분석해줘"
+- 신규 상품 소싱 전 수요 확인
+- 키워드 간 비교가 필요할 때
+- 전문몰(무신사, 올리브영 등) 랭킹 확인
+
+## Prerequisites
+
+- `sppt` CLI 설치 완료
+
+## Steps
+
+### 1. 키워드 검색량 조회
+
+```bash
+sppt trend keyword <키워드>
+```
+
+네이버 데이터랩 기반 검색량 + 트렌드 방향을 확인합니다.
+
+판단 기준:
+| 월 검색량 | 수요 |
+|---|---|
+| 10,000+ | 높음 — 경쟁도 높을 수 있음 |
+| 1,000~10,000 | 적정 — 니치 시장 가능성 |
+| 1,000 미만 | 낮음 — 틈새 or 비인기 |
+
+### 2. 키워드 비교
+
+후보 키워드가 여러 개일 때 상대 비교:
+
+```bash
+sppt trend compare <키워드1> <키워드2> [키워드3]
+```
+
+검색량, 트렌드 방향, 경쟁강도를 비교합니다.
+
+### 3. 전문몰 랭킹 확인
+
+특정 카테고리의 전문몰 인기 상품을 확인합니다:
+
+```bash
+sppt trend platform musinsa
+sppt trend platform oliveyoung
+sppt trend platform hwahae
+```
+
+지원 플랫폼: 무신사, 올리브영, 화해 등
+
+### 4. 결과 종합
+
+사용자에게 다음을 제안합니다:
+
+1. **검색량 충분 + 상승 트렌드**: 소싱 적기 → `/sppt-source-to-register`로 진행
+2. **검색량 충분 + 하락 트렌드**: 재고 리스크 있음, 소량 테스트 권장
+3. **검색량 부족**: 키워드 변경 또는 연관 키워드로 확장
+
+## Error handling
+
+- **검색량 데이터 없음**: 키워드 오타 확인, 영문/한글 변환 시도
+- **전문몰 데이터 실패**: 해당 플랫폼 API 상태 확인
+
+## Notes
+
+- 네이버 데이터랩은 상대값 기반이므로 절대 검색량은 추정치입니다
+- 시즌 상품은 전년 동기 대비 확인 권장
+- 소싱 전 트렌드 확인은 재고 리스크를 줄이는 핵심 단계입니다

package/dist/skills/trend-research/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "트렌드 키워드 리서치"
+  short_description: "검색량 조회 · 키워드 비교 · 전문몰 트렌드 분석"
+  brand_color: "#2563EB"
+  default_prompt: "$sppt-trend-research 요즘 잘 팔리는 키워드 알려줘"
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/update/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: sppt-update
+description: |
+  Sppurt CLI 버전 업데이트 + 릴리즈 노트 확인.
+  Use when asked to "업데이트", "최신 버전", "sppt update", "버전 올려줘", "새 버전 있어?".
+---
+
+# update
+
+Sppurt CLI를 최신 버전으로 업데이트하고 변경사항을 확인하는 워크플로우.
+
+## When to use
+
+- "업데이트 해줘", "최신 버전으로 올려줘"
+- "새 버전 나왔어?", "지금 몇 버전이야?"
+- 스킬이 안 되거나 새 커맨드가 없을 때
+
+## Steps
+
+### 1. 현재 버전 확인
+
+```bash
+sppt --version
+```
+
+### 2. 최신 버전 확인
+
+```bash
+npm view sppurt version
+```
+
+현재 버전과 최신 버전을 비교합니다.
+- 같으면 → "이미 최신 버전입니다" 안내 후 종료
+- 다르면 → 3단계로 진행
+
+### 3. 업데이트 실행
+
+```bash
+npm update -g sppurt
+```
+
+설치 시 `postinstall` 훅이 자동으로 `setup-skills`를 실행하여 새 스킬도 함께 등록됩니다.
+
+### 4. 업데이트 확인
+
+```bash
+sppt --version
+```
+
+버전이 올라갔는지 확인합니다.
+
+### 5. 릴리즈 노트 확인
+
+```bash
+gh release view v<최신버전> --repo onlymytho/sppurt
+```
+
+주요 변경사항을 사용자에게 요약해줍니다:
+- 새로 추가된 기능/스킬
+- 버그 수정 사항
+- Breaking changes (있는 경우)
+
+## 결과 요약 형식
+
+```
+📦 Sppurt 업데이트 완료
+────────────────────────────────────
+이전 버전:  v0.2.4
+현재 버전:  v0.3.0
+────────────────────────────────────
+주요 변경:
+• 정산 엔진 대폭 강화 (채널×PG 분리 계산)
+• 알림 체계 구축
+• 새 스킬: /sppt-policy-ask
+────────────────────────────────────
+```
+
+## Notes
+
+- 기존 `shopport` 패키지 사용자라면 한 번 `npm uninstall -g shopport` 후 `npm install -g sppurt`를 실행하세요. `sppt` 명령과 기존 사용자 데이터는 유지됩니다.
+- `npm update -g`가 안 되면 `npm install -g sppurt@latest`로 시도
+- 권한 오류 시 `sudo npm update -g sppurt` 또는 nvm/volta 사용 권장
+- 업데이트 후 스킬이 갱신되지 않으면 `sppt setup-skills` 수동 실행

package/dist/skills/waterfall-source/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: sppt-waterfall-source
+description: |
+  3개 소싱 채널(도매매→specialoffer→cjdropshipping) 워터폴 가격 비교.
+  Use when asked to "가장 싼 공급사 찾아줘", "소싱 비교", "최적 소싱처".
+---
+
+# waterfall-source
+
+3개 소싱 채널을 비용 낮은 순서대로 검색하는 워터폴 소싱 워크플로우.
+
+## When to use
+
+- 사용자가 "가장 싼 공급사 찾아줘", "최적 소싱처 검색", "소싱 비교해줘" 같은 요청을 할 때
+- 여러 소싱 채널에서 동일 상품의 가격/조건을 비교할 때
+
+## Prerequisites
+
+- 최소 2개 이상 소싱 채널 설정
+- `sppt config list`로 소싱 채널 확인
+
+## Steps
+
+### 1. 워터폴 검색 실행
+
+`--waterfall` 플래그로 3채널을 자동으로 순서대로 검색합니다.
+
+**비용 절약 모드 (기본)** — 첫 유효 결과에서 중단:
+
+```bash
+sppt source search domeggook "<keyword>" --waterfall --strategy first
+```
+
+**최적 품질 모드** — 3채널 전부 검색 후 스코어 비교:
+
+```bash
+sppt source search domeggook "<keyword>" --waterfall --strategy best
+```
+
+워터폴 순서: domeggook(도매매) → specialoffer → cjdropshipping (비용 오름차순)
+
+결과에는 각 상품의 마진율과 종합 스코어(마진 40% + 재고유연성 30% + 공급사신뢰도 30%)가 표시됩니다.
+
+### 2. 상세 조회
+
+워터폴 결과에서 선택한 상품의 상세 정보를 확인합니다:
+
+```bash
+sppt source detail <channel> <productId>
+```
+
+### 3. 결과 요약
+
+사용자에게 채널별 비교 결과를 표로 정리합니다:
+
+```
+워터폴 소싱 결과: "키워드"
+검색 채널: 도매매, specialoffer, cjdropshipping  캐시 히트: 0  API 호출: 2  결과: 8건
+
+채널           상품명         도매가     마진    스코어
+도매매         상품A          8,500원    32%     78/100
+specialoffer   상품B          9,200원    28%     71/100
+cjdropshipping 상품C          7,150원    35%     65/100
+─────────────────────────────────────
+추천: 도매매 — 상품A (스코어 1위)
+```
+
+## Error handling
+
+- **전체 채널 검색 실패**: 키워드를 변경하거나 영문으로 검색 시도
+- **도매매 일일 한도 초과**: CLI가 자동으로 다음 채널로 진행
+- **Rate limit**: CLI의 rate limiter가 자동 처리하므로 대기
+
+## Notes
+
+- `--strategy first` (기본): 첫 유효 결과에서 중단 — API 호출 최소화
+- `--strategy best`: 전체 검색 후 스코어 기반 최적 선택
+- 검색 결과는 2시간 캐시됨 — 같은 키워드 재검색 시 캐시 반환
+- CJ Dropshipping USD 가격은 기본 환율(1,380원) 또는 `--usd-krw N`으로 지정
+- 공급사 신뢰도 스코어는 `order score record`로 쌓인 실데이터 기반

package/dist/skills/waterfall-source/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "워터폴 소싱 비교"
+  short_description: "도매매→specialoffer→CJ 3채널 가격 비교"
+  brand_color: "#2563EB"
+  default_prompt: "$sppt-waterfall-source 소싱 가격 비교해줘"
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/weekly-analysis/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: sppt-weekly-analysis
+description: |
+  전주 대비 매출 변화 원인 분석 + 채널 수수료 최적화 컨설팅 워크플로우.
+  Use when asked to "주간 분석", "왜 매출이 줄었어", "채널별 원인 분석", "지난 주 비교",
+  "매출이익률 분석", "수수료율 변화", "원인 분석해줘".
+---
+
+# weekly-analysis
+
+## 채널 분류 컨텍스트
+
+`channelMeta` 응답의 각 채널에는 `type`(own-mall/open-market/vertical-specialist), `entryRequirement`(open/contract), `hasChannelBrandValue`가 정의되어 있다.
+
+**수수료 최적화 시 주의:**
+- `entryRequirement: "contract"` 채널은 계약 관계이므로 단순 수수료 비교로 비중 축소를 권고하면 안 된다.
+- `hasChannelBrandValue: true` 채널은 높은 수수료에 마케팅·브랜딩·노출 가치가 포함된다.
+- 채널 간 이동보다 **같은 채널 내 최적화**(유입경로, 단가, 프로모션)가 실행 가능성이 높다.
+
+## Data Collection
+
+커맨드 **1회**로 모든 데이터를 가져옵니다:
+
+```bash
+sppt report weekly --json
+```
+
+옵션:
+- `--period 7d` (기본값) — 채널/상품 비교 기간
+- `--top 10` (기본값) — 채널/상품 표시 개수
+- `--settlement-days 30` (기본값) — 정산 집계 기간
+
+응답 구조:
+- `channelMeta` — 채널 특성 (type/entryRequirement/hasChannelBrandValue)
+- `channelFees` — 채널별 수수료 전체 (유입경로별 포함)
+- `reportByChannel` — 채널별 현재/전주 비교 + diff
+- `reportByProduct` — 상품별 현재/전주 비교 + diff (top 10)
+- `settlement` — 채널별 정산 요약 (매출/수수료/순수익/실효수수료율)
+- `costs` — SKU별 원가 목록 (미등록 시 null)
+
+## Analysis Steps
+
+### Step 1: 채널 수수료율 분석
+
+1. **채널별 수수료율 랭킹** — 채널 분류(자사몰/오픈마켓/버티컬)와 함께 표시. 표본 < 5건은 신뢰도 낮음 표기.
+2. **실효수수료율** = Σ(채널_비중 × 채널_수수료율), 오픈마켓 채널 간 비중과 버티컬 채널 비중을 분리해서 보여줌.
+3. **스마트스토어 유입경로 분석** — `fee list smartstore` 결과로 마케팅링크 유입 비중이 실효율에 미치는 영향 추정. 규칙 미등록 시 annualRevenue/브랜드스토어 여부에 따른 오차 가능성 언급.
+4. **오픈마켓 내 믹스 최적화** — smartstore ↔ cafe24 비중 이동 시 절감 효과. 버티컬 채널은 별도 분석.
+5. **집중 리스크** — 단일 채널 비중 > 70% 경고. 단, 버티컬 채널의 비중 감소는 리스크가 아닌 채널 특성으로 해석.
+6. **전주 대비 변화** (데이터 있을 때만) — 채널믹스 효과 vs 채널내 수수료율 변화로 분해.
+
+### Step 2: 채널별 매출 변화 분해
+
+`reportByChannel.diff` 배열에서 직접 읽는다.
+
+- 채널별 매출 증감, volumeEffect / priceEffect 요약
+- 채널 점유율 변화 (이전주 비중 → 이번주 비중)
+
+### Step 3: Top Mover 상품 귀속
+
+`reportByProduct.diff` 배열 상위 항목을 채널 변화에 귀속시킨다.
+
+- 매출 변화 상위 5개 상품: revenueChange, volumeDiff%, priceDiff%
+- 특이값 (신규 등장 또는 완전 소멸 상품) 별도 언급
+
+### Step 4: 공헌이익률 분석 (원가 있을 때만)
+
+- 이번주 vs 지난주 공헌이익률 변화
+- 상품 믹스 효과 vs 단가 변화 효과로 분해
+
+## AI Interpretation
+
+위 데이터를 바탕으로 각 변화에 대해:
+1. 가능한 원인 (내부/외부 구분)
+2. 우선순위 조치 (즉각 / 단기 / 검토)
+3. 수수료 최적화: 채널 특성과 진입 가능성을 고려한 실행 가능한 방안만 제안. "버티컬 채널 축소" 같은 계약 외 조치는 제안하지 않는다.
+
+## Error Handling
+
+- **이번주 매출이 이전주 대비 -80% 이상**: 데이터 수집 공백 가능성 → `sppt order pull` 재실행 안내 후 분석
+- **원가 미등록**: Step 4 skip
+- **채널 1개만**: 수수료 비교 skip, 단가/볼륨 분석 집중
+- **settlement 표본 부족** (채널별 < 5건): 수수료율 신뢰도 낮음 표기, `--settlement-days 90` 권장
+- **smartstore fee rule 미등록**: 실효율 신뢰도 낮음 표기. `sppt settlement hints smartstore`로 annualRevenue 설정 권장.

package/dist/skills/weekly-analysis/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "주간 매출 분석"
+  short_description: "전주 대비 매출 변화 원인 분석 + 채널 수수료 최적화"
+  brand_color: "#2563EB"
+  default_prompt: "$sppt-weekly-analysis 이번 주 매출 분석해줘"
+
+policy:
+  allow_implicit_invocation: true

package/package.json

@@ -1,6 +1,61 @@
 {
-  "name": "sppurt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "sppurt",
+	"version": "0.6.0",
+	"description": "커머스 운영 자동화 CLI — Cafe24, Coupang, SmartStore, Shopify 통합 관리",
+	"type": "module",
+	"bin": {
+		"sppt": "dist/cli.js",
+		"sppurt": "dist/cli.js"
+	},
+	"scripts": {
+		"dev": "tsx watch src/cli.ts",
+		"build:dashboard": "cd dashboard-ui && bun install && bun run build",
+		"build": "bun run build:dashboard && tsup && node -e \"const fs=require('fs');const f='dist/cli.js';const c=fs.readFileSync(f,'utf8');fs.writeFileSync(f,'#!/usr/bin/env bun\\n'+c);fs.chmodSync(f,0o755)\"",
+		"start": "node dist/cli.js",
+		"build:publish": "SHOPPORT_PUBLISH=1 bun run build",
+		"postinstall": "node -e \"try{require('child_process').execFileSync(process.execPath,['dist/cli.js','setup-skills'],{stdio:'pipe'})}catch(_){}\"",
+		"prepublishOnly": "bun run build:publish",
+		"test": "vitest run"
+	},
+	"keywords": [
+		"dropshipping",
+		"ecommerce",
+		"cafe24",
+		"coupang",
+		"smartstore",
+		"shopify",
+		"커머스운영",
+		"자동화"
+	],
+	"license": "UNLICENSED",
+	"engines": {
+		"node": ">=18"
+	},
+	"files": ["dist", "README.md"],
+	"dependencies": {
+		"@browserbasehq/stagehand": "^2.0.0",
+		"@e965/xlsx": "^0.20.3",
+		"@hyunbinseo/holidays-kr": "^4.2026.0",
+		"@types/bcrypt": "^6.0.0",
+		"axios": "^1.13.5",
+		"basic-ftp": "^5.3.0",
+		"bcrypt": "^6.0.0",
+		"date-fns": "^4.1.0",
+		"form-data": "^4.0.5",
+		"posthog-node": "^5.30.8",
+		"zod": "^3.24.0"
+	},
+	"devDependencies": {
+		"@shopport/core": "workspace:*",
+		"@shopport/reliability": "workspace:*",
+		"@shopport/types": "workspace:*",
+		"@types/node": "^22.13.10",
+		"javascript-obfuscator": "^5.4.1",
+		"playwright": "^1.59.1",
+		"terser": "^5.46.1",
+		"tsup": "^8.5.1",
+		"tsx": "^4.19.4",
+		"typescript": "^5.8.2",
+		"vitest": "^4.1.4"
+	}
+}