npm package: @saeroon/cli
Description: Saeroon Hosting developer CLI — preview, validate, and deploy sites & templates
Latest version: 0.2.19

<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` 텍스트) |
| `analyze` | 레퍼런스 URL 분석 (스크린샷 + DOM/CSS + 비디오 감지 + Pexels 스톡 매칭) |
| `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

```
analyze <url> ──→ generate --ref <url> ──→ validate --local ──→ 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              ← 사이트 스키마 정의

# 환경변수
SAEROON_API_KEY            ← Saeroon API Key
PEXELS_API_KEY             ← Pexels API Key (비디오 스톡 검색, 무료 — pexels.com/api)
```

## 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
```

## Reference Analysis

```bash
# 레퍼런스 URL 분석 (스크린샷 4장 + DOM/CSS + 비디오 감지)
npx @saeroon/cli analyze https://example.com

# 업종 지정 (비디오 검색 키워드에 사용)
npx @saeroon/cli analyze https://example.com --industry cafe

# Pexels API Key 설정 시 비디오 자동 매칭 (video-stock-map.json 생성)
# 설정: PEXELS_API_KEY 환경변수 또는 .saeroon/config.json의 pexelsApiKey
```

## 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