@bifos/nhncloud-cli 0.15.0 → 0.17.0

package/package.json

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

package/skills/nhncloud-cli/SKILL.md

@@ -20,7 +20,7 @@ description: >-
 5. 결과는 stdout의 구조화 데이터로 판정하고 stderr는 진행 상황과 진단에 사용한다.
 6. 실패하면 [troubleshooting.md](references/troubleshooting.md)에서 종료 코드와 인증 모델을 확인한다.
 
-`--quiet`는 해당 명령이 식별자 출력을 문서화한 경우에만 사용한다.
+`--quiet`는 해당 명령이 핵심 값 한 줄 출력을 문서화한 경우에만 사용한다.
 명령 문법이나 응답 형태를 추측하지 않는다.
 비밀값과 실제 사용자 리소스 ID는 문서·이슈·보고서에 남기지 않고 placeholder로 바꾼다.
 

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

@@ -73,6 +73,11 @@ nhncloud skills uninstall --quiet
 첫 설정은 `nhncloud configure`로 한다.
 대화형 마법사가 profile, UAK, 서비스별 자격증명을 묻고 저장 전 연결을 테스트한다.
 
+공공망 profile에는 `~/.nhncloud/credentials.json`의 해당 profile 블록에 `"environment": "gov"`를 명시한다.
+기존 profile은 이 필드를 생략하면 일반망을 사용한다.
+현재 공공망 endpoint 선택 대상은 OAuth, Deploy, NCR, IaaS이며 공공망에서 주소가 확인되지 않은 API는 호출하지 않는다.
+`configure`의 연결 테스트는 일반망 주소를 사용한다. 공공망 자격증명은 `--no-verify`로 저장하고, profile에 `environment`를 추가한 뒤 조회 명령으로 확인한다.
+
 ```bash
 nhncloud configure
 nhncloud configure --profile staging
@@ -141,7 +146,7 @@ profile 해석 순서:
 |--------|------|------|
 | 없음 | 사람이 읽기 좋은 table | 터미널 확인 |
 | `--json` | JSON stdout | 파싱, 자동화, AI 에이전트 |
-| `--quiet` | 핵심 식별자만 stdout | 단순 체이닝 |
+| `--quiet` | 명령이 문서화한 핵심 값 한 줄을 stdout으로 출력 | 단순 체이닝 |
 
 `--json`은 CLI 출력 계약이다.
 API 원본 wrapper를 항상 보존하지 않는다.
@@ -250,6 +255,6 @@ NKS 쓰기 명령 중 생성, resize, 설정 변경, 노드 action, 애드온
 
 - 조회는 먼저 `--json`으로 실행하고 필요한 id를 추출한다.
 - 쓰기 명령 전에 `--profile`, `--region`, 대상 id를 명시한다.
-- `--quiet`는 해당 명령이 식별자 출력을 문서화한 경우에만 사용한다.
+- `--quiet`는 해당 명령이 핵심 값 한 줄 출력을 문서화한 경우에만 사용한다.
 - 삭제 명령은 비대화형 환경에서 `--yes`를 명시한다.
 - stdout은 데이터로만 취급하고, 진행 메시지는 stderr로 분리된다고 가정한다.

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

@@ -8,6 +8,8 @@ UAK를 OAuth `client_credentials`로 교환한 Bearer token으로 인증하고,
 `~/.nhncloud/credentials.json`에 profile 공통 `userAccessKey`가 필요하다.
 appkey는 `nhncloud configure --deploy-appkey <key>`로 profile에 설정한다.
 `nhncloud configure` 사용을 권장한다.
+공공망에서는 profile에 `"environment": "gov"`를 명시하고 `--profile`로 선택한다.
+공공망 Deploy API 주소는 `https://api-tcd.gov-nhncloudservice.com`이다.
 
 배포 좌표(아티팩트·서버그룹·시나리오 등)는 config에 두지 않는다.
 매 호출마다 명령 옵션으로 넘긴다.
@@ -57,6 +59,7 @@ nhncloud deploy run --artifact-id <id> --server-group-id <id> --scenario-ids <id
 ```bash
 nhncloud deploy artifacts --json
 nhncloud deploy server-groups --artifact-id <id> --json
+nhncloud deploy scenarios --artifact-id <id> --server-group-id <id> --json
 nhncloud deploy histories --artifact-id <id> --json
 nhncloud deploy binary-groups --artifact-id <id> --json
 nhncloud deploy binaries --binary-group <key> --artifact-id <id> --json
@@ -68,11 +71,13 @@ nhncloud deploy binaries --binary-group <key> --artifact-id <id> --json
 |------|------|
 | 아티팩트 목록 | `deploy artifacts` |
 | 서버그룹 목록 | `deploy server-groups --artifact-id <id>` |
+| 시나리오 목록 | `deploy scenarios --artifact-id <id> --server-group-id <id>` |
 | 배포 이력 | `deploy histories --artifact-id <id>` |
 | 바이너리 그룹 목록 | `deploy binary-groups --artifact-id <id>` |
 | 바이너리 목록 | `deploy binaries --binary-group <key> --artifact-id <id>` |
 
 `deploy binary-groups --json`은 `binaryGroups` wrapper를 언랩한 배열이다.
+`deploy scenarios --json`은 시나리오 배열이며, `--quiet`은 시나리오 ID를 한 줄씩 출력한다.
 `deploy binaries --json`은 `{ totalCount, binaries }` 객체다.
 
 ## 바이너리 전송
@@ -101,11 +106,9 @@ nhncloud deploy histories --artifact-id <id> --json | jq '.[0] | {deployKey, dep
 | 상황 | exit code |
 |------|-----------|
 | UAK 누락 또는 profile에 deploy appkey 없음 | 4 |
-| 좌표 옵션(`--artifact-id`·`--server-group-id`·`--scenario-ids`) 누락 | 3 |
+| 필수 옵션 누락(좌표, `--binary-group`·`--binary-key`·`--file`·`-o`) | 3 |
 | OAuth 인증 실패 | 2 |
 | Deploy API 오류 또는 봉투 실패 | 1 |
-| `--binary-group`·`--binary-key`·`--file`·`-o` 누락 | 1 |
 
-마지막 두 행이 같은 값인 것은 우연이 아니라 필수 옵션을 강제하는 방식이 둘이기 때문이다.
-좌표 옵션은 CLI 가 직접 검증해 3 을 내고, 나머지 필수 옵션은 Commander 가 거부해 1 을 낸다.
-종료 코드로 분기하는 자동화는 이 차이를 알아야 한다.
+필수 옵션 누락은 검증 방식과 관계없이 종료 코드 3으로 끝난다.
+Commander의 조기 검증과 명령 내부 검증은 오류 문구가 다를 수 있지만 자동화는 같은 입력 오류로 처리할 수 있다.

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

@@ -2,6 +2,8 @@
 
 `instance`, `network`, `volume`, `floatingip`은 IaaS 자격증명과 Keystone token을 공유한다.
 region이 중요하면 `--region <region>`을 명시한다.
+공공망 profile에는 `"environment": "gov"`를 명시한다.
+공식 문서에 endpoint가 있는 공공망 IaaS region은 `kr1`과 `kr2`다.
 
 ## IaaS 설정
 

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

@@ -1,8 +1,8 @@
 # Log & Crash Reference
 
-`logncrash` 명령군은 Log & Crash Search v3 커서 검색, scroll export, collector 전송을 다룬다.
+`logncrash` 명령군은 Log & Crash Search v3 조회 토큰 확인, 커서 검색, scroll export, collector 전송을 다룬다.
 
-검색과 export에는 profile의 logncrash appkey와 공통 UAK가 필요하다.
+조회 토큰 확인, 검색과 export에는 profile의 logncrash appkey와 공통 UAK가 필요하다.
 CLI가 UAK를 OAuth 토큰으로 교환해 Bearer 인증을 적용한다.
 `send`는 별도 collector 계약이므로 Search v3 전환의 영향을 받지 않는다.
 
@@ -96,30 +96,43 @@ cursor는 파싱하거나 인코딩을 바꾸지 않고 받은 문자열 그대
 이 응답은 HTTP 200에 봉투 오류로 오며 500과는 다른 원인이다.
 CLI는 둘을 구분해 안내한다.
 
-```text
-조회 횟수 제한에 걸렸습니다. 시간을 두고 다시 실행하세요. 검색 기간을 좁혀도 풀리지 않습니다.
+검색 전에는 남은 조회 토큰을 직접 확인할 수 있다.
+
+```bash
+nhncloud logncrash available-token
+nhncloud logncrash available-token --json
+nhncloud logncrash available-token --quiet
 ```
 
-**검색 기간을 좁히는 것은 해법이 아니다.**
-호출 한 번의 비용이 조회 기간에 거의 비례하지 않기 때문이다.
-같은 구간을 여러 창으로 나누면 오히려 제한을 더 빨리 소모한다.
-시간을 두고 다시 실행해야 한다.
+기본 출력은 남은 조회 토큰과 양수가 될 때까지의 추정 대기 시간을 표로 보여 준다.
+`--json`은 `{ availableToken, estimatedWaitSeconds }`를 출력하고, `--quiet`은 `availableToken` 숫자만 출력한다.
+잔량이 양수이면 `estimatedWaitSeconds`는 `null`이다.
+
+`search`와 `export`는 실제 검색 요청마다 먼저 잔량을 확인한다.
+잔량이 0 이하면 검색 요청을 보내지 않고 종료 코드 1로 끝낸다.
+추정 대기 시간은 관측한 회복 속도 1.6 token/s로 잔량이 양수가 될 때까지를 계산한 값이다.
+서버가 보장한 값이 아니며, 같은 프로젝트의 다른 호출이 잔량을 쓰면 달라질 수 있다.
+
+잔량이 양수여도 다음 검색의 비용까지 충분하다는 뜻은 아니다.
+호출 비용을 사전에 계산할 공식 규칙이 없고, 성공한 한 번의 호출이 잔량을 음수로 만들 수 있다.
+잔량 조회가 실패하면 CLI는 검색을 강행하지 않고 그 오류로 끝난다.
+
+**검색 기간만 좁히는 것을 보장된 해법으로 보지 않는다.**
+공식 가이드는 기간, 크기와 쿼리 복잡도가 함께 비용에 영향을 준다고 설명하지만 산정식은 공개하지 않는다.
+기간을 나누면 한 호출의 비용이 줄 수 있지만 호출 수가 늘어난다.
+`available-token`의 추정 시간을 확인한 뒤 사용자가 다시 실행해야 한다.
 
 CLI는 자동으로 다시 시도하지 않는다.
-서버가 남은 시간을 알려주지 않아 얼마나 기다릴지 알 수 없고, 회복이 느려 대기가 실효를 갖기 어렵다.
+추정값은 서버 계약이 아니므로 CLI가 그 시간만큼 자동으로 기다리지는 않는다.
 
 ### 반복 조회를 설계할 때
 
 주기적으로 로그를 수집하는 자동화라면 아래를 전제로 짠다.
 실패한 워크플로에서 되짚어 얻은 것이다.
 
-**비용을 정하는 것은 호출 횟수와 쿼리의 선택성이다.** 조회 기간이 아니다.
-기간을 6배로 늘려도 한 호출의 비용은 거의 그대로였다.
-반면 `*` 대신 필드로 좁힌 쿼리는 같은 조회를 10분의 1 이하로 끝냈다.
-
-**그래서 쿼리를 먼저 좁힌다.** 기간을 좁히는 것보다 효과가 크다.
-`logSource`·`logLevel`·`host` 처럼 인덱스가 있는 필드로 걸러내면 호출당 비용이 급감한다.
-`*` 로 넓게 받아 로컬에서 거르는 방식은 제한을 가장 빨리 소모한다.
+**호출 비용을 이전 실측값으로 예측하지 않는다.**
+같은 프로젝트에서도 좁힌 쿼리의 비용이 호출당 약 85에서 약 21,870까지 다르게 관측됐다.
+쿼리와 기간은 필요한 데이터 범위에 맞추되, 다음 호출 전에 `available-token`을 다시 확인한다.
 
 **전수 수집은 `search` 반복이 아니라 `export` 한 번이다.**
 `search`를 페이지마다 부르면 호출 수가 페이지 수만큼 늘어난다.
@@ -131,19 +144,19 @@ Search v3에서 `--page`는 `0`만 받는다.
 100건을 넘겨 받아야 하면 `export`를 쓴다.
 
 **재시도할 때 오류를 구분한다.**
-조회 횟수 제한과 서버 500은 기다리면 풀리지만, 입력 오류와 설정 오류는 풀리지 않는다.
-구분하지 않고 백오프를 걸면 풀리지 않는 오류에 대기 시간만 쓴다.
+조회 횟수 제한은 토큰 회복 뒤 다시 시도할 수 있고, 서버 500은 export의 기간 분할 대상이다.
+입력 오류와 설정 오류는 기다려도 풀리지 않는다.
 
 | 종료 코드 | 의미 | 기다리면 풀리나 |
 |---|---|---|
-| 1 | API 오류, 봉투 실패 (조회 횟수 제한 포함) | 그렇다 |
+| 1 | API 오류, 봉투 실패 (조회 횟수 제한 포함) | 오류에 따라 다르다 |
 | 2 | 인증 실패 | 아니다 |
 | 3 | 입력 오류 | 아니다 |
 | 4 | 설정 오류 | 아니다 |
 
-**백오프는 분 단위로 짧게 잡지 않는다.**
-회복이 느려서, 넓은 쿼리로 소모한 뒤에는 몇십 초나 몇 분을 기다려도 한 번 호출할 몫이 돌아오지 않는다.
-좁은 쿼리라면 훨씬 빨리 회복되지만, 정확한 값은 프로젝트와 쿼리마다 달라 넉넉히 잡는 편이 안전하다.
+**고정 간격 대신 매번 잔량을 확인한다.**
+호출 비용은 쿼리마다 다르고 한 번에 큰 음수로 내려갈 수 있다.
+짧은 고정 간격은 아직 회복하지 않은 상태에서 같은 실패만 반복할 수 있다.
 
 ## 대량 export
 
@@ -180,7 +193,7 @@ scroll 시작이나 계속 요청에서 서버가 500 응답을 반환하면 CLI
 
 ### 중단된 추출 이어받기
 
-추출이 실패하면 `--output`은 만들어지지 않는다.
+조회가 끝나기 전에 추출이 실패하면 `--output`은 만들어지지 않는다.
 대신 그때까지 받은 결과가 `<output>.partial`에 남고, 위치와 이어받는 방법을 stderr로 알린다.
 
 ```text
@@ -196,6 +209,22 @@ scroll 시작이나 계속 요청에서 서버가 500 응답을 반환하면 CLI
 
 부분 결과를 남기지 못하면 CLI가 그 사실을 경고로 알리고 원래 오류를 그대로 낸다.
 
+### 조회 완료 뒤 복구 파일
+
+모든 데이터를 받은 뒤 로컬 파일 처리에 실패했다면 API를 다시 호출하지 않는다.
+stderr에 나온 복구 경로로 전체 결과를 확인한다.
+
+| 복구 파일 | 상태 | 처리 방법 |
+|---|---|---|
+| `<output>.<id>.complete` | 모든 데이터를 받고 파일 형식까지 완성했지만 최종 경로 교체에 실패 | API를 다시 호출하지 않고 원하는 최종 경로로 옮겨 그대로 사용 |
+| `<output>.<id>.unfinalized` | 모든 데이터를 받았지만 JSON 배열 마무리에 실패 | API를 다시 호출하지 않고 마지막 `]`를 확인한 뒤, JSON 파싱이 성공하면 원하는 최종 경로로 이동 |
+
+`<id>`는 실행별 고유값이다.
+`.complete`와 `.unfinalized`는 앞선 복구 파일을 덮어쓰지 않고, 이후 실행이 성공해도 CLI가 자동으로 삭제하지 않는다.
+
+복구 경로로 옮기는 작업까지 실패하면 stderr가 임시 파일 경로를 알린다.
+먼저 그 임시 파일을 별도 경로에 보존한 뒤 형식을 확인한다.
+
 ## 로그 전송
 
 `logncrash send`는 collector host로 로그 한 건을 전송한다.

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

@@ -13,6 +13,7 @@ nhncloud configure --uak-id <uak-id> --uak-secret <uak-secret> --ncr-appkey <app
 ```
 
 기본 region은 `kr1`이고, `kr1`, `kr2`, `kr3`를 지원한다.
+공공망 profile(`"environment": "gov"`)의 NCR API는 `kr1`만 지원한다.
 
 ## Registry 조회