@saeroon/cli 0.2.0

package/README.md

@@ -0,0 +1,283 @@
+<p align="center">
+  <img src="https://saeroon.diskn.com/e82ODzSxYY" alt="Saeroon" width="48" height="48" />
+</p>
+
+<h1 align="center">Saeroon CLI</h1>
+
+<p align="center">
+  <strong>Build, preview, and deploy Saeroon sites — from your terminal.</strong>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#commands">Commands</a> ·
+  <a href="#workflows">Workflows</a> ·
+  <a href="https://hosting.saeroon.com/developer/docs">Docs</a>
+</p>
+
+---
+
+## Quick Start
+
+```bash
+# Authenticate
+npx @saeroon/cli login
+
+# Create a new project
+npx @saeroon/cli init
+
+# Live preview
+npx @saeroon/cli preview
+
+# Validate & deploy
+npx @saeroon/cli validate
+npx @saeroon/cli deploy --target production
+```
+
+## Commands
+
+### Auth
+
+| Command | Description |
+|---------|-------------|
+| `login` | API 키 등록 및 연결 확인 |
+| `whoami` | 현재 인증 상태 및 프로젝트 설정 확인 |
+
+### Development
+
+| Command | Description |
+|---------|-------------|
+| `init` | 새 프로젝트 생성 (스타터, 마켓플레이스 템플릿, 기존 사이트에서) |
+| `preview` | 스키마 파일 감시 + 실시간 미리보기 (REST / WebSocket) |
+| `validate` | 스키마 검증 + 품질 리포트. `--local`로 오프라인 검증 가능 |
+| `blocks` | 전체 블록 카탈로그 조회 또는 개별 블록 상세 정보 |
+| `add` | schema.json에 블록 추가 (기본 props + 부모 children 자동 연결) |
+| `upload` | 이미지를 Saeroon CDN에 업로드. `--replace-in`으로 경로 자동 교체 |
+| `generate` | AI로 사이트 스키마 생성 (`--ref` URL 분석 / `--prompt` 텍스트) |
+| `compare` | 레퍼런스 ↔ 프리뷰 시각 비교 (Playwright 스크린샷 diff) |
+
+### Deployment
+
+| Command | Description |
+|---------|-------------|
+| `deploy` | 에셋 처리 + 스키마 배포 (staging / production) |
+| `diff` | Draft(스테이징)와 Published(프로덕션) 스키마 비교 |
+
+### Templates
+
+| Command | Description |
+|---------|-------------|
+| `template register` | 내 사이트를 마켓플레이스 템플릿으로 등록 |
+| `template sync` | 소스 사이트의 최신 스키마를 템플릿에 반영 |
+| `template status` | 내 템플릿 목록·판매·수익 현황 |
+| `template update` | 템플릿 메타데이터 수정 |
+
+## Workflows
+
+### Create → Preview → Deploy
+
+```
+init ──→ preview ──→ validate ──→ deploy --target staging
+                                        │
+                                        ▼
+                                  diff (staging vs production)
+                                        │
+                                        ▼
+                                  deploy --target production
+```
+
+### AI-Assisted Creation
+
+```
+generate --ref <url> ──→ validate --local ──→ add <블록> ──→ preview
+        or                                                      │
+generate --prompt <text>                              upload ./assets/
+                                                      --replace-in schema.json
+                                                                │
+                                                          compare --ref ──→ deploy
+```
+
+### Template Marketplace
+
+```
+deploy --target production
+        │
+        ▼
+template register ──→ template sync ──→ template status
+```
+
+`--sync-template` 플래그로 배포와 동시에 템플릿 동기화도 가능합니다:
+
+```bash
+npx @saeroon/cli deploy --target production --sync-template
+```
+
+## AI-Powered Development
+
+`init` 시 AI 에디터 컨텍스트 파일이 자동 생성됩니다:
+
+| File | For |
+|------|-----|
+| `CLAUDE.md` | Claude Code 컨텍스트 |
+| `.cursorrules` | Cursor 컨텍스트 |
+| `.vscode/settings.json` | JSON Schema 자동완성 (`$schema` 연동) |
+| `.claude/settings.json` | MCP 서버 설정 (Claude Code) |
+
+스키마 작성부터 배포까지 AI와 함께 작업할 수 있습니다.
+
+### JSON Schema 자동완성
+
+`schema.json`에 `$schema` 필드가 포함되어 VS Code/Cursor에서 **속성 자동완성 + 타입 검증 + 인라인 설명**이 즉시 작동합니다:
+
+```json
+{
+  "$schema": "https://hosting.saeroon.com/schema/v1.20.0/site-schema.json",
+  "schemaVersion": "1.20.0",
+  ...
+}
+```
+
+### Validate 모드
+
+| 모드 | 사용 | 특성 |
+|------|------|------|
+| `--local` | `validate --local` | 오프라인, 구조 검증 3단계 (Schema Structure → Block Properties → Reference Integrity) |
+| 기본 (서버) | `validate` | API 호출, Editor Parity 검증 + SEO·GEO·성능·접근성 품질 점수 |
+
+## Preview Modes
+
+| Mode | Latency | How |
+|------|---------|-----|
+| REST (default) | ~500ms | API 폴링, 브라우저 자동 오픈 |
+| WebSocket | ~300ms | 실시간 양방향 통신 |
+
+```bash
+# REST (기본)
+npx @saeroon/cli preview
+
+# WebSocket (저지연)
+npx @saeroon/cli preview --mode ws
+
+# 디바이스 지정
+npx @saeroon/cli preview --device mobile
+```
+
+## Asset Handling
+
+### `upload` — 독립 에셋 업로드
+
+개발 중 이미지를 CDN에 업로드하고 schema.json 내 경로를 자동 교체합니다.
+
+```bash
+# 단일 파일 → CDN URL 반환
+npx @saeroon/cli upload ./assets/hero.jpg
+
+# 디렉토리 전체 → URL 매핑 테이블 출력
+npx @saeroon/cli upload ./assets/
+
+# schema.json 내 로컬 경로를 CDN URL로 자동 교체
+npx @saeroon/cli upload ./assets/ --replace-in schema.json
+```
+
+### `deploy` — 배포 시 자동 에셋 처리
+
+`deploy` 시 로컬 이미지 파일을 자동으로 감지·해시·업로드합니다.
+
+- SHA-256 기반 중복 검사 — 이미 업로드된 에셋은 스킵
+- 최대 5개 동시 업로드
+- `--dry-run`으로 에셋 리포트만 확인 가능
+
+```bash
+npx @saeroon/cli deploy --dry-run
+```
+
+## Configuration
+
+```
+~/.saeroon/config.json     ← API 키, 기본 설정 (login으로 생성)
+./saeroon.config.json      ← 프로젝트별 siteId, templateId (init으로 생성)
+./schema.json              ← 사이트 스키마 정의
+```
+
+## Block Scaffolding
+
+`add` 명령으로 블록을 빠르게 추가합니다. Block Catalog API에서 기본 props를 가져와 부모 children에 자동 연결합니다.
+
+```bash
+# 기본 — 인터랙티브 부모 선택
+npx @saeroon/cli add heading-block
+
+# 부모 + 위치 지정
+npx @saeroon/cli add image-block --parent root --after hero-1
+
+# ID + 페이지 지정
+npx @saeroon/cli add content-showcase --id insights --parent main --page about
+```
+
+## AI Generation
+
+```bash
+# 레퍼런스 URL → Playwright 스크린샷 → Claude 분석 → schema.json
+npx @saeroon/cli generate --ref https://example.com
+
+# 프롬프트 기반 생성
+npx @saeroon/cli generate --prompt "카페 홈페이지, 모던 스타일, 주황 강조색"
+
+# 출력 파일 지정
+npx @saeroon/cli generate --ref https://example.com --output my-site.json
+```
+
+## Visual Diff
+
+레퍼런스 사이트와 프리뷰 결과를 시각적으로 비교합니다. Playwright + ImageMagick 사용.
+
+```bash
+npx @saeroon/cli compare \
+  --ref https://example.com \
+  --preview https://preview.hosting.saeroon.com/abc \
+  --width 1280 --height 800
+
+# 사전 필요: npx playwright install chromium
+```
+
+## Starters
+
+`init`에서 선택할 수 있는 빌트인 스타터:
+
+| Starter | Description |
+|---------|-------------|
+| `restaurant` | 음식점·케이터링 |
+| `portfolio` | 포트폴리오·이력서 |
+| `business` | 비즈니스·랜딩 |
+| `saas` | SaaS·서비스 소개 |
+
+```bash
+npx @saeroon/cli init --template restaurant
+```
+
+마켓플레이스 템플릿에서도 시작할 수 있습니다:
+
+```bash
+npx @saeroon/cli init --from-template <template-id>
+```
+
+## Security
+
+CLI는 다음 보안 조치를 적용합니다:
+
+- **API 통신**: HTTPS 전용, SSRF 방어 (Private IP 차단), 30초 타임아웃
+- **JSON 파싱**: Prototype Pollution 방어 (`secure-json-parse`)
+- **파일 접근**: Path Traversal 방어 (CWD 외부 접근 차단)
+- **API Key**: 입력 시 마스킹, 설정 파일 저장 (`~/.saeroon/config.json`)
+- **Rate Limit**: 429 응답 시 `Retry-After` 기반 자동 재시도 (최대 3회)
+
+## Requirements
+
+- Node.js 18+
+- Saeroon API Key ([Developer Center](https://hosting.saeroon.com/developer/keys)에서 발급)
+- (선택) Playwright — `compare` 명령용 (`npx playwright install chromium`)
+- (선택) ImageMagick — `compare` 오버레이 diff용
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }