@bifos/nhncloud-cli 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bifos/nhncloud-cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "CLI tool for NHN Cloud services — AI agent & terminal friendly",
   "keywords": [
     "nhncloud",

package/skills/nhncloud-cli/SKILL.md

@@ -3,8 +3,10 @@ name: nhncloud-cli
 description: >-
   NHN Cloud 리소스를 nhncloud CLI로 조회·생성·변경·삭제하거나,
   configure·profile·출력 형식·종료 코드·명령 문법을 확인할 때 사용한다.
+  Claude Code 공개 스킬의 상태를 확인하거나
+  `skills status|install|update|uninstall`로 관리하고 상태별 복구 방법을 안내할 때도 사용한다.
   Log & Crash, Deploy, Compute, Network, Block Storage, Floating IP,
-  Load Balancer, NCR, NKS, NCS 작업을 서비스별 참조와 명령 카탈로그로 안내한다.
+  Load Balancer, NCR, NKS, NCS, API Gateway 작업을 서비스별 참조와 명령 카탈로그로 안내한다.
 ---
 
 # nhncloud-cli
@@ -26,7 +28,8 @@ description: >-
 
 | 작업 | 읽을 파일 |
 |---|---|
-| 설치, `configure`, profile, 출력 모드, 명령 카탈로그, 종료 코드 | [common.md](references/common.md) |
+| CLI 설치, `configure`, profile, 출력 모드, 명령 카탈로그, 종료 코드 | [common.md](references/common.md) |
+| 공개 스킬 상태 확인·설치·갱신·제거와 상태별 복구 | [common.md](references/common.md) |
 | Log & Crash Search v3 커서 검색·scroll 대량 추출·collector 전송 | [logncrash.md](references/logncrash.md) |
 | Deploy 실행·조회·바이너리 전송 | [deploy.md](references/deploy.md) |
 | Compute, VPC, Block Storage, Floating IP | [iaas.md](references/iaas.md) |
@@ -34,4 +37,5 @@ description: >-
 | Container Registry | [ncr.md](references/ncr.md) |
 | Kubernetes Service | [nks.md](references/nks.md) |
 | Container Service | [ncs.md](references/ncs.md) |
+| API Gateway 서비스·리소스·스테이지·배포 조회와 Swagger export | [apigateway.md](references/apigateway.md) |
 | 인증·profile·region·출력·검색 제한 문제 해결 | [troubleshooting.md](references/troubleshooting.md) |

package/skills/nhncloud-cli/references/apigateway.md

@@ -0,0 +1,98 @@
+# API Gateway 조회 안내
+
+`apigateway` 명령군은 API Gateway 서비스, 리소스, 스테이지, 배포 이력을 조회하고 스테이지의 Swagger를 내보낸다.
+현재는 조회만 지원하며 플러그인 적용, 스테이지 수정, 배포, 롤백 같은 쓰기 작업은 지원하지 않는다.
+
+## 인증과 설정
+
+공통 UAK와 API Gateway `appKey`가 필요하다.
+`nhncloud configure --apigateway-appkey <appkey>`로 `profile`의 `apigateway.appkey`를 설정하거나, 명령마다 `--app-key <appkey>`를 넘긴다.
+`--app-key`가 `profile` 설정보다 우선한다.
+
+API 요청은 공통 UAK로 발급한 Bearer 토큰을 `X-NHN-Authorization` 헤더에 담는다.
+표준 `Authorization` 헤더가 아니므로 직접 API를 호출할 때 혼동하지 않는다.
+
+지원 `region`은 `kr1`, `kr2`, `kr3`이며 기본값은 `kr1`이다.
+
+```bash
+nhncloud apigateway service list --region kr1 --app-key <appkey> --json
+```
+
+## 명령
+
+아래 표의 공통 옵션은 `--region <region>`, `--app-key <key>`, `--profile <name>`이다.
+루트 전역 옵션인 `--json`과 `--quiet`도 사용할 수 있다.
+
+| 명령 경로 | 인수 | 명령 옵션 |
+|---|---|---|
+| `nhncloud apigateway service list` | 없음 | 공통 옵션 |
+| `nhncloud apigateway service get` | `<service-id>` | 공통 옵션 |
+| `nhncloud apigateway resource list` | `<service-id>` | 공통 옵션 |
+| `nhncloud apigateway resource parameters` | `<service-id> <resource-id>` | 공통 옵션 |
+| `nhncloud apigateway resource responses` | `<service-id> <resource-id>` | 공통 옵션 |
+| `nhncloud apigateway stage list` | `<service-id>` | 공통 옵션 |
+| `nhncloud apigateway stage swagger` | `<service-id> <stage-id>` | 공통 옵션, `--output <file>`, `--force` |
+| `nhncloud apigateway stage resources` | `<service-id> <stage-id>` | 공통 옵션 |
+| `nhncloud apigateway stage deploy list` | `<service-id> <stage-id>` | 공통 옵션 |
+| `nhncloud apigateway stage deploy latest` | `<service-id> <stage-id>` | 공통 옵션 |
+
+`--quiet`가 식별자를 출력하는 명령은 다음과 같다.
+
+- `service list`·`service get`: `apigwServiceId`
+- `resource list`: `resourceId`
+- `stage list`: `stageId`
+- `stage resources`: `stageResourceId`
+- `stage deploy list`·`stage deploy latest`: `deployId`
+
+`resource parameters`와 `resource responses`는 식별자 출력이 없어 `--quiet`에서 아무것도 출력하지 않는다.
+`stage swagger`는 `--output`을 생략하면 Swagger JSON을 stdout에 출력하고, 지정하면 파일을 새로 만든 뒤 경로를 출력한다.
+기존 파일을 덮어쓰려면 `--force`를 함께 지정한다.
+
+## JSON 구조
+
+API 응답 봉투의 `header`를 검사한 뒤 CLI는 아래 데이터를 꺼내 `--json`으로 출력한다.
+따라서 목록은 JSON 배열, 단건은 JSON 객체로 출력된다.
+특히 서비스 목록의 최상위 키는 `apigwServiceList`이고 서비스 단건은 `apigwService`로 서로 다르다.
+
+| 명령 | API 응답의 최상위 키 | CLI JSON 구조 |
+|---|---|---|
+| `service list` | `apigwServiceList`, `paging` | service 객체 배열 |
+| `service get` | `apigwService` | service 객체 |
+| `resource list` | `resourceList` | resource 객체 배열 |
+| `resource parameters` | `queryStringList`, `headerList`, `formDataList`, `requestBody`, `contentTypeList` | 같은 키를 가진 객체 |
+| `resource responses` | `responseList`, `contentTypeList` | 같은 키를 가진 객체 |
+| `stage list` | `stageList`, `paging` | stage 객체 배열 |
+| `stage swagger` | `swaggerData` | Swagger 객체 |
+| `stage resources` | `stageResourceList` | stage resource 객체 배열 |
+| `stage deploy list` | `stageDeployHistoryList`, `paging` | deploy 객체 배열 |
+| `stage deploy latest` | `latestStageDeployResult` | 최신 deploy 객체 |
+
+`stage list`의 `resourceUpdatedAt`은 배포 시점이 아니다.
+서비스 리소스를 해당 스테이지로 가져온 일시를 뜻하며, 실제 배포 시점은 배포 응답의 `deployedAt`으로 확인한다.
+
+## 목록 수집 방식
+
+페이지네이션은 엔드포인트마다 다르다.
+
+- `service list`, `stage list`, `stage deploy list`는 응답의 `paging.totalCount`까지 다음 페이지를 요청해 전수 수집한다.
+- `resource list`와 `stage resources`는 `paging`이 없으며 한 번의 단일 호출로 전체 목록을 받는다.
+
+모든 목록 명령에 `page`나 `limit`을 임의로 적용하지 않는다.
+
+## 자동화 예시
+
+서비스 식별자를 얻어 스테이지를 조회하고, 선택한 스테이지의 Swagger를 저장소 파일과 비교할 수 있다.
+
+```bash
+SERVICE_ID=$(nhncloud apigateway service list --quiet | head -n 1)
+nhncloud apigateway stage list "$SERVICE_ID" --json
+
+STAGE_ID=$(nhncloud apigateway stage list "$SERVICE_ID" --quiet | head -n 1)
+nhncloud apigateway stage swagger "$SERVICE_ID" "$STAGE_ID" \
+  --output /tmp/apigateway-swagger.json
+
+diff -u specs/apigateway-swagger.json /tmp/apigateway-swagger.json
+```
+
+`service list --quiet`과 `stage list --quiet`은 결과가 없으면 아무것도 출력하지 않는다.
+자동화에서는 빈 식별자를 다음 명령에 넘기기 전에 검사한다.

package/skills/nhncloud-cli/references/common.md

@@ -1,6 +1,6 @@
 # Common Reference
 
-설치, configure, profile, 출력 모드, 에러 코드를 다룬다.
+CLI와 공개 스킬 설치, configure, profile, 출력 모드, 에러 코드를 다룬다.
 서비스별 세부 명령은 각 reference를 읽는다.
 
 ## 설치
@@ -9,6 +9,65 @@
 npm install -g @bifos/nhncloud-cli
 ```
 
+## Claude Code 공개 스킬 관리
+
+전역 설치한 CLI나 `npx`로 패키지의 공개 스킬을 관리 저장소에 설치할 수 있다.
+관리 저장소는 실행 중인 npm 패키지 경로와 분리되므로 `npx`의 임시 패키지 경로가 사라져도 활성 스킬은 유지된다.
+
+```bash
+# 전역 설치한 CLI에서 설치
+nhncloud skills install
+
+# 전역 설치 없이 최신 공개 스킬 설치
+npx --yes @bifos/nhncloud-cli@latest skills install
+
+# 상태 확인 (`nhncloud skills`도 동일)
+nhncloud skills status
+```
+
+npm 패키지와 설치된 공개 스킬은 자동으로 함께 갱신되지 않는다.
+패키지를 먼저 갱신한 뒤 새 CLI로 스킬 갱신을 명시적으로 실행한다.
+
+```bash
+npm install -g @bifos/nhncloud-cli@latest
+nhncloud skills update
+```
+
+상태별 의미와 복구 명령:
+
+| 상태 | 의미 | 복구 명령 |
+|------|------|-----------|
+| `current` | 현재 CLI 버전과 콘텐츠 해시가 일치함 | 조치 없음 |
+| `missing` | 활성 스킬이 설치되지 않음 | `nhncloud skills install` |
+| `outdated` | 이전 버전 또는 기존 패키지·저장소 직접 링크 | `nhncloud skills update` |
+| `broken` | 관리형 링크 또는 기존 패키지 링크의 대상이 없음 | `nhncloud skills update` |
+| `modified` | 관리 저장소 콘텐츠가 설치 매니페스트와 다름 | 내용을 확인한 뒤 `nhncloud skills update --force` |
+| `corrupt` | 관리 저장소 경로나 매니페스트가 손상됨 | 내용을 확인한 뒤 `nhncloud skills update --force` |
+| `unmanaged` | 사용자가 만든 파일·디렉터리 또는 알 수 없는 링크가 설치 경로를 차지함 | 내용을 확인한 뒤 `nhncloud skills update --force` |
+
+`--force`는 사용자 항목 또는 수정·손상된 관리 저장소를 삭제하지 않고 같은 상위 디렉터리에 백업한 뒤 교체한다.
+`nhncloud skills uninstall`은 `~/.claude/skills/nhncloud-cli`의 활성 심볼릭 링크만 제거하며 버전별 관리 저장소는 보존한다.
+설치 경로가 사용자 파일이나 실제 디렉터리이면 제거하지 않는다.
+
+자동화에서는 모든 하위 명령에 전역 출력 옵션을 함께 사용할 수 있다.
+
+```bash
+# 전체 상태 객체
+nhncloud skills status --json
+
+# 상태 토큰 하나만 출력
+nhncloud skills status --quiet
+
+# 갱신 결과의 상태 전이와 백업 경로 확인
+nhncloud skills update --force --json
+
+# 제거 결과 토큰만 출력 (`missing`)
+nhncloud skills uninstall --quiet
+```
+
+`--json`은 상태·변경 여부·백업 경로처럼 자동화에 필요한 필드를 제공한다.
+`--quiet`은 상태 토큰 하나만 stdout에 출력한다.
+
 ## 초기 설정
 
 첫 설정은 `nhncloud configure`로 한다.
@@ -88,6 +147,30 @@ profile 해석 순서:
 API 원본 wrapper를 항상 보존하지 않는다.
 예를 들어 `nhncloud instance get <instance-id> --json`은 `.server.status`가 아니라 `.status`를 읽는다.
 
+## 요청 타임아웃
+
+HTTP 요청의 기본 상한은 30초다.
+조회 기간이 넓은 `logncrash search` 같은 요청은 기본 상한을 넘을 수 있으므로 전역 옵션이나 환경변수로 늘린다.
+
+```bash
+nhncloud logncrash search --query '*' --from 24h --to now --request-timeout 120 --json
+NHNCLOUD_REQUEST_TIMEOUT=120 nhncloud logncrash search --query '*' --from 24h --to now --json
+```
+
+값은 초 단위이며 1~3600 사이의 정수만 허용한다.
+범위를 벗어나면 API 호출 전에 종료 코드 3으로 실패한다.
+우선순위는 다음과 같다.
+
+1. `--request-timeout <sec>`
+2. `NHNCLOUD_REQUEST_TIMEOUT`
+3. 기본값 30초
+
+deploy 바이너리 업로드·다운로드의 상한은 최소 600초를 유지한다.
+전역 값을 600초보다 크게 지정했을 때만 함께 늘어나며, 더 작게 지정해도 바이너리 전송 상한은 낮아지지 않는다.
+
+`instance create --timeout` 과 `ncs workload create --timeout` 은 상태 폴링 대기 시간을 지정한다.
+HTTP 요청 상한과는 다른 설정이므로 서로 대체하지 않는다.
+
 ## Command catalog
 
 `nhncloud commands`는 Commander tree에서 command path, argument, option, description을 출력한다.
@@ -107,19 +190,36 @@ AI 에이전트는 먼저 `commands --json`으로 실제 command path와 option
 |------|---------------------|
 | `commands` | `{ commands: [{ path, description, arguments, options, subcommands }] }` |
 | `logncrash search` | `{ totalItems, pageNumber, pageSize, data, nextCursor? }` |
+| `logncrash export` | 파일 출력 전용. stdout JSON 없음 |
+| `deploy artifacts` | Deploy API `body` 객체 |
+| `deploy server-groups` | Deploy API `body` 객체 |
+| `deploy histories` | Deploy API `body` 객체 |
 | `deploy binary-groups` | `binaryGroups` wrapper를 언랩한 배열 |
 | `deploy binaries` | `{ totalCount, binaries }` |
+| `deploy upload` | `{ downloadUrl, binaryKey }` |
 | `instance list` | `servers` wrapper를 언랩한 server 배열 |
 | `instance get` | `server` wrapper를 언랩한 단일 server |
+| `instance create --wait` | `server` wrapper를 언랩한 단일 server |
 | `instance flavors` | `flavors` wrapper를 언랩한 flavor 배열 |
 | `instance images` | `images` wrapper를 언랩한 image 배열 |
 | `instance availability-zones` | `availabilityZoneInfo` wrapper를 언랩한 배열 |
 | `instance keypairs` | `keypairs[].keypair`를 flatten한 keypair 배열 |
+| `instance volumes` | `volumeAttachments` wrapper를 언랩한 attachment 배열 |
 | `network list` | VPC 배열 |
 | `network subnet list` | subnet 배열 |
 | `volume list` | volume 배열 |
 | `volume get` | 단일 volume 객체 |
+| `volume create` | 단일 volume 객체 |
 | `floatingip list` | Floating IP 배열 |
+| `floatingip create` | 단일 Floating IP 객체 |
+| `loadbalancer list` | Load Balancer 배열 |
+| `loadbalancer get` | 단일 Load Balancer 객체 |
+| `loadbalancer ipacl list` | IP ACL 그룹 배열 |
+| `loadbalancer ipacl get` | 단일 IP ACL 그룹 객체 |
+| `loadbalancer ipacl target list` | IP ACL 대상 배열 |
+| `loadbalancer ipacl create/delete` | 작업 상태와 IP ACL 그룹 UUID 객체 |
+| `loadbalancer ipacl target add/remove` | 대상 UUID와 재바인딩 결과 객체 |
+| `loadbalancer set-ipacl/clear-ipacl` | 작업 상태와 Load Balancer UUID·그룹 UUID 객체 |
 | `ncr list` | `registries` wrapper를 언랩한 registry 배열 |
 | `ncr get` | `registry` wrapper를 언랩한 단일 registry |
 | `ncr images` | repository 배열 |

package/skills/nhncloud-cli/references/troubleshooting.md

@@ -15,13 +15,13 @@
 
 | 서비스 | 비밀 | 인증 방식 |
 |--------|------|-----------|
-| Log & Crash 검색/export | appkey + 공통 UAK id/secret | UAK OAuth `X-NHN-Authorization: Bearer <token>` |
+| Log & Crash 검색/export | appkey 와 공통 UAK id/secret | UAK OAuth `X-NHN-Authorization: Bearer <token>` |
 | Log & Crash send | appkey | body `projectName=appkey`, 인증 헤더 없음 |
-| Deploy | UAK id + secret | OAuth Bearer token |
-| Instance/network/volume/floatingip | tenantId + username + API password | Keystone `X-Auth-Token` |
-| NKS | tenantId + username + API password | Keystone `X-Auth-Token` + container-infra API version |
-| NCR registry | UAK id + secret + NCR appkey | `X-TC-AUTHENTICATION-*` |
-| NCR images/tags | UAK id + secret | HTTP Basic Auth to Harbor REST |
+| Deploy | UAK id 와 secret | OAuth Bearer token |
+| Instance/network/volume/floatingip | tenantId, username, API password | Keystone `X-Auth-Token` |
+| NKS | tenantId, username, API password | Keystone `X-Auth-Token` 과 container-infra API version |
+| NCR registry | UAK id, secret, NCR appkey | `X-TC-AUTHENTICATION-*` |
+| NCR images/tags | UAK id 와 secret | HTTP Basic Auth to Harbor REST |
 
 ## Exit code