---
name: zik-deploy
description: zik(직) 서비스로 정적 웹사이트를 배포한다. 사용자가 "zik으로 배포", "zik.kr에 올려줘", "이 사이트 배포해줘"(zik 맥락) 등을 요청하면 사용. GitHub·계정 없이 HTTP 업로드만으로 https://<이름>.zik.kr 주소가 생성된다.
---

# zik 배포

zik은 정적 파일(HTML/CSS/JS/이미지)을 zip으로 업로드하면 즉시 `https://<site>.zik.kr` 로 서빙하는 서비스다. 압축·업로드 방법은 실행 환경에 맞게 스스로 판단하라. 아래는 API 계약과 수행 규칙이다.

## API

### 배포
```
POST https://zik.kr/api/deploy
Content-Type: multipart/form-data
필드: site=<사이트이름>, key=<비밀키>, file=<zip파일>
```
성공: `{"ok": true, "url": "https://<site>.zik.kr/", "new": <신규여부>}`

### 이름 사용 가능 확인 (선택)
```
GET https://zik.kr/api/check/<site>   →  {"available": true|false}
```
`false`여도 자신의 key로 만든 사이트라면 재배포 가능.

## 제약

- `site`: `^[a-z0-9][a-z0-9-]{1,30}$` (영소문자·숫자·하이픈, 2~31자). www, api, admin 등 예약어 불가. 선착순 소유.
- `key`: 6자 이상. 최초 배포 시 소유권이 이 key에 귀속되며, 재배포에는 동일 key 필수.
- zip 최대 10MB, 파일 최대 100개, 정적 파일만. `index.html` 필수.
- 재배포는 기존 파일 전체 교체(병합 아님).
- 업로드된 파일의 유효기간은 최대 1주일. 이후 삭제될 수 있으므로 계속 유지하려면 그 전에 재배포 필요.

## 수행 규칙

1. **key 관리**: `~/.zik-key` (Windows: `%USERPROFILE%\.zik-key`) 파일이 있으면 그 값을 사용. 없으면 랜덤 영숫자 32자를 생성해 이 파일에 저장한 뒤 사용. 신규 생성한 경우 사용자에게 "key를 ~/.zik-key에 저장했으며, 분실하면 이 사이트 이름으로 재배포할 수 없다"고 반드시 안내.
2. **배포 전 점검**: 대상 폴더에 `index.html`이 있는지, 파일 수·용량이 제한 내인지 확인. site 이름이 미정이면 폴더명 기반으로 규칙에 맞게 제안하고 `/api/check`로 확인.
3. **압축**: 폴더 자체가 아니라 폴더의 내용물을 zip 루트에 담아라. (최상위 폴더 하나로 감싸진 zip도 서버가 벗겨내지만 내용물 압축이 안전.) `.git`, `node_modules` 등 불필요 파일은 제외.
4. **업로드**: 위 API로 POST. Windows PowerShell에서는 `curl`이 Invoke-WebRequest 별칭이므로 반드시 `curl.exe`를 사용.
5. **완료 보고**: 사용자에게 URL을 알려주고, 첫 방문 시 경고 페이지가 먼저 나오며 [계속하기] 버튼을 누르면 사이트가 보인다(2시간 유지)는 점, 그리고 사이트는 최대 1주일 후 만료되므로 계속 쓰려면 재배포해야 한다는 점을 안내.

## 동적 기능 (zik API)

배포된 모든 사이트는 서버 코드 없이 자신의 오리진 아래 API를 클라이언트 JS(`fetch`)로 쓸 수 있다. **사이트를 먼저 배포해야 사용 가능하다** (미배포 사이트 이름으로 호출하면 404):

- **DB**: `POST /zik-api/v1/db/{컬렉션}` — 방명록·폼·댓글용 JSON 문서 저장/조회. 스키마 없음, 컬렉션 자동 생성. (문서 8KB, 사이트당 10MB)
- **파일**: `POST /zik-api/v1/file` 업로드 → 반환된 `/zik-user-uploads/...` URL을 `<img src>` 등에 바로 사용. (파일 2MB, 사이트당 업로드 파일 총 50MB — 배포 zip의 10MB 제한과는 별개)
- 인증은 방문자 경고 확인 쿠키로 자동 처리되며 로그인·토큰 없음. `zik-`로 시작하는 파일/폴더 이름은 예약어라 배포 zip에 쓸 수 없다.

이 기능을 구현할 때는 반드시 상세 스펙을 참고하라: **https://zik.kr/api/SKILL.md** (전체 API 계약, fetch 예시, 제한, 에러 표)

## 에러 대처

| 상태 | 의미 | 에이전트 행동 |
|---|---|---|
| 400 | 이름 규칙 위반 / zip에 파일 없음 | 이름 수정 또는 zip 내용 확인 후 재시도 |
| 403 | key 불일치 (이미 다른 key가 소유) | `~/.zik-key`의 key로 재시도. 그래도 403이면 사용자에게 알리고 다른 이름 제안 |
| 413 | 10MB 또는 100개 초과 | 큰 파일(원본 이미지·영상·소스맵 등) 제외/압축 후 재시도 |
| 5xx | 서버 오류 | 잠시 후 1회 재시도, 실패 시 사용자에게 보고 |