@clack-platform/cli 0.1.1 → 0.3.0

package/README.md

@@ -63,9 +63,9 @@ clack login --resume --env dev   # 발급 당시와 같은 환경이어야 한
 | 크리에이터 채널 | `channel get/create/update`, `channel post list/get/create/update/delete`, `channel series list/create/update/delete` |
 | 이미지 | `upload <파일...>` |
 | 설정 | `config get`, `config set <키> <값>` |
-| HTML 콘텐츠 | `content config/list/status/create/upload/complete/preview/submit/withdraw/publish/unpublish` |
+| HTML 콘텐츠 | `content config/list/status/create/update/upload/complete/info-version/preview/submit/withdraw/publish/unpublish` |
 | 에이전트 연결 | `mcp config`, `skills` |
-| 스킬 패키지·관리 | `skill validate`, `skill push`, `skill complete`, `skill submit`, `skill list`, `skill get`, `skill form`, `skill status`, `skill cancel`, `skill release`, `skill deprecate` |
+| 스킬 패키지·관리 | `skill validate`, `skill pack`, `skill editor dev`, `skill push`, `skill complete`, `skill submit`, `skill list`, `skill get`, `skill form`, `skill status`, `skill cancel`, `skill release`, `skill deprecate` |
 | 콘텐츠 서버 키(platform:read/write) | `content server-keys list/revoke` (발급·회전은 크리에이터 센터 전용) |
 | 공유 문서 관리(platform:read/write) | `content shared collections/list/get/hide/delete` |
 | 플랫폼 서버 키 데이터 | `platform usage`, `platform data get`, `platform data list`, `platform data leaderboard`, `platform data put`, `platform data patch`, `platform data delete` |
@@ -138,7 +138,7 @@ clack skills --json
 
 환경변수 참조 형식은 [Claude Code MCP 문서](https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json)와 [Codex MCP 문서](https://developers.openai.com/codex/mcp/)를 따른다. 다른 클라이언트는 해당 제품의 Streamable HTTP·인증 헤더 지원을 확인한다.
 
-원격 MCP는 프로필·상품·게시글·채널 도구 외에 스킬 목록·상세·업로드(`create_skill`→`request_skill_version_upload`→`complete_skill_version`)·심사 제출·공개(`submit_skill_version`, `release_skill_version`, `get_skill_version`), 승인된 HTML 콘텐츠 공개(`publish_creator_content`), 공유 문서 조회·숨김·삭제(`list_shared_documents`, `hide_shared_document`, `delete_shared_document` 등)도 제공한다. 각 도구는 해당 스코프(`skill:*`, `creator-content:publish`, `platform:read`/`platform:write`)를 가진 토큰에만 노출되며, 파괴적 도구는 `confirm:true` 전에는 미리보기만 반환한다. 원격 MCP는 로컬 파일을 읽지 못하므로 스킬 ZIP 전송은 `clack skill push` 또는 로컬 플랫폼 MCP의 `platform_skill_push`를 사용한다.
+원격 MCP는 프로필·상품·게시글·채널 도구 외에 스킬 목록·상세·업로드(`create_skill`→`request_skill_version_upload`→`complete_skill_version`)·심사 제출·공개(`submit_skill_version`, `release_skill_version`, `get_skill_version`), HTML 콘텐츠 정보 수정·정보만 새 버전(`update_creator_content`, `create_creator_info_version`), 승인된 HTML 콘텐츠 공개(`publish_creator_content`), 공유 문서 조회·숨김·삭제(`list_shared_documents`, `hide_shared_document`, `delete_shared_document` 등)도 제공한다. 각 도구는 해당 스코프(`skill:*`, `creator-content:write`·`creator-content:publish`, `platform:read`/`platform:write`)를 가진 토큰에만 노출되며, 파괴적 도구는 `confirm:true` 전에는 미리보기만 반환한다. 원격 MCP는 로컬 파일을 읽지 못하므로 스킬 ZIP 전송은 `clack skill push` 또는 로컬 플랫폼 MCP의 `platform_skill_push`를 사용한다.
 
 에이전트 스킬은 별도 공개 저장소 [clack-project/skills](https://github.com/clack-project/skills)에서 `npx skills add clack-project/skills`로 설치한다. 모두 10종으로, 일반 계정 관리용 6종(`clack-setup`·`clack-products`·`clack-content`·`clack-channel`·`clack-profile`·`clack-mcp`)과 크리에이터용 4종(`clack-creator-content`·`clack-page`·`clack-skill-package`·`clack-platform-data`)이다. 스킬에 필요한 CLI는 0.1.1 이상이다(`clack-mcp`는 CLI 없이도 쓸 수 있고, 설정 출력에 CLI를 쓸 때는 0.1.0 이상). `clack skills`는 설치를 실행하지 않고 안내만 출력한다. 스킬 목록과 스킬별 요구 CLI 버전도 함께 보여 준다. 스킬 하나만 선택 설치할 때는 `-s clack-products`, 여러 개는 `--skill clack-setup clack-creator-content clack-page`처럼 나열하고, 전역 설치에는 `-g`를 사용한다.
 
@@ -162,7 +162,7 @@ GitHub Actions는 Linux·macOS·Windows × Node 20·22에서 `pnpm check`와 패
 |---|---|
 | `config` | 없음(로그인 불필요) |
 | `list`, `status`, `preview` | `creator-content:read` |
-| `create`, `upload`, `complete`, `withdraw` | `creator-content:write` |
+| `create`, `update`, `upload`, `complete`, `info-version`, `withdraw` | `creator-content:write` |
 | `submit` | `creator-content:write`와 `creator-content:publish` 모두 |
 | `publish`, `unpublish` | `creator-content:publish` |
 
@@ -181,6 +181,15 @@ clack content preview --env dev <콘텐츠-UUID> <버전-UUID>
 
 ZIP에 `clack.content.json` 또는 `.clack/`가 있으면 업로드 전에 선언·경로·크기와 프로필 파일 대응을 확인하고 표준 오류에 경고합니다. 선언이 없는 기존 정적 ZIP도 계속 업로드할 수 있습니다. 경고는 업로드를 막지 않으며 서버의 최종 검증·심사 결과를 대신하지 않습니다. 전송 없이 확인하려면 `content upload ... --dry-run`을 사용하세요.
 
+`content update`는 제목·설명·종류·썸네일·메타데이터·태그를 서버 PATCH와 같은 규칙으로 수정합니다(`--title`, `--description`, `--kind`, `--thumbnail-id <썸네일 작업 ID|none>`, `--metadata-mode single|localized`, `--metadata-lang ko|en|none`, `--localized-metadata '<JSON>'|none`, `--tags 쉼표목록`). 지정한 필드만 바뀌고 `--tags`·`--localized-metadata`는 통째 교체됩니다. 단일 메타데이터 모드에서는 제목을 비우면 「제목 없는 콘텐츠」로 표시되고, 언어별(`localized`) 모드에서는 빈 제목을 서버가 거부합니다(400). 썸네일 작업 ID는 `POST /v4/creator/thumbnails` 등으로 발급하며 CLI에는 썸네일 업로드 명령이 없어 보통 `none`(기본 이미지로 되돌리기)만 씁니다. 언어별 메타데이터·태그는 서버 게이트가 켜진 환경에서만 쓸 수 있습니다. 인트로 저장은 개인 액세스 토큰으로 할 수 없어 크리에이터 센터에서만 합니다.
+
+`content info-version <콘텐츠-UUID> <버전-UUID>`는 승인·반려된 버전의 번들을 재사용해 바뀐 콘텐츠 정보만 담은 새 초안 버전을 만듭니다(새로 만들면 201, 이미 있던 초안이면 200이며 응답의 `created`로 구분). 새 버전은 앱 확인과 심사를 다시 받아야 합니다. 서버 게이트가 꺼진 환경에서는 `CONTENT_INFO_VERSION_DISABLED`(409)가 반환되며 `clack content config`의 `info_version.enabled`로 확인할 수 있습니다.
+
+```bash
+clack content update --env dev <콘텐츠-UUID> --title "새 제목" --tags 여행,사진
+clack content info-version --env dev <콘텐츠-UUID> <버전-UUID>
+```
+
 심사는 승인됐지만 아직 공개하지 않은 버전(크리에이터 센터 등록·게시 중단 후 재공개 등)은 `creator-content:publish` 권한으로 공개합니다. 승인 이력·심사 해시·현재 계정과 권한을 공개 시점에 다시 검사합니다.
 
 ```bash
@@ -222,7 +231,7 @@ clack skill deprecate <스킬-UUID> --env dev
 
 ### 스킬 플러그인 정적 검사(plugin-static-v2)
 
-`clack.skill.json`의 `authoring.plugin`으로 제작 화면 플러그인을 선언하면 서버가 번들을 구문 트리(JS·HTML·CSS)로 검사합니다. 위험 기능을 쓰지 않는다고 증명할 수 있는 코드만 통과하고, 판단할 수 없는 코드는 오류로 봅니다. 요약은 다음과 같고 크리에이터 센터 `/creator/skills/help/plugin`에도 같은 안내가 있습니다. 메시지 예제·권한 동의·심사 준비를 포함한 상세 안내의 정본은 크리에이터 가이드 `/guide/reference/templates/editor-plugins`(T09)와 실습 과정 `/guide/courses/center-editor-plugin`(T05)입니다.
+`clack.skill.json`의 `authoring.plugin`으로 제작 화면 플러그인을 선언하면 서버가 번들을 구문 트리(JS·HTML·CSS)로 검사합니다. 위험 기능을 쓰지 않는다고 증명할 수 있는 코드만 통과하고, 판단할 수 없는 코드는 오류로 봅니다. 요약은 다음과 같고 크리에이터 센터 `/ko/creator/skills/help/plugin`에도 같은 안내가 있습니다. 메시지 예제·권한 동의·심사 준비를 포함한 상세 안내의 정본은 크리에이터 가이드 `/ko/guide/reference/templates/editor-plugins`(T09)와 실습 과정 `/ko/guide/courses/center-editor-plugin`(T05)입니다.
 
 - 선언: `bundle`(진입 HTML)·`sha256`·`fields`·`permissions`·`purpose`. 권한은 `getFormSchema`·`getFormValues`·`setFormValues`·`listApprovedAssets`·`requestAssetUpload`만 있고, 권한·필드가 늘면 크리에이터에게 다시 동의를 받습니다.
 - 번들: 파일 50개, 파일당 512 KiB, 전체 2 MiB, 코드 합계 512 KiB 이하. 형식은 html·js·mjs·css·json·png·jpg·webp·gif·woff·woff2만 허용합니다.
@@ -232,6 +241,23 @@ clack skill deprecate <스킬-UUID> --env dev
 - 로드 토큰: iframe 주소의 실행 토큰은 300초 동안 유효하고 번들 안 상대 경로 자원도 같은 토큰으로 검사합니다. 센터는 만료 30초 전에 새 토큰으로 플러그인을 다시 엽니다. 필요한 자원은 첫 로드 때 불러오고, 상태는 `setFormValues`로 저장한 뒤 다시 열렸을 때 `getFormValues`로 이어 갑니다.
 - 심사: 업로드는 구조 오류만 422 `SKILL_PLUGIN_INVALID`로 거부하고, 코드 판정은 줄 번호와 함께 심사 근거로 남깁니다. 관리자가 번들 소스를 직접 확인한 뒤 승인하며 플러그인과 결과 콘텐츠는 자동 공개되지 않습니다. 이전 규칙(v1)으로 검사된 대기 플러그인은 승인할 수 없으니(409 `PLUGIN_STATIC_CHECK_STALE`) 새 버전으로 다시 올립니다.
 
+
+## 스킬 에디터(`authoring.editor`) 개발
+
+스킬이 전체 화면 제작 UI(에디터)를 제공하는 스킬입니다. v1은 크리에이터 센터에서만 쓸 수 있어 `skill list`·`skill get` 결과에 `availability: "센터 전용"`으로 표시됩니다(서버가 `center_only`·`editor`를 내려줄 때).
+
+- `clack skill validate [dir]`: 에디터 번들 구조·한도(파일 50개·파일 512 KiB·전체 2 MiB·코드 512 KiB)·번들 해시, `output.data` 스키마(`output-data.v1`: `pattern` 금지, `uniqueItems`는 스칼라 배열만), 예시 문서를 로컬에서 검사합니다. 지연 로드 의심(`loading="lazy"`·동적 `import()`·CSS `url()`)은 경고로만 알립니다. 에디터 코드의 구문 트리 정적 검사(`editor-static-v1`)와 심사는 서버 판정이 최종입니다.
+- `clack skill pack [dir] [-o out.zip] [--write-manifest]`: ZIP을 만들면서 `authoring.editor.sha256`을 번들 해시로 채웁니다. `--write-manifest`는 채운 값을 디렉터리의 `clack.skill.json`에도 기록합니다. `skill push`도 같은 값을 채워 올립니다.
+- `clack skill editor dev [--editor <dir>] [--document <json>] [--schema <json>]`: SDK의 모의 호스트로 `http://localhost:5170`에서 에디터를 열어 봅니다(로그인 불필요). SDK(`@clack/skill-editor-sdk`)는 `--sdk-dir`, `CLACK_SKILL_EDITOR_SDK_DIR`, 현재 디렉터리에서 설치된 패키지, `CLACK_MONOREPO_DIR/clack-skill-editor-sdk` 순서로 찾으며, SDK에서 `pnpm build`를 먼저 실행해야 합니다.
+
+스킬 에디터 SDK는 아직 npm에 공개되지 않았고 CLI 패키지에도 들어 있지 않습니다. SDK 소스 디렉터리(클랙 내부 작업자는 내부 저장소 체크아웃의 `clack-skill-editor-sdk`)에서 한 번 빌드한 뒤 그 위치를 알려 줍니다.
+
+```sh
+cd <내부 저장소>/clack-skill-editor-sdk && pnpm install && pnpm build
+clack skill editor dev --sdk-dir <내부 저장소>/clack-skill-editor-sdk --editor ./editor --schema ./output/data.schema.json --document ./examples/basic.json
+# 또는 CLACK_MONOREPO_DIR=<내부 저장소> clack skill editor dev ...
+```
+
 ## 플랫폼 전용 PAT 도구(서버 키·공유 문서·콘텐츠 공개)
 
 `platform:read`·`platform:write` 스코프의 개인 액세스 토큰(PAT)으로 내 콘텐츠의 서버 키(`csk_`)를 조회·폐기하고, 이용자가 쓴 공유(shared) 문서를 조회·숨김·삭제합니다. `platform:read`는 조회, `platform:write`는 폐기·숨김·삭제입니다. 서버 키 발급·회전은 PAT보다 오래 사는 비밀값을 만들므로 크리에이터 센터 로그인 세션에서만 할 수 있고, `content server-keys issue`·`rotate`는 센터 안내만 출력합니다. 서버 키 원문은 센터의 발급·회전 응답에만 한 번 담깁니다.
@@ -307,7 +333,7 @@ clack page restore PAGE_ID PREVIOUS_VERSION_ID --revision 1
 clack page disable PAGE_ID --revision 2
 ```
 
-헤더는 `fixed`, `scroll_hide`, `translucent_scroll_hide`, `floating_close` 중 선택한다. 파일과 헤더를 한 버전으로 저장하므로 헤더만 바뀌어도 앱 확인·심사가 필요하다. 승인만으로 자동 적용되지 않으며 복원도 최신 수정 번호가 필요하다. 충돌 시 `status`를 다시 읽고 의도한 버전을 확인한다. 기본 화면 전환은 파일을 삭제하지 않는다. 업로드 완료 요청만 실패하면 오류에 표시된 `clack page complete PAGE_ID UPLOAD_ID`로 재시도할 수 있다.
+헤더는 `fixed`, `scroll_hide`, `translucent_scroll_hide`, `floating_close`(전체 화면, 화면 끝까지), `floating_close_safe_area`(전체 화면, 안전 영역 안쪽) 중 선택한다. 파일과 헤더를 한 버전으로 저장하므로 헤더만 바뀌어도 앱 확인·심사가 필요하다. 승인만으로 자동 적용되지 않으며 복원도 최신 수정 번호가 필요하다. 충돌 시 `status`를 다시 읽고 의도한 버전을 확인한다. 기본 화면 전환은 파일을 삭제하지 않는다. 업로드 완료 요청만 실패하면 오류에 표시된 `clack page complete PAGE_ID UPLOAD_ID`로 재시도할 수 있다.
 
 페이지 파일은 유지하고 헤더만 바꾸려면 `clack page presentation PAGE_ID VERSION_ID --header scroll_hide --color light`를 사용합니다. 새 비공개 버전이 만들어지며 응답의 새 버전 ID로 앱 확인과 심사를 다시 진행합니다. 기존 적용본은 유지됩니다.
 
@@ -334,3 +360,7 @@ clack page status PAGE_ID
 - AI 채우기는 `fill-quote` → `fill` → `fill-status`, 자산 목록은 `assets`, 이미지 작업 조회는 `tool`, 폼 검증은 `validate`를 사용한다.
 
 `image_list` 값은 `[{"asset_id":"UUID","scene":"장면","pose":"구도","mood":"분위기","aspect":"1:1"}]`이며 한 번에 최대 8장, 콘텐츠당 최대 24장을 사용한다. 스킬의 `max_calls`와 플랫폼 설정 중 작은 한도를 적용한다. 참조 이미지 생성은 공급자 검증 전 비활성이며 현재 외모·화풍·팔레트 텍스트로 동일성을 안내한다.
+
+크리에이터 센터·가이드는 `/ko`·`/en` 주소를 사용하며 로그인 상태에서는 앱 언어 설정을 따릅니다. 콘텐츠는 SDK 1.2.0의 `clack.locale` 또는 `window.__clack_env?.locale`에서 앱 언어(`language`)·기기 지역(`region`)·BCP 47 태그(`tag`)를 동기적으로 읽습니다. 번역은 `language`로 고르고 숫자·날짜는 `tag`를 `Intl`에 전달합니다. 기존 `me().locale`은 `ko|en`이고 `me().locale_tag`가 전체 태그입니다.
+
+새 다국어 계약은 개발 센터와 최신 staging 테스터 앱에서 제공하며, 운영에서는 센터 초기 출시와 함께 별도로 활성화합니다. 상세 계약과 예제는 개발 센터의 가이드 P11(`/ko/guide/reference/platform/multilingual-content`)을 확인하세요. 앱 언어 환경값이 없는 구버전 앱에서는 `clack.locale.source`가 `browser`이며 브라우저 언어로 대체됩니다.