Quick Start

기본은 정적 트랙 — raw HTML/CSS/JS 사이트를 스키마·빌드 단계 없이 배포합니다.

# 1. 인증 (최초 1회)
npx @saeroon/cli login

# 2. 프로젝트 생성 — index.html 스켈레톤 + 포인터형 CLAUDE.md / .cursorrules
npx @saeroon/cli init

# 3. index.html 을 편집한 뒤 배포 (Draft = 검색 비노출)
npx @saeroon/cli deploy .

# 4. 라이브 발행
npx @saeroon/cli site publish <slug>

폼·회원·게시판은 HTML 요소에 data-saeroon-* 속성만 붙이면 배포 시 자동 연결됩니다. 전체 속성 계약: https://developers.saeroon.com/docs/attributes.md

Commands

Auth

| Command | Description | |---------|-------------| | login | API 키 등록 및 연결 확인 | | whoami | 현재 인증 상태 및 프로젝트 설정 확인 |

Development

| Command | Description | |---------|-------------| | init | 새 프로젝트 생성 — 정적 트랙(index.html + 포인터 컨텍스트) | | preview | 스키마 파일 감시 + 실시간 미리보기 (REST / WebSocket) | | upload | 이미지를 Saeroon CDN에 업로드. --replace-in으로 경로 자동 교체 | | analyze | 레퍼런스 URL 분석 (스크린샷 + DOM/CSS + 비디오 감지 + Pexels 스톡 매칭) | | compare | 레퍼런스 ↔ 프리뷰 시각 비교 (Playwright 스크린샷 diff) | | verify | 프리뷰 URL의 템플릿 렌더 검증 (7 카테고리: render/behavior/visibility/seo/assets/content/tokens) |

Deployment

| Command | Description | |---------|-------------| | deploy | 배포. 두 형식 — ① deploy <folder>: raw HTML/CSS/JS 정적 사이트 직배포(아래 Static Hosting) ② deploy --target staging\|production: 스키마 사이트 배포 | | diff | Draft(스테이징)와 Published(프로덕션) 스키마 비교 |

Static Hosting (raw HTML/CSS/JS)

AI(Claude / v0 / Bolt) 출력 또는 직접 작성한 raw 정적 사이트를 한 줄로 배포한다. 스키마 변환 단계 0.

npx @saeroon/cli deploy ./my-site          # 신규 — 이름/slug 자동 prompt → URL 즉시
npx @saeroon/cli deploy ./my-site --site-id <id>   # 기존 사이트 업데이트

deploy <folder> 자동 처리: symlink 해소 + 민감 파일 차단 + content-hash manifest(변경 파일만 업로드) + Form Auto-Attach(data-saeroon-form) + 회원/게시판 SDK inject(data-saeroon-auth/data-saeroon-post-*) + R2 업로드 + manifest atomic swap.

| Command | Description | |---------|-------------| | feature attach form --site <id> | 정적 사이트에 폼 백엔드 연결 + API key 발급 (booking / collection = 로드맵) | | board list / board apply <slug> / board export | 게시판 템플릿 조회·적용·export | | domain connect <domainId> --site <id> | 구매/이전 도메인 연결 (zone 생성 + NS 위임 자동) | | domain connect-external <siteId> <domain> | 직접 보유 도메인(BYO) 추가 + NS 발급 | | domain verify <domainId> [--watch] | BYO 검증/활성화 (zone active 시 무료 SSL) | | domain list / domain status <domainId> | 도메인 목록·상세 조회 |

Templates

| Command | Description | |---------|-------------| | template register | 내 사이트를 마켓플레이스 템플릿으로 등록 | | template sync | 소스 사이트의 최신 스키마를 템플릿에 반영 | | template status | 내 템플릿 목록·판매·수익 현황 | | template update | 템플릿 메타데이터 수정 |

Workflows

Template Marketplace

deploy --target production
        │
        ▼
template register ──→ template sync ──→ template status

--sync-template 플래그로 배포와 동시에 템플릿 동기화도 가능합니다:

npx @saeroon/cli deploy --target production --sync-template

AI-Powered Development

init 시 AI 에디터 컨텍스트 파일이 자동 생성됩니다.

정적 트랙 (기본) — 포인터형 컨텍스트:

| File | For | |------|-----| | CLAUDE.md | Claude Code 컨텍스트 (정적 워크플로 + 핵심 data-saeroon 속성 + 계약 문서 링크) | | .cursorrules | Cursor 컨텍스트 (동일) | | index.html | data-saeroon-* 예시 주석이 담긴 스켈레톤 |

편집부터 배포까지 AI와 함께 작업할 수 있습니다.

Preview Modes

| Mode | Latency | How | |------|---------|-----| | REST (default) | ~500ms | API 폴링, 브라우저 자동 오픈 | | WebSocket | ~300ms | 실시간 양방향 통신 |

# REST (기본)
npx @saeroon/cli preview

# WebSocket (저지연)
npx @saeroon/cli preview --mode ws

# 디바이스 지정
npx @saeroon/cli preview --device mobile

Asset Handling

upload — 독립 에셋 업로드

개발 중 이미지를 CDN에 업로드하고 schema.json 내 경로를 자동 교체합니다.

# 단일 파일 → 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으로 에셋 리포트만 확인 가능

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)

Reference Analysis

# 레퍼런스 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

Visual Diff

레퍼런스 사이트와 프리뷰 결과를 시각적으로 비교합니다. Playwright + ImageMagick 사용.

npx @saeroon/cli compare \
  --ref https://example.com \
  --preview https://preview.hosting.saeroon.com/abc \
  --width 1280 --height 800

# 사전 필요: npx playwright install chromium

Render Verify (0.3.0)

프리뷰 URL의 실제 렌더 결과를 스키마와 비교해 템플릿 영역을 검증합니다. 스크린샷 없이 구조화된 Issue 리포트 — AI 파이프라인과 CI에 바로 투입 가능.

# 기본 호출
npx @saeroon/cli verify https://preview.hosting.saeroon.com/abc schema.json

# 다중 페이지 자동 순회 (스키마의 모든 pages[].path)
npx @saeroon/cli verify https://preview.hosting.saeroon.com/abc schema.json --all-pages

# 특정 페이지만
npx @saeroon/cli verify https://site.saeroon.com schema.json --page / --page /about

# 3종 포맷 동시 생성 (json + junit + html)
npx @saeroon/cli verify <url> schema.json \
  --output-dir .saeroon/verify/$(date +%s) \
  --format json,junit,html

# CI용 — error만 실패, warn은 통과
npx @saeroon/cli verify <url> schema.json --fail-level error

# 외부 스테이징 환경 (saeroon.com 도메인 밖) 허용
npx @saeroon/cli verify https://stage.myclient.com schema.json --allow-host "*.myclient.com"

# JSON만 stdout으로 (파일 출력 없음)
npx @saeroon/cli verify <url> schema.json --json

검증 카테고리 (7종)

• render — 스키마 blockId vs DOM [data-block-id] + semanticTag 일치 + repeat 인스턴스 개수
• behavior — data-behavior 매핑 + config JSON 파싱 + config 스키마 타입 검증 + ARIA 속성(toggle/dialog)
• visibility — data-vr-pending="true" 마크업이 스키마 visibilityRules와 정합한지
• seo — <title>, meta[name="description"], og:*
• assets — 템플릿 참조 image/media/font/stylesheet 4xx/5xx
• content — heading-block/text-block/button-block props.text ↔ DOM innerText
• tokens — :root { --* } CSS 변수 정의 존재 (디자인 토큰 파이프라인 헬스체크)

Issue 모델

각 이슈는 { category, code, severity, message, blockId?, details?, fix, docsLink } 구조.

• severity: error | warn | info
• fix: 해결 방법 한 줄
• docsLink: https://developers.saeroon.com/docs (Issue 코드는 URL fragment 로 부착)
• code: 안정적 식별자 (예: render.block.missing, behavior.config.invalid)

보안 가드 (0.3.0)

• URL allowlist 기본: saeroon.com, *.saeroon.com, *.hostings.saeroon.com
• --allow-host <pattern>로 확장 (예: *.staging.example.com)
• 내부 IP/루프백/링크로컬 차단 (SSRF 방어) — --allow-host * 지정해도 차단됨
• file://, data://, javascript:// 프로토콜 차단
• 리포트에서 URL query의 token/key/secret/password + Authorization/Cookie 헤더 자동 마스킹

주요 플래그

| Flag | 역할 | |---|---| | --all-pages | 스키마의 모든 pages[].path 순회 | | --page <path> | 특정 페이지만 (여러 번 지정 가능) | | --fail-level error\|warn\|info | 이 심각도 이상일 때 exit 1 (기본 warn) | | --format json,junit,html | 포맷 선택 (콤마 구분) | | --output-dir <dir> | 리포트 디렉토리 (기본 .saeroon/verify/<timestamp>/) | | --output <path> | 단일 JSON 파일만 출력 | | --allow-host <pattern> | 추가 허용 호스트 (여러 번 지정) | | --allow-insecure | http:// 허용 (로컬 개발 전용) | | --viewport <WxH> | 뷰포트 (기본 1280x800) | | --json | stdout JSON만 (파일 출력 없음) |

플랫폼/인프라 영역(SSR, /api/, CSP, RSC 스트림 등)은 검사 대상이 아닙니다 — 새로온 플랫폼 운영 책임 영역이며, 별도의 내부 도구로 다룹니다.

Exit code: pass=0, fail=1, error=2.

# 사전 필요: npx playwright install chromium

Coming soon (0.3.x / 0.4.0)

• --local <schema> — deploy 없이 스키마 → 정적 HTML → 검증 (universal-renderer workspace 연동)
• inspect 신규 커맨드 — Playwright trace ZIP (HAR 포함)
• Pattern 확장 결과 검증 (2-Layer Pattern System)
• Feature provider 마크업 검증 (shop/booking/auth/board/kipris)
• Behavior 런타임 동작 검증 (click/keypress 시뮬레이션)
• Visual regression + Lighthouse 통합

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 22+ (package.json engines)
• Saeroon API Key (Developer Center에서 발급)
• (선택) Playwright — compare 명령용 (npx playwright install chromium)
• (선택) ImageMagick — compare 오버레이 diff용

License

MIT