@bstage-sdk/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bemyfriends Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/MIGRATION.md

@@ -0,0 +1,50 @@
+# 마이그레이션 가이드
+
+`bstage init`으로 만든 프로젝트는 생성 시점의 SDK 버전을 `package.json`에 **고정값으로 박는다**. 따라서 SDK가 올라가도 기존 프로젝트는 자동으로 따라오지 않는다. 이 문서는 **버전 사이에 소비자(템플릿 개발자)가 해야 할 일**을 SDK 쪽에서 누적 관리하는 단일 소스다.
+
+## 이 문서의 소유권과 역할
+
+- **누가 쓰나**: 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 이상으로 올려야 한다.
+
+## 마이그레이션이 동작하는 방식
+
+마이그레이션은 두 단계로 나뉘고, 각 단계에 맞는 도구가 다르다.
+
+1. **감지 (결정론)** — 설치된 SDK 버전과 최신 버전을 비교하고, 누락된 파일·드리프트를 보고한다. 정답이 하나이므로 도구가 기계적으로 처리한다.
+2. **변환 (판단)** — 이 문서의 해당 구간을 읽고, **실제 프로젝트 코드를 보면서** 적용한다. 사용자가 분기시킨 코드를 덮어쓰지 않고 reconcile해야 하므로 AI/사람의 판단이 들어간다.
+
+소비자 프로젝트에서는 AI가 1로 시작 버전을 파악 → 이 문서에서 해당 구간을 읽음 → 프로젝트에 맞춘 작업 계획을 사람에게 제시 → 승인 후 변환을 수행한다.
+
+### 도구
+
+- **감지**: `bstage doctor` (`npx @bstage-sdk/cli@latest doctor`). 버전 드리프트·보일러플레이트 누락·적용 가능한 마이그레이션 항목을 read-only로 보고한다. `--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가 마이그레이션을 진행할 수 있다.
+
+## 항목 작성 규칙
+
+각 항목은 **소비자가 행동해야 하는 변경 하나**를 기술한다. 단순 내부 리팩터링은 적지 않는다(그건 CHANGELOG의 몫).
+
+항목 머리에 두 가지 배지를 단다.
+
+- 적용 난이도: `자동` (충돌 없이 기계적 적용 가능) / `판단` (사용자 코드 이해 필요)
+- 필요도: `필수` (안 하면 깨짐) / `선택` (새 기능을 쓸 때만)
+
+각 항목은 다음 소제목을 갖는다.
+
+- **영향** — 어떤 프로젝트가 해당되는지 + 감지 방법(어떤 파일/버전을 보면 아는지)
+- **변경 내용** — 무엇이 왜 바뀌었는지 (배경은 한 줄, 상세는 관련 docs 링크)
+- **적용** — 단계. 자동 단계와 판단 단계를 구분해서 적는다.
+
+> **`적용` 단계는 옛 프로젝트에서 실제로 따라가 본 뒤 적는다.** 새 `bstage init` 프로젝트에서 되는 것과, 기존 프로젝트가 이 절차만 보고 도달하는 것은 다르다. 따라 했을 때 깨지는 선행 조건이 있으면 **그 조건까지 적는다** — `core 0.44.0` 항목이 그 사례다(스크립트만 넣으면 `@types/node` 부재로 `TS2688`이 난다. 스캐폴드 템플릿을 고쳐 새 프로젝트는 해결됐지만, 먼저 써둔 적용 절차를 되짚지 않아 기존 프로젝트용 지침이 깨진 채 남았다).
+
+> **헤더 규칙**: `
+
+아직 항목이 없다. 소비자에게 영향이 있는 변경을 릴리즈할 때 여기에 추가한다.