@bstage-sdk/cli 0.8.4 → 0.8.6

package/dist/MIGRATION.md

@@ -7,7 +7,7 @@
 - **누가 쓰나**: SDK 작성자. 소비자 영향이 있는 변경을 릴리즈하는 **그 시점에** 항목을 추가한다. 마이그레이션할 때 만드는 게 아니라 미리 쌓아둔다.
 - **누가 읽나**: 소비자 프로젝트의 마이그레이션 도구(아래)와 사람.
 - **어디에 실리나**: `docs/`는 core 패키지 배포물에 포함되므로, 소비자는 `node_modules/@bstage-sdk/core/docs/MIGRATION.md`로 이 파일을 본다. cli도 빌드 시 `dist/MIGRATION.md`로 같은 파일을 복사해 `bstage doctor`가 동일 가이드를 읽는다.
-- **파일 배포 버전 ≠ 항목 헤더 버전**: 이 파일이 **실려 나가는** 버전(core)과 각 항목 헤더의 버전은 별개다. 패키지는 완전 독립 버전(cli·core·react·host·design이 서로 다른 버전 라인)이라, 항목 헤더는 그 변경을 **실제로 낸 패키지**의 버전을 가리킨다(대개 cli·react이며 core가 아닐 수 있다). 즉 core를 설치한 소비자도 헤더가 `cli 0.43.0`인 항목을 적용하려면 **cli**를 0.43.0 이상으로 올려야 한다.
+- **버전 라인과 항목 헤더**: 공개 패키지(cli·core·react·host·design·ai-toolkit)는 **한 버전 라인을 함께 쓴다** — 릴리즈마다 모든 패키지가 같은 번호로 나간다. 항목 헤더는 그중 그 변경을 **실제로 낸 패키지**를 가리키므로(대개 cli·react·ai-toolkit이며 이 파일이 실려 나가는 core가 아닐 수 있다), 헤더가 `cli 0.8.5`인 항목을 적용하려면 **cli**를 0.8.5 이상으로 올려야 한다.
 
 ## 마이그레이션이 동작하는 방식
 
@@ -20,13 +20,13 @@
 
 ### 도구
 
-- **감지**: `bstage doctor` (`npx @bstage-sdk/cli@latest doctor`). 버전 드리프트·보일러플레이트 누락·적용 가능한 마이그레이션 항목을 read-only로 보고한다. `--json`으로 구조화 출력.
+- **감지**: `bstage doctor` (`npx @bstage-sdk/cli@latest doctor`). 버전 드리프트·보일러플레이트 누락·적용 가능한 마이그레이션 항목을 보고한다. 진단 자체는 프로젝트 코드를 고치지 않지만, `--json` 없이 실행하면 SDK가 관리하는 스킬이 뒤처졌을 때 `ai install`과 같은 동기화(스킬·`AGENTS.md` 관리 영역, 없는 `AGENTS.md`·`CLAUDE.md` 생성)를 자동으로 한다. `--json`은 구조화 출력이며 아무것도 쓰지 않는다.
 - **변환**: `bstage-migrate` 스킬 (`.claude/skills/bstage-migrate/SKILL.md`). doctor 출력과 이 문서를 읽고 프로젝트에 맞춰 적용한다.
 
 ### 마이그레이션 스킬 부트스트랩
 
 - **새 프로젝트** (이 기능 도입 이후 `bstage init`): `.claude/skills/`에 스킬이 이미 들어 있다. 별도 작업 없음.
-- **옛 프로젝트**: `npx @bstage-sdk/cli@latest skills install`로 스킬을 설치한다(`.claude/skills/`에 기록). SDK 버전업 후 다시 실행하면 최신으로 동기화된다. 스킬이 없어도 `bstage doctor` 출력 + 이 문서만으로 AI가 마이그레이션을 진행할 수 있다.
+- **옛 프로젝트**: `npx @bstage-sdk/cli@latest ai install`로 스킬을 설치한다(`.claude/skills/`에 기록). SDK 버전업 후 다시 실행하면 최신으로 동기화된다. 스킬이 없어도 `bstage doctor` 출력 + 이 문서만으로 AI가 마이그레이션을 진행할 수 있다.
 
 ## 항목 작성 규칙
 
@@ -43,14 +43,67 @@
 - **변경 내용** — 무엇이 왜 바뀌었는지 (배경은 한 줄, 상세는 관련 docs 링크)
 - **적용** — 단계. 자동 단계와 판단 단계를 구분해서 적는다.
 
-> **`적용` 단계는 옛 프로젝트에서 실제로 따라가 본 뒤 적는다.** 새 `bstage init` 프로젝트에서 되는 것과, 기존 프로젝트가 이 절차만 보고 도달하는 것은 다르다. 따라 했을 때 깨지는 선행 조건이 있으면 **그 조건까지 적는다** — `core 0.44.0` 항목이 그 사례다(스크립트만 넣으면 `@types/node` 부재로 `TS2688`이 난다. 스캐폴드 템플릿을 고쳐 새 프로젝트는 해결됐지만, 먼저 써둔 적용 절차를 되짚지 않아 기존 프로젝트용 지침이 깨진 채 남았다).
+> **`적용` 단계는 옛 프로젝트에서 실제로 따라가 본 뒤 적는다.** 새 `bstage init` 프로젝트에서 되는 것과, 기존 프로젝트가 이 절차만 보고 도달하는 것은 다르다. 따라 했을 때 깨지는 선행 조건이 있으면 **그 조건까지 적는다** — 스크립트를 추가하던 항목이 그 사례다(스크립트만 넣으면 `@types/node` 부재로 `TS2688`이 난다. 스캐폴드 템플릿을 고쳐 새 프로젝트는 해결됐지만, 먼저 써둔 적용 절차를 되짚지 않아 기존 프로젝트용 지침이 깨진 채 남았다).
 
-> **헤더 규칙**: `## → {패키지} {버전}` 형식으로, 그 변경을 실제로 낸 패키지와 버전을 명시한다(예: `→ cli 0.3.0`, `→ core 0.3.0`). 한 변경이 여러 패키지를 함께 범프시켰으면 소비자가 올려야 할 패키지를 `·`로 나열한다(예: `→ core 0.3.0 · cli 0.3.0`). 소비자는 이 헤더의 패키지를 해당 버전 **이상**으로 올려야 한다. 단순 의존성 재핀(dependency bump)만 된 패키지는 헤더에 적지 않는다.
+> **헤더 규칙**: `## → {패키지} {버전}` 형식으로, 그 변경을 실제로 낸 패키지와 버전을 명시한다(예: `→ cli 0.8.5`, `→ core 0.3.0`). 한 변경이 여러 패키지를 함께 범프시켰으면 소비자가 올려야 할 패키지를 `·`로 나열한다(예: `→ cli 0.8.5 · ai-toolkit 0.8.5`). 소비자는 이 헤더의 패키지를 해당 버전 **이상**으로 올려야 한다. 단순 의존성 재핀(dependency bump)만 된 패키지는 헤더에 적지 않는다.
 >
-> **정렬**: 릴리즈 **시점 최신이 위**. 패키지가 독립 버전이라 헤더 숫자만으로는 시간순 정렬이 되지 않으므로 릴리즈 순서를 기준으로 한다.
+> **정렬**: 릴리즈 **시점 최신이 위**. 공개 패키지는 한 버전 라인을 쓰므로 헤더 숫자 순서가 곧 릴리즈 순서다.
 
 ---
 
+## → ai-toolkit 0.8.6
+
+### `bstage doctor` 종료 코드·동작 안내 정정(에이전트 스킬) — `자동`
+
+**영향**
+
+- 코드·빌드 동작은 바뀌지 않는다. 에이전트 스킬 본문만 바로잡았다.
+- `bstage-deploy`·`bstage-migrate`·`bstage-onboarding` 스킬이 `bstage doctor`의 종료 코드 1을 "진단에 error 항목이 있을 때"로만 안내했고, doctor를 "파일을 고치지 않는다"고 적었다.
+
+**변경 내용**
+
+- `bstage-deploy`: 포털 진단 자체가 실패해도(`portal.status`가 `error`) 종료 코드 1이다. 이때 `reason`·`placements[].error`를 읽고, 권한 부족이면 계정 권한·CLI 토큰 등급부터 확인하도록 안내한다.
+- `bstage-migrate`: `doctor --json`이 종료 코드 1이어도 JSON은 정상이며, 포털 진단 결과는 마이그레이션과 무관하다는 점을 적었다. "세 가지"로 적혀 있던 출력 항목 수를 네 가지로 바로잡았다.
+- `bstage-onboarding`: doctor가 포털 진단을 함께 보고, `--json` 없이 실행하면 SDK 소유 스킬을 자동 동기화한다는 점을 적었다.
+
+**적용**
+
+1. (자동) `npx @bstage-sdk/cli@latest ai update` — 스킬을 갱신한다.
+
+## → cli 0.8.5 · ai-toolkit 0.8.5
+
+### `bstage doctor`: 포털 진단이 실패해도 종료 코드 1 — `자동` · `선택`
+
+**영향**
+
+- CI·스크립트·에이전트가 `bstage doctor`의 종료 코드를 보는 프로젝트. 로그인·링크가 없는 환경(포털 진단 `skipped`)은 영향이 없다.
+
+**변경 내용**
+
+- 포털 진단 자체가 실패하면 — 배치 목록 조회 실패, 일부 배치 진단의 권한 부족(403)·서버 오류(5xx) 등으로 `portal.status`가 `"error"`면 — 종료 코드 **1**로 끝난다. 전에는 `error` 심각도 항목이 없으면 0이라, 진단을 못 끝낸 것을 "문제 없음"으로 읽을 수 있었다.
+- 그대로인 것: `error` 항목이 있으면 1, 건너뜀(`skipped`)·서버 미지원(`unsupported`)·`warn`/`info`만 있으면 0, 로컬 진단 결과는 종료 코드에 영향 없음.
+
+**적용**
+
+1. (자동) CLI를 올린다. 종료 코드 1을 실패로 처리하던 CI는 그대로 동작한다. 1이 나오면 `--json`의 `portal.status`·`portal.reason`·`portal.placements[].error`로 원인을 본다(권한 부족이면 스테이지 관리 권한이 있는 계정·토큰인지 확인).
+
+### 어드민 템플릿도 `BstageClient`로 어드민 API를 부른다(에이전트 안내 정정) — `자동`
+
+**영향**
+
+- 코드·빌드 동작은 바뀌지 않는다. 에이전트 안내 문서만 바로잡았다.
+- `AGENTS.md` 관리 영역과 `bstage-template` 스킬이 "BstageClient는 유저단 API만 지원하고 어드민용 API는 미지원"이라고 안내했다. 어드민 게이트웨이가 열린 지금 이 문구를 따르면 에이전트가 어드민 템플릿의 데이터 호출을 거부하거나 사용자 확인을 되풀이한다.
+
+**변경 내용**
+
+- 어드민 템플릿도 같은 `BstageClient`를 쓴다. 어드민 도메인에 임베드되면 `baseUrl` 기본값이 어드민 게이트웨이(`/gw`)가 되고, 게이트웨이가 어드민 로그인 쿠키와 MANAGEMENT 키(`bsm_`)를 함께 확인한다. PUBLIC 키로는 `KEY_TYPE_NOT_ALLOWED`다.
+- 호출 가능한 경로는 포털 API 레퍼런스(유저/운영자 탭)에 있는 것뿐이며, 목록에 없는 API는 경로를 추측하지 말고 사용자에게 먼저 확인한다는 안내는 그대로다.
+- **AGENTS.md 관리 영역 v17**: 파일 트리의 `client.ts` 설명과 API 금지 사항 절을 위 내용으로 고쳤다. `bstage-template` 스킬도 같은 내용으로 고쳤다. 상세는 [GETTING_STARTED.md](./GETTING_STARTED.md) "8. 어드민 템플릿 › API 호출".
+
+**적용**
+
+1. (자동) `npx @bstage-sdk/cli@latest ai update` — 스킬·`AGENTS.md` 관리 영역을 v17로 갱신한다.
+
 ## → cli 0.8.4 · ai-toolkit 0.8.4
 
 ### `bstage doctor`가 포털 배치 진단을 함께 본다 — `자동` · `선택`

package/dist/index.js

@@ -4456,6 +4456,9 @@ var DIAGNOSIS_CONCURRENCY = 4;
 function portalHasErrorFinding(p5) {
   return (p5?.placements ?? []).some((row) => row.findings.some((f) => f.severity === "error"));
 }
+function portalNeedsWork(p5) {
+  return p5 !== void 0 && (p5.status === "error" || portalHasErrorFinding(p5));
+}
 async function diagnosePortal(opts, deps = {}) {
   const explicit = Boolean(opts.placement);
   const ctx = await openContext(deps, explicit);
@@ -4982,9 +4985,6 @@ function clean(s) {
 function marker(severity) {
   return MARKERS[severity] ?? pc16.dim("\xB7");
 }
-function portalNeedsWork(p5) {
-  return p5 !== void 0 && (p5.status === "error" || portalHasErrorFinding(p5));
-}
 function hintSuffix(reason, hint) {
   return hint && !(reason ?? "").includes(hint) ? ` (\uD560 \uC77C: ${hint})` : "";
 }
@@ -5328,7 +5328,7 @@ async function doctorCommand(options, deps = {}) {
     )
   ]);
   const report2 = { ...local, portal };
-  if (portalHasErrorFinding(portal)) process.exitCode = ExitCode.FAILURE;
+  if (portalNeedsWork(portal)) process.exitCode = ExitCode.FAILURE;
   if (options.json) {
     printJson(report2);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bstage-sdk/cli",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "bstage SDK CLI — build b.stage templates",
   "type": "module",
   "publishConfig": {
@@ -32,14 +32,14 @@
     "liquidjs": "^10.24.0",
     "picocolors": "^1.1.1",
     "vite": "^7.0.0",
-    "@bstage-sdk/ai-toolkit": "0.8.4",
-    "@bstage-sdk/core": "0.8.4"
+    "@bstage-sdk/ai-toolkit": "0.8.6",
+    "@bstage-sdk/core": "0.8.6"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
-    "@bstage-sdk/design": "0.8.4"
+    "@bstage-sdk/design": "0.8.6"
   },
   "license": "MIT",
   "scripts": {