@saeroon/cli

v0.4.0

Published

10 days ago

Saeroon Hosting developer CLI — preview, validate, and deploy sites & templates

Downloads

230

0High
0Medium
0Low

saeroon

saeroon hosting cli site-builder schema preview deploy

Quick Start

# 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) | | verify | 프리뷰 URL의 템플릿 렌더 검증 (7 카테고리: render/behavior/visibility/seo/assets/content/tokens) |

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 플래그로 배포와 동시에 템플릿 동기화도 가능합니다:

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에서 속성 자동완성 + 타입 검증 + 인라인 설명이 즉시 작동합니다:

{
  "$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 | 실시간 양방향 통신 |

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

Block Scaffolding

add 명령으로 블록을 빠르게 추가합니다. Block Catalog API에서 기본 props를 가져와 부모 children에 자동 연결합니다.

# 기본 — 인터랙티브 부모 선택
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

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

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

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/verify/<code-slug>
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 통합

Starters

init에서 선택할 수 있는 빌트인 스타터:

| Starter | Description | |---------|-------------| | restaurant | 음식점·케이터링 | | portfolio | 포트폴리오·이력서 | | business | 비즈니스·랜딩 | | saas | SaaS·서비스 소개 |

npx @saeroon/cli init --template restaurant

마켓플레이스 템플릿에서도 시작할 수 있습니다:

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에서 발급)
(선택) Playwright — compare 명령용 (npx playwright install chromium)
(선택) ImageMagick — compare 오버레이 diff용

License

MIT