@bifos/nhncloud-cli 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +115 -190
  2. package/dist/index.js +2321 -368
  3. package/package.json +25 -4
  4. package/skills/nhncloud-cli/SKILL.md +4 -3
  5. package/skills/nhncloud-cli/references/apigateway.md +2 -6
  6. package/skills/nhncloud-cli/references/common.md +107 -26
  7. package/skills/nhncloud-cli/references/deploy.md +0 -1
  8. package/skills/nhncloud-cli/references/loadbalancer.md +2 -3
  9. package/skills/nhncloud-cli/references/logncrash.md +6 -9
  10. package/skills/nhncloud-cli/references/ncs.md +3 -3
  11. package/skills/nhncloud-cli/references/nks.md +1 -1
  12. package/skills/nhncloud-cli/references/skm.md +118 -0
  13. package/skills/nhncloud-cli/references/troubleshooting.md +17 -31
package/README.md CHANGED
@@ -5,10 +5,11 @@
5
5
  [![CI](https://github.com/jon890/nhncloud-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/jon890/nhncloud-cli/actions/workflows/ci.yml)
6
6
  [![license](https://img.shields.io/npm/l/@bifos/nhncloud-cli.svg)](https://github.com/jon890/nhncloud-cli/blob/main/LICENSE)
7
7
 
8
- [NHN Cloud](https://www.nhncloud.com) 를 AI 에이전트가 다룰 수 있게 만든 CLI 다.
8
+ [NHN Cloud](https://www.nhncloud.com) 를 터미널과 AI 에이전트에서 쓸 수 있게 해 주는 비공식 CLI 예요.
9
+ NHN 이 만든 공식 제품이 아니에요.
9
10
 
10
- Compute·Network·Block Storage·Load Balancer·Container Registry·Kubernetes·Container Service·Log & Crash·Deploy·API Gateway 를 명령 한 줄로 다루고, 결과를 `--json` 으로 내보낸다.
11
- Claude Code 같은 에이전트에 스킬로 설치하면 "인스턴스 목록 보여줘" 같은 자연어 지시를 그대로 처리한다.
11
+ 인스턴스, 네트워크, 로드밸런서, Kubernetes, 컨테이너 레지스트리와 컨테이너 서비스, 로그 검색, 배포, API Gateway, 키 관리를 명령 한 줄로 다루고, 결과를 `--json` 으로 내보내요.
12
+ Claude Code 나 Codex 에 스킬로 설치하면 "인스턴스 목록 보여줘" 같은 말을 그대로 알아듣고 처리해요.
12
13
 
13
14
  ```bash
14
15
  npm install -g @bifos/nhncloud-cli
@@ -16,105 +17,111 @@ nhncloud configure
16
17
  nhncloud skills install
17
18
  ```
18
19
 
19
- ## 설치와 설정
20
+ ```
21
+ "인스턴스 목록 보여줘"
22
+ "kr1 리전에 인스턴스 만들고 ACTIVE 될 때까지 기다려줘"
23
+ "최근 1시간 에러 로그 찾아줘"
24
+ "배포 실행하고 완료되면 알려줘"
25
+ "클러스터 kubeconfig 받아줘"
26
+ ```
27
+
28
+ ## 이런 분께 맞아요
20
29
 
21
- Node.js 20 이상이 필요하다.
30
+ - NHN Cloud 콘솔을 열지 않고 터미널에서 리소스를 확인하고 바꾸고 싶은 분
31
+ - AI 에이전트에게 인스턴스 관리, 로그 조회, 배포 실행을 맡기고 싶은 분
32
+ - 로그 추출이나 배포처럼 반복되는 작업을 스크립트로 자동화하고 싶은 분
33
+
34
+ ## 빠른 시작
35
+
36
+ Node.js 20 이상이 필요해요.
37
+
38
+ ### 1. 설치해요
22
39
 
23
40
  ```bash
24
41
  npm install -g @bifos/nhncloud-cli
25
42
  ```
26
43
 
27
- `nhncloud configure` 가 profile 과 서비스별 자격증명을 대화형으로 받는다.
28
- 공통 UAK, Log & Crash appkey, iaas 자격증명, NCR appkey, NCS appkey, Deploy appkey 순으로 입력한다.
29
- appkey 는 명령 옵션으로 지정할 수 없고 profile 에만 둔다.
30
- 여러 프로젝트를 다루려면 profile 을 나눠 `--profile` 로 전환한다.
31
- 저장 전 연결 테스트를 자동으로 수행한다 (`--no-verify` 로 생략).
44
+ ### 2. 자격증명을 설정해요
45
+
46
+ 아래 명령을 실행하면 profile 과 서비스별 자격증명을 차례로 물어봐요.
47
+ 쓰는 서비스의 값만 입력해도 돼요.
48
+ 저장하기 전에 연결 테스트를 자동으로 수행해요.
32
49
 
33
50
  ```bash
34
51
  nhncloud configure
35
- nhncloud doctor # 설정이 제대로 됐는지 확인
36
52
  ```
37
53
 
38
- 자격증명은 `~/.nhncloud/credentials.json`(mode 0600), 설정은 `~/.nhncloud/config.json` 에 저장한다.
39
- profile 우선순위는 `--profile` > `NHNCLOUD_PROFILE` > `config.defaultProfile` > `default` 다.
40
-
41
- 공공기관용 NHN Cloud를 사용한다면 해당 profile의 `credentials.json` 블록에 `"environment": "gov"`를 추가한다.
42
- 기존 profile은 이 필드를 생략하면 일반망을 사용한다.
43
- 공공망 endpoint 선택은 OAuth, Deploy, NCR, IaaS 호출에 적용된다.
44
- 공공망 NCR은 `kr1`, IaaS는 `kr1`과 `kr2`만 지원한다.
45
-
46
- ```json
47
- {
48
- "version": 1,
49
- "profiles": {
50
- "public-project": {
51
- "environment": "gov",
52
- "userAccessKey": { "id": "<uak-id>", "secret": "<uak-secret>" },
53
- "deploy": { "appkey": "<appkey>" }
54
- }
55
- }
56
- }
57
- ```
54
+ 인스턴스, 네트워크 같은 IaaS 명령을 쓴다면 두 값을 특히 조심해 주세요.
58
55
 
59
- `nhncloud deploy artifacts --profile public-project --json`으로 조회할 수 있다.
60
- 현재 `configure`의 연결 테스트는 일반망 주소를 사용하므로, 공공망 자격증명을 저장할 때는 `--no-verify`를 지정한다.
61
- 공공망 표시를 추가한 뒤 조회 명령으로 연결과 권한을 확인한다.
56
+ - "API 비밀번호"(`--iaas-password`)는 콘솔 로그인 비밀번호가 아니라 IAM 의 **API 비밀번호**예요. IAM 사용자 상세 페이지의 "API 비밀번호 설정"에서 따로 발급해요.
57
+ - "IAM username"(`--iaas-username`)은 계정 이메일이나 IAM 계정 ID 예요. tenantId 와 비슷하게 생긴 UUID 형태의 "API 사용자 ID"가 아니에요.
62
58
 
63
- > **iaas 자격증명의 함정 두 가지**
64
- >
65
- > `--iaas-password` 는 NHN Cloud 콘솔 IAM 의 **API 비밀번호**다. 로그인 비밀번호와 다르다.
66
- > IAM 사용자 상세 페이지의 "API 비밀번호 설정"에서 따로 발급한다.
67
- >
68
- > `--iaas-username` 은 계정 이메일 또는 **IAM 계정 ID(사번)** 다.
69
- > tenantId 와 비슷하게 생긴 "API 사용자 ID"(UUID) 가 아니다.
59
+ 나머지 입력 항목은 [IaaS 가이드](skills/nhncloud-cli/references/iaas.md)에 있어요.
60
+ 공공기관용 NHN Cloud 설정은 [공통 가이드](skills/nhncloud-cli/references/common.md)에 있어요.
70
61
 
71
- CI·자동화는 flag 로 비대화형 설정한다. 비밀번호는 환경변수를 권장한다.
62
+ ### 3. 설정을 확인해요
72
63
 
73
64
  ```bash
74
- NHNCLOUD_IAAS_PASSWORD=<api-password> nhncloud configure \
75
- --uak-id <uak-id> --uak-secret <uak-secret> \
76
- --logncrash-appkey <appkey> \
77
- [--deploy-appkey <appkey>] [--ncr-appkey <appkey>] [--ncs-appkey <appkey>] \
78
- --iaas-tenant-id <tenant-id> --iaas-username <iam-username> --iaas-region kr1 \
79
- --no-verify
65
+ nhncloud doctor
66
+ nhncloud doctor --check-connection # 대상 profile 의 실제 연결까지 확인
80
67
  ```
81
68
 
82
- 에이전트에서 쓰려면 스킬을 설치한다. Claude Code 가 이 CLI 의 사용법을 알게 된다.
69
+ `doctor` 는 기본으로 외부 API 를 호출하지 않고 자격증명, 설정 파일, 스킬 설치 상태를 확인해요.
70
+ `--check-connection` 을 주면 대상 profile 의 자격증명으로 실제 연결까지 확인해요.
71
+
72
+ ### 4. 첫 명령을 실행해요
73
+
74
+ ```bash
75
+ nhncloud instance list --region kr1 # 인스턴스 목록
76
+ nhncloud network list --region kr1 # VPC 목록
77
+ ```
78
+
79
+ `--region` 은 IaaS 와 NKS 계열에서 결과가 달라지므로, 기본값에 기대지 말고 직접 지정하는 편이 안전해요.
80
+
81
+ ### 5. AI 에이전트에 연결해요 (선택)
82
+
83
+ Claude Code 나 Codex 를 쓴다면 스킬을 설치해요. 에이전트가 이 CLI 의 사용법을 알게 돼요.
84
+ 설치하면 Claude Code 의 `~/.claude/skills/nhncloud-cli` 와 Codex 의 `~/.agents/skills/nhncloud-cli` 에 함께 연결돼요.
83
85
 
84
86
  ```bash
85
87
  nhncloud skills install
86
88
  nhncloud skills status
87
89
  ```
88
90
 
89
- 전역 설치 없이 `npx --yes @bifos/nhncloud-cli@latest skills install` 로도 설치된다.
90
- 관리 저장소에 복사되므로 임시 패키지 경로가 사라져도 남는다.
91
- CLI 를 새 버전으로 올린 뒤에는 `nhncloud skills update` 를 실행해야 스킬도 갱신된다.
91
+ 이제 에이전트에게 한국어로 시키면 돼요.
92
+ 에이전트가 알맞은 `nhncloud` 명령을 고르고, 필요하면 인스턴스 id 나 VPC id 를 먼저 조회해요.
92
93
 
93
- 상태는 `current`, `missing`, `outdated`, `broken`, `unmanaged`, `modified`, `corrupt` 중 하나이고, 출력에 딸린 복구 명령을 따르면 된다.
94
- 사용자 항목이나 수정·손상된 저장소는 자동으로 덮어쓰지 않는다.
94
+ CLI 를 새 버전으로 올린 뒤에는 `nhncloud skills update` 를 한 번 실행해 주세요. 그래야 스킬도 함께 갱신돼요.
95
+ 전역 설치 없이 `npx --yes @bifos/nhncloud-cli@latest skills install` 로도 설치할 수 있어요.
95
96
 
96
- ## 사용법
97
+ ## 할 수 있는 일
97
98
 
98
- 설정을 마치면 에이전트에게 한국어로 시키면 된다.
99
+ | 영역 | 대표 명령 | 가이드 |
100
+ | --- | --- | --- |
101
+ | Compute 인스턴스 | `nhncloud instance` | [IaaS](skills/nhncloud-cli/references/iaas.md) |
102
+ | 네트워크, 보안그룹 | `nhncloud network` | [IaaS](skills/nhncloud-cli/references/iaas.md) |
103
+ | Block Storage | `nhncloud volume` | [IaaS](skills/nhncloud-cli/references/iaas.md) |
104
+ | Floating IP | `nhncloud floatingip` | [IaaS](skills/nhncloud-cli/references/iaas.md) |
105
+ | Load Balancer, IP ACL | `nhncloud loadbalancer` | [Load Balancer](skills/nhncloud-cli/references/loadbalancer.md) |
106
+ | Log & Crash | `nhncloud logncrash` | [Log & Crash](skills/nhncloud-cli/references/logncrash.md) |
107
+ | Deploy | `nhncloud deploy` | [Deploy](skills/nhncloud-cli/references/deploy.md) |
108
+ | Container Registry | `nhncloud ncr` | [NCR](skills/nhncloud-cli/references/ncr.md) |
109
+ | Kubernetes Service | `nhncloud nks` | [NKS](skills/nhncloud-cli/references/nks.md) |
110
+ | Container Service | `nhncloud ncs` | [NCS](skills/nhncloud-cli/references/ncs.md) |
111
+ | API Gateway | `nhncloud apigateway` | [API Gateway](skills/nhncloud-cli/references/apigateway.md) |
112
+ | Secure Key Manager | `nhncloud skm` | [SKM](skills/nhncloud-cli/references/skm.md) |
113
+ | 설정과 진단 | `nhncloud configure`, `nhncloud doctor`, `nhncloud skills` | [공통](skills/nhncloud-cli/references/common.md) |
114
+
115
+ 명령과 옵션 전체는 카탈로그로 확인할 수 있어요.
116
+ 외부 API 를 호출하지 않고 명령 트리 정보만 출력해요.
99
117
 
118
+ ```bash
119
+ nhncloud commands --json | jq '.commands[] | select(.path=="nks cluster list")'
100
120
  ```
101
- "인스턴스 목록 보여줘"
102
- "kr1 리전에 인스턴스 만들고 ACTIVE 될 때까지 기다려줘"
103
- "최근 1시간 에러 로그 찾아줘"
104
- "배포 실행하고 완료되면 알려줘"
105
- "이 로드밸런서에 IP ACL 그룹 붙여줘"
106
- "클러스터 kubeconfig 받아줘"
107
- "레지스트리 이미지 태그 목록 보여줘"
108
- ```
109
-
110
- 에이전트가 알맞은 `nhncloud` 명령으로 옮기고, 필요하면 인스턴스 id 나 VPC id 를 먼저 조회한다.
111
-
112
- 에이전트가 쓰는 명령 카탈로그와 판단 기준은 [스킬 문서](skills/nhncloud-cli/SKILL.md)에 있다.
113
- 서비스별 상세는 [references/](skills/nhncloud-cli/references/) 아래 파일로 나뉘어 있다.
114
121
 
115
122
  ## 에이전트 없이 직접 쓰기
116
123
 
117
- 터미널에서 바로 쓸 수도 있다.
124
+ 터미널에서 바로 써도 돼요.
118
125
 
119
126
  ```bash
120
127
  nhncloud instance list # 인스턴스 목록
@@ -132,13 +139,16 @@ nhncloud deploy scenarios --artifact-id <id> --server-group-id <id> # 서버그
132
139
  nhncloud logncrash available-token # 남은 조회 토큰과 추정 대기 시간
133
140
  nhncloud logncrash search --query '*' --from 1h --to now # 최근 1시간 로그
134
141
  nhncloud logncrash export --query '<lucene>' --from 1h --to now --output logs.jsonl # 대량 로그 파일 저장
135
- nhncloud apigateway service list # API Gateway 서비스
136
- nhncloud apigateway stage update <service-id> <stage-id> --description "설명" --yes # API Gateway 스테이지 수정
137
- nhncloud apigateway stage import-resources <service-id> <stage-id> --yes # 리소스를 스테이지로 반영
138
- nhncloud apigateway stage deploy create <service-id> <stage-id> --yes # API Gateway 스테이지 배포
142
+ nhncloud apigateway service list # API Gateway 서비스
143
+ nhncloud apigateway stage deploy create <service-id> <stage-id> --yes # API Gateway 스테이지 배포
144
+ nhncloud skm key list <keystore-id> # Secure Key Manager 키 목록
145
+ nhncloud skm secret get <key-id> --quiet # 기밀 데이터 원문
139
146
  ```
140
147
 
141
- 전체 명령과 옵션은 `--help` 로 본다.
148
+ 삭제처럼 되돌리기 어려운 일부 명령은 `--yes` 를 붙여야 실행돼요. 비대화형 환경에서 `--yes` 가 없으면 API 를 호출하기 전에 끝나요.
149
+ 확인 없이 바로 실행되는 변경 명령도 있으니, 에이전트에게 맡기기 전에 [공통 가이드](skills/nhncloud-cli/references/common.md)의 「되돌릴 수 없는 명령」 절을 먼저 봐 주세요.
150
+
151
+ 명령과 옵션은 `--help` 로 볼 수 있어요.
142
152
 
143
153
  ```bash
144
154
  nhncloud --help
@@ -146,143 +156,58 @@ nhncloud instance --help
146
156
  nhncloud instance create --help
147
157
  ```
148
158
 
149
- 기계가 읽을 카탈로그가 필요하면 `commands` 를 쓴다. 외부 API 를 호출하지 않고 Commander 트리 메타데이터만 출력한다.
150
-
151
- ```bash
152
- nhncloud commands --json | jq '.commands[] | select(.path=="nks cluster list")'
153
- ```
154
-
155
- 출력은 세 가지 모드다.
159
+ ### 출력 형식을 골라요
156
160
 
157
- | 플래그 | 출력 | 쓰는 곳 |
161
+ | 옵션 | 출력 | 쓰는 곳 |
158
162
  | --- | --- | --- |
159
- | (없음) | 사람이 읽는 표 | 터미널 |
160
- | `--json` | JSON | 파싱, 명령 연결 |
161
- | `--quiet` | 명령이 문서화한 핵심 값 한 줄 | 스크립트 |
162
-
163
- 전역 옵션이라 모든 명령에 붙일 수 있다. `--no-color` 와 `--request-timeout <sec>` 도 같은 자리에서 쓴다.
164
- 요청 타임아웃은 초 단위이며 기본값은 30초, 허용 범위는 1~3600초다.
165
- `NHNCLOUD_REQUEST_TIMEOUT` 환경변수로도 지정할 수 있으며 명령줄 옵션이 환경변수보다 우선한다.
166
-
167
- `--json` 은 CLI 가 가공한 출력 계약이라 원본 응답의 최상위 래퍼를 그대로 보존하지 않는다.
168
- 예를 들어 `instance get --json` 은 `.server.status` 가 아니라 `.status` 를 읽는다.
169
- 명령별 shape 는 [common.md 의 JSON shape 요약](skills/nhncloud-cli/references/common.md)에 있다.
163
+ | (없음) | 사람이 읽기 좋은 표 | 터미널 |
164
+ | `--json` | JSON | 다른 프로그램에서 읽을 때 |
165
+ | `--quiet` | 명령이 문서화한 핵심 값 한 줄 | 셸 스크립트 |
170
166
 
171
167
  ```bash
172
168
  nhncloud instance get <instance-id> --json | jq -r '.status'
173
169
  nhncloud logncrash available-token --json | jq -r '.availableToken'
174
- nhncloud logncrash search --query '*' --from 1h --to now --json | jq -r '.data[].logBody'
175
170
  ```
176
171
 
177
- ### 종료 코드
172
+ `--json` 은 CLI 가 가공한 출력이라 원본 응답과 모양이 달라요. 명령별 모양은 「할 수 있는 일」 표의 서비스별 가이드에 있어요.
173
+ 요청 타임아웃, 환경변수, 비대화형 설정은 [공통 가이드](skills/nhncloud-cli/references/common.md)에 있어요.
178
174
 
179
- | 코드 | 의미 |
180
- | :---: | --- |
181
- | 0 | 성공 |
182
- | 1 | API 오류 |
183
- | 2 | 인증 실패 (401/403) |
184
- | 3 | 입력 오류 (파라미터·시간 범위) |
185
- | 4 | 설정 오류 (자격증명 누락) |
175
+ ## 더 알아보기
186
176
 
187
- ### 되돌리기 어려운 명령의 확인
188
-
189
- 삭제·전체 교체처럼 되돌리기 어려운 명령은 실행 전 확인을 요구한다.
190
- 자동화·파이프 등 비대화형 실행에서는 `--yes` 를 명시해야 한다.
191
- 플래그가 없으면 API 를 호출하기 전에 종료 코드 3 으로 끝난다.
192
-
193
- `--region` 은 IaaS 와 NKS 계열에서 결과를 가르므로, 기본값에 기대지 말고 명시하는 편이 안전하다.
194
-
195
- ## 프로젝트 구조
196
-
197
- ```
198
- src/
199
- index.ts CLI 진입점
200
- api/ 공통 endpoint, 응답 봉투, HTTP 오류 처리 (ky)
201
- services/ 서비스별 API 클라이언트와 타입 가드
202
- commands/ Commander.js 명령 정의
203
- config/ ~/.nhncloud/ 자격증명·설정 스키마와 profile 해석
204
- cache/ ~/.nhncloud/cache/ 토큰 캐시
205
- formatters/ 표·JSON·quiet 출력
206
- skill/ Claude Code 스킬 설치·갱신
207
- utils/ 에러, 스피너, 종료 코드
208
- ```
177
+ | 문서 | 내용 |
178
+ | --- | --- |
179
+ | [스킬 문서](skills/nhncloud-cli/SKILL.md) | 에이전트가 읽는 명령 목록과 판단 기준 |
180
+ | [공통 가이드](skills/nhncloud-cli/references/common.md) | 초기 설정, profile, 공공망, 출력 모드, 타임아웃 |
181
+ | [문제 해결](skills/nhncloud-cli/references/troubleshooting.md) | 종료 코드와 증상별 대처 |
182
+ | [docs/data-schema.md](docs/data-schema.md) | 자격증명과 설정 파일 스키마 |
183
+ | [docs/code-architecture.md](docs/code-architecture.md) | 코드 구조와 경계 |
209
184
 
210
- `commands/`는 `services/`, `api/`, `config/`의 기능을 조합한다.
211
- `services/`가 `commands/`를 import하지 않는 경계와 상세 의존 방향은 `docs/code-architecture.md`를 기준으로 삼는다.
185
+ ## 문제가 생기면
212
186
 
213
- | 문서 | 담는 것 |
214
- | --- | --- |
215
- | [docs/prd.md](docs/prd.md) | 제품 목적과 범위 |
216
- | [docs/flow.md](docs/flow.md) | 사용자 흐름 |
217
- | [docs/code-architecture.md](docs/code-architecture.md) | 디렉터리 트리, 레이어, 경계 |
218
- | [docs/data-schema.md](docs/data-schema.md) | 자격증명과 캐시 스키마 |
219
- | [docs/adr/INDEX.md](docs/adr/INDEX.md) | 기술 의사결정 기록 |
220
- | [docs/pitfalls/INDEX.md](docs/pitfalls/INDEX.md) | 반복해서 발견된 회피 패턴 |
187
+ - 설정이 의심되면 `nhncloud doctor` 를 먼저 실행해 보세요.
188
+ - 에이전트가 새 명령을 모르면 `nhncloud skills update` 를 실행해 주세요.
189
+ - 종료 코드별 대처는 [문제 해결](skills/nhncloud-cli/references/troubleshooting.md)에 있어요.
190
+ - 버그나 제안은 [GitHub Issues](https://github.com/jon890/nhncloud-cli/issues) 에 남겨 주세요. 설정 문제라면 `nhncloud doctor --json` 출력을 함께 붙여 주세요.
191
+ 비밀값은 출력에 들어가지 않지만 파일 경로에 사용자 이름이 보일 수 있으니 필요하면 가려 주세요.
221
192
 
222
193
  ## 기여하기
223
194
 
224
- 이슈와 PR 모두 환영한다.
225
-
226
- ### 개발 환경
195
+ 이슈와 PR 모두 환영해요.
196
+ 개발 환경은 아래 명령으로 준비해요.
227
197
 
228
198
  ```bash
229
199
  git clone https://github.com/jon890/nhncloud-cli.git
230
200
  cd nhncloud-cli
231
201
  pnpm install
232
-
233
- pnpm run build # tsup 으로 dist/index.js 단일 번들 생성
234
- pnpm test # vitest
235
- pnpm tsc --noEmit # 타입 검사 (빌드는 타입을 검사하지 않는다)
236
-
237
- node dist/index.js --help # 빌드 결과 직접 실행
238
- node dist/index.js commands --json
202
+ pnpm run build
203
+ pnpm tsc --noEmit
204
+ pnpm test
239
205
  ```
240
206
 
241
- `pnpm` 을 쓴다. 빌드는 `tsup`(esbuild) 이 담당하고 `tsc` 는 타입 검사 전용이므로,
242
- 타입 오류를 잡으려면 `pnpm tsc --noEmit` 를 따로 돌려야 한다.
243
-
244
- ### 새 명령을 추가할 때
245
-
246
- 1. [공식 API 문서](https://docs.nhncloud.com)로 엔드포인트와 요청·응답 구조를 먼저 확인한다. 확정할 수 없으면 추측해 구현하지 않는다
247
- 2. `src/services/<service>/` 에 API 클라이언트와 타입 가드를 둔다. 공식 예제 JSON 과 필드 타입을 맞춘다
248
- 3. `src/commands/<service>/` 에 명령을 정의한다. 인접한 명령의 구조를 따르는 것이 가장 빠르다
249
- 4. 출력은 `src/formatters/` 에서 표·JSON·quiet 세 모드를 모두 지원한다
250
- 5. `src/**/*.test.ts` 에 테스트를 추가한다
251
- 6. 명령이나 옵션이 바뀌면 이 README 와 `skills/nhncloud-cli/references/` 를 함께 갱신한다
252
-
253
- HTTP 호출은 `ky` 만 쓰고, 사용자 오류는 `NhnCloudCliError` 와 `src/utils/exit-codes.ts` 의 종료 코드를 쓴다.
254
- 데이터는 stdout, 진행 상황·경고·오류는 stderr 로 분리한다.
255
-
256
- NHN Cloud API 가 문서와 다르거나 직관에 반하면 [docs/adr/](docs/adr/) 에 기록한다.
257
- 엔드포인트 버전 이중 prefix 나 200 응답 속 `isSuccessful: false`처럼 직관에 반하는 동작은 관련 ADR과 반복 함정 문서에서 확인한다.
258
-
259
- ### PR 을 낼 때
260
-
261
- - 커밋과 PR 제목은 `type(scope): 설명` 형식을 쓴다
262
- - 커밋 메시지와 PR 본문은 한국어로 쓴다
263
- - PR 을 열면 CI 가 타입 검사·테스트·빌드를 돌리고, Claude 가 코드 리뷰를 남긴다
264
- - 리뷰의 🔴 항목은 머지 전에 반영한다
265
-
266
- 이 저장소와 npm 패키지는 공개된다.
267
- 문서·코드·테스트 fixture·이슈 본문에 실제 자격증명이나 사용자 리소스 ID 를 남기지 않고 `<instance-id>` 같은 placeholder 로 바꾼다.
268
-
269
- ### 버그와 제안
270
-
271
- [GitHub Issues](https://github.com/jon890/nhncloud-cli/issues) 에 올린다.
272
- 설정 문제라면 `nhncloud doctor` 출력을 함께 붙이면 진단이 빠르다 (비밀값은 가려서 붙인다).
273
-
274
- ## 기술 스택
275
-
276
- | 분류 | 사용 |
277
- | --- | --- |
278
- | 언어·런타임 | TypeScript, Node.js 20+ |
279
- | CLI 프레임워크 | Commander.js |
280
- | HTTP | ky |
281
- | 출력 | chalk, cli-table3, ora |
282
- | 대화형 입력 | @inquirer/prompts |
283
- | 빌드 | tsup (CJS 단일 번들) |
284
- | 테스트 | vitest |
207
+ 새 명령을 추가하는 규칙은 [AGENTS.md](AGENTS.md) 와 [docs/code-architecture.md](docs/code-architecture.md) 에 있어요.
208
+ 커밋과 PR 제목은 `type(scope): 설명` 형식으로, 커밋 메시지와 PR 본문은 한국어로 써 주세요.
209
+ 이 저장소는 공개돼요. 실제 자격증명이나 리소스 ID 는 남기지 말고 `<instance-id>` 같은 placeholder 를 써 주세요.
285
210
 
286
211
  ## 라이선스
287
212
 
288
- MIT
213
+ [MIT](LICENSE)