@bifos/nhncloud-cli 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bifos/nhncloud-cli",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "CLI for NHN Cloud (Compute, Network, Kubernetes, Load Balancer, Log & Crash, Deploy, Secure Key Manager and more) — AI agent & terminal friendly",
   "keywords": [
     "nhncloud",

package/skills/nhncloud-cli/SKILL.md

@@ -3,7 +3,7 @@ name: nhncloud-cli
 description: >-
   NHN Cloud 리소스를 nhncloud CLI로 조회·생성·변경·삭제하거나,
   configure·profile·출력 형식·종료 코드·명령 문법을 확인할 때 사용한다.
-  Claude Code 공개 스킬의 상태를 확인하거나
+  Claude Code·Codex 공개 스킬의 상태를 확인하거나
   `skills status|install|update|uninstall`로 관리하고 상태별 복구 방법을 안내할 때도 사용한다.
   Log & Crash, Deploy, Compute, Network, Block Storage, Floating IP,
   Load Balancer, NCR, NKS, NCS, API Gateway, Secure Key Manager 작업을 서비스별 참조와 명령 카탈로그로 안내한다.

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

@@ -3,8 +3,12 @@
 공개 스킬 관리, configure, profile, 출력 모드, 에러 코드를 다룬다.
 서비스별 세부 명령은 각 reference를 읽는다.
 
-## Claude Code 공개 스킬 관리
+## Claude Code·Codex 공개 스킬 관리
 
+설치 경로는 Claude Code 의 `~/.claude/skills/nhncloud-cli` 와 Codex 의 `~/.agents/skills/nhncloud-cli` 다.
+두 경로는 같은 관리 저장소를 가리킨다.
+Codex 를 설치했는지와 관계없이 두 경로를 만들고, 필요하면 `~/.agents/skills` 디렉터리도 만든다.
+이전에 Claude Code 경로에만 설치했다면 `nhncloud skills install` 이나 `update` 를 다시 실행해 Codex 경로를 연결한다.
 
 ```bash
 # 전역 설치한 CLI에서 설치
@@ -29,17 +33,25 @@ 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` |
+| `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` |
+
+상태는 설치 경로를 합친 값이고 위 표의 `corrupt`부터 `current` 방향으로 먼저 해당하는 값이다.
+`status --json`의 최상위 `destination`, `linkTarget`, `managed`는 Claude Code 경로 값이다. 경로별 상세의 위치는 아래 `--json` 설명이 명령별로 정한다.
+
+두 경로가 모두 `current` 일 때만 상태가 `current` 다.
 
 `--force`는 사용자 항목 또는 수정·손상된 관리 저장소를 삭제하지 않고 같은 상위 디렉터리에 백업한 뒤 교체한다.
-`nhncloud skills uninstall`은 `~/.claude/skills/nhncloud-cli`의 활성 심볼릭 링크만 제거하며 버전별 관리 저장소는 보존한다.
-설치 경로가 사용자 파일이나 실제 디렉터리이면 제거하지 않는다.
+한 경로라도 `unmanaged`, `modified`, `corrupt` 면 `--force` 없이는 어느 경로도 바꾸지 않는다.
+다른 링크를 거쳐 가다가 대상이 사라진 링크(예: `~/.agents/skills/nhncloud-cli` 가 없는 `~/.claude/skills/nhncloud-cli` 를 가리킴)도 `unmanaged` 로 판정한다. 링크가 가리키는 곳을 확인한 뒤 `--force` 로 교체한다.
+한 경로의 전환이 실패하면 이미 바꾼 경로를 이전 상태로 되돌린다.
+`nhncloud skills uninstall`은 두 설치 경로의 활성 심볼릭 링크만 제거하며 버전별 관리 저장소는 보존한다.
+한 경로라도 사용자 파일, 실제 디렉터리, 알 수 없는 링크이면 어느 링크도 제거하지 않는다.
 
 자동화에서는 모든 하위 명령에 전역 출력 옵션을 함께 사용할 수 있다.
 
@@ -58,8 +70,15 @@ nhncloud skills uninstall --quiet
 ```
 
 `--json`은 상태·변경 여부·백업 경로처럼 자동화에 필요한 필드를 제공한다.
+경로별 정보는 `agents.claude`, `agents.codex` 에 있고 위치는 명령마다 다르다.
+`status` 는 최상위 `agents.*` 에 경로별 상세를 두고, 최상위 필드는 합친 `status` 를 빼면 Claude Code 경로의 상세다.
+`install` 과 `update` 는 `status.agents.*` 에 경로별 상세를 둔다.
+`uninstall` 은 최상위 `agents.*` 에 경로별 `action` 과 `destination` 을 둔다.
 `--quiet`은 상태 토큰 하나만 stdout에 출력한다.
 
+Codex 에서는 `$nhncloud-cli` 로 스킬을 부를 수 있다.
+설치한 스킬이 Codex 에 보이지 않으면 Codex 를 다시 시작한다.
+
 ## 초기 설정
 
 첫 설정은 `nhncloud configure`로 한다.
@@ -112,6 +131,78 @@ CLI가 UAK를 OAuth 토큰으로 교환하므로 별도 logncrash secret은 저
 저장 파일은 `~/.nhncloud/credentials.json`이고 mode 0600으로 관리된다.
 기본 profile은 선택적으로 `~/.nhncloud/config.json`의 `defaultProfile`로 지정한다.
 
+## 설정 진단
+
+`nhncloud doctor`는 자격증명 파일, 설정 파일, 대상 profile, 공개 스킬 상태를 진단한다.
+기본 실행은 외부 API를 호출하지 않는다.
+`--check-connection`을 주면 대상 profile 하나의 자격증명으로 실제 연결을 확인한다.
+
+```bash
+nhncloud doctor
+nhncloud doctor --json | jq .
+nhncloud doctor --profile staging --check-connection --json
+nhncloud doctor --quiet          # ready 또는 not-ready
+nhncloud doctor --json | jq -e '.ready'   # 준비되지 않았으면 jq 가 1 로 끝난다
+```
+
+진단 보고서를 출력했으면 종료 코드는 문제가 있어도 0이다.
+실패로 끝나야 하는 점검은 `ready` 필드로 판정한다.
+비밀값(UAK secret, API 비밀번호, appkey)은 어떤 출력 형식에도 넣지 않는다.
+
+`--json` 최상위 필드:
+
+| 필드 | 값 |
+|---|---|
+| `schemaVersion` | `1` |
+| `ready` | 자격증명 파일이 `ok`, 대상 profile 이 있고 자격증명 블록이 하나 이상 있으며 `environment`가 올바르고, 연결 확인을 했다면 `failed`가 없을 때 `true`. `config.state`는 반영하지 않으므로 `config.json` 손상은 `config.state`로 따로 본다 |
+| `credentials` | `credentials.json` 진단. 아래 표 |
+| `config` | `config.json` 진단. 아래 표 |
+| `profile` | `{ "name": string \| null, "exists": boolean }`. `name`은 profile 해석 순서로 정한 대상이며, `config.json` 이 JSON 이 아니라 해석하지 못하면 `null` |
+| `connection` | 연결 확인 결과. 아래 표 |
+| `skills` | `{ "agents": { "claude": ..., "codex": ... } }`. 에이전트별 공개 스킬 상태 |
+
+`credentials`와 `config`:
+
+| 필드 | 값 |
+|---|---|
+| `path` | 파일의 절대 경로 |
+| `state` | `ok`, `missing`, `invalid`(JSON 이 아니거나 형식이 맞지 않음), `unreadable`(권한 등으로 읽지 못함) |
+| `reason` | `state`가 `invalid`나 `unreadable`일 때만 있는 고정 문구. 파일 내용은 담지 않는다 |
+| `permissions` | `credentials`에만 있다. 파일이 있으면 `ok`(group·other 권한 없음), `too-open`, `unknown`(Windows) |
+| `profiles` | `credentials`에만 있다. `[{ "name", "environment": "real" \| "gov" \| "invalid", "blocks": string[] }]`. `blocks`는 profile 안의 블록 이름(`userAccessKey`, `iaas`, `logncrash` 등)을 정렬한 목록이다 |
+| `defaultProfile` | `config`에만 있다. `defaultProfile` 값이나 `null` |
+
+`connection`:
+
+| 경우 | 모양 |
+|---|---|
+| `--check-connection` 없음 | `{ "checked": false }` |
+| `--check-connection` 있음 | `{ "checked": true, "profile": string \| null, "targets": { "userAccessKey", "iaas", "logncrash", "ncr", "ncs" } }` |
+
+`targets`의 각 값은 `{ "status", "reason"?, "exitCode"? }`다.
+
+| `status` | `reason` | 뜻 |
+|---|---|---|
+| `ok` | 없음 | 연결과 인증에 성공했다 |
+| `failed` | `auth` | 인증에 실패했다. 키나 appkey를 확인한다 |
+| `failed` | `error` | 네트워크나 API 오류로 확인하지 못했다. `exitCode`에 그 오류의 종료 코드가 있다. Log & Crash 는 조회 한도 소진도 `failed`로 보고된다 |
+| `skipped` | `not-configured` | profile 에 그 블록이 없거나 필수 값이 비어 있다 |
+| `skipped` | `uak-missing` | appkey 는 있지만 함께 쓰는 공통 UAK 가 없다(`logncrash`, `ncr`, `ncs`) |
+| `skipped` | `uak-failed` | `userAccessKey` 확인이 `ok`가 아니라 UAK 로 OAuth 토큰을 받는 대상(`logncrash`, `ncs`)을 확인하지 않았다 |
+| `skipped` | `gov-unsupported` | 공공망 profile 이라 확인하지 않았다 |
+| `skipped` | `profile-unavailable` | 자격증명 파일을 읽지 못했거나 대상 profile 이 없거나 `environment`가 올바르지 않다 |
+
+`ncr`과 `ncs` 확인은 `kr1` region 을 가정한다.
+연결 확인은 대상을 순차로 확인하며 요청마다 `--request-timeout`(기본 30초) 상한이 적용된다.
+`logncrash` 확인은 최근 1분 범위의 검색 요청을 하나 보내므로 Log & Crash 조회 토큰을 쓴다.
+
+`skills.agents.claude`와 `skills.agents.codex`는 각각 Claude Code(`~/.claude/skills/nhncloud-cli`)와 Codex(`~/.agents/skills/nhncloud-cli`) 경로 하나의 `SkillStatus`(`schemaVersion` 1)에 `recoveryCommand`(복구 명령, `current`이면 `null`)를 더한 것이다.
+상태를 판정하지 못하면 `{ "status": "error", "reason": string }`이다.
+한 경로의 판정이 실패해도 그 에이전트만 `error`가 되고 다른 에이전트의 상태는 그대로다.
+`reason`에는 원문 오류 메시지를 넣지 않고 고정 문구만 쓴다. 오류에 문자열 errno 코드(`EACCES` 등)가 있으면 그 코드만 붙인다.
+에이전트가 늘면 `agents`에 키가 추가되며 기존 키의 모양은 바뀌지 않는다.
+doctor 가 경로마다 다른 복구 명령을 보여도 어느 명령이든 두 경로를 함께 고친다.
+
 ## Profile 우선순위
 
 profile 해석 순서:

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

@@ -11,7 +11,9 @@
 5. exit code를 확인한다.
 6. 서비스별 인증 모델을 대조한다.
 
-`nhncloud doctor`는 자격증명과 공개 스킬 설치 상태를 오프라인에서 진단한다.
+`nhncloud doctor`는 기본으로 외부 API를 호출하지 않고 자격증명, 설정 파일, 공개 스킬 설치 상태를 진단한다.
+`--check-connection`을 주면 대상 profile 의 자격증명으로 실제 연결까지 확인한다.
+출력 필드와 상태 값은 [common.md](common.md#설정-진단)의 「설정 진단」 절을 본다.
 
 ## 인증 모델