@bstage-sdk/cli 0.14.0 → 0.14.2

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.
package/dist/MIGRATION.md CHANGED
@@ -1,56 +1,76 @@
1
1
  # 마이그레이션 가이드
2
2
 
3
- `bstage init`으로 만든 프로젝트는 생성 시점의 SDK 버전을 `package.json`에 **고정값으로 박는다**. 따라서 SDK가 올라가도 기존 프로젝트는 자동으로 따라오지 않는다. 이 문서는 **버전 사이에 소비자(템플릿 개발자)가 해야 할 일**을 SDK 쪽에서 누적 관리하는 단일 소스다.
3
+ `bstage init`으로 만든 프로젝트는 생성 시점의 SDK 버전을 `package.json`에 **고정값으로 박습니다**. 따라서 SDK가 올라가도 기존 프로젝트는 자동으로 따라오지 않습니다. 이 문서는 **버전 사이에 소비자(템플릿 개발자)가 해야 할 일**을 SDK 쪽에서 누적 관리하는 단일 소스입니다.
4
4
 
5
5
  ## 이 문서의 소유권과 역할
6
6
 
7
- - **누가 쓰나**: SDK 작성자. 소비자 영향이 있는 변경을 릴리즈하는 **그 시점에** 항목을 추가한다. 마이그레이션할 때 만드는 게 아니라 미리 쌓아둔다.
7
+ - **누가 쓰나**: SDK 작성자. 소비자 영향이 있는 변경을 릴리즈하는 **그 시점에** 항목을 추가합니다. 마이그레이션할 때 만드는 게 아니라 미리 쌓아둡니다.
8
8
  - **누가 읽나**: 소비자 프로젝트의 마이그레이션 도구(아래)와 사람.
9
- - **어디에 실리나**: `docs/`는 core 패키지 배포물에 포함되므로, 소비자는 `node_modules/@bstage-sdk/core/docs/MIGRATION.md`로 이 파일을 본다. cli도 빌드 시 `dist/MIGRATION.md`로 같은 파일을 복사해 `bstage doctor`가 동일 가이드를 읽는다.
10
- - **버전 라인과 항목 헤더**: 공개 패키지(cli·core·react·host·design·ai-toolkit)는 **한 버전 라인을 함께 쓴다** — 릴리즈마다 모든 패키지가 같은 번호로 나간다. 항목 헤더는 그중 그 변경을 **실제로 낸 패키지**를 가리키므로(대개 cli·react·ai-toolkit이며 이 파일이 실려 나가는 core가 아닐 수 있다), 헤더가 `cli 0.8.5`인 항목을 적용하려면 **cli**를 0.8.5 이상으로 올려야 한다.
9
+ - **어디에 실리나**: `docs/`는 core 패키지 배포물에 포함되므로, 소비자는 `node_modules/@bstage-sdk/core/docs/MIGRATION.md`로 이 파일을 봅니다. cli도 빌드 시 `dist/MIGRATION.md`로 같은 파일을 복사해 `bstage doctor`가 동일 가이드를 읽습니다.
10
+ - **버전 라인과 항목 헤더**: 공개 패키지(cli·core·react·host·design·ai-toolkit)는 **한 버전 라인을 함께 씁니다** — 릴리즈마다 모든 패키지가 같은 번호로 나갑니다. 항목 헤더는 그중 그 변경을 **실제로 낸 패키지**를 가리키므로(대개 cli·react·ai-toolkit이며 이 파일이 실려 나가는 core가 아닐 수 있습니다), 헤더가 `cli 0.8.5`인 항목을 적용하려면 **cli**를 0.8.5 이상으로 올려야 합니다.
11
11
 
12
12
  ## 마이그레이션이 동작하는 방식
13
13
 
14
- 마이그레이션은 두 단계로 나뉘고, 각 단계에 맞는 도구가 다르다.
14
+ 마이그레이션은 두 단계로 나뉘고, 각 단계에 맞는 도구가 다릅니다.
15
15
 
16
- 1. **감지 (결정론)** — 설치된 SDK 버전과 최신 버전을 비교하고, 누락된 파일·드리프트를 보고한다. 정답이 하나이므로 도구가 기계적으로 처리한다.
17
- 2. **변환 (판단)** — 이 문서의 해당 구간을 읽고, **실제 프로젝트 코드를 보면서** 적용한다. 사용자가 분기시킨 코드를 덮어쓰지 않고 reconcile해야 하므로 AI/사람의 판단이 들어간다.
16
+ 1. **감지 (결정론)** — 설치된 SDK 버전과 최신 버전을 비교하고, 누락된 파일·어긋난 설정(드리프트)을 보고합니다. 정답이 하나이므로 도구가 기계적으로 처리합니다.
17
+ 2. **변환 (판단)** — 이 문서의 해당 구간을 읽고, **실제 프로젝트 코드를 보면서** 적용합니다. 사용자가 분기시킨 코드를 덮어쓰지 않고 맞춰 합쳐야 하므로 AI/사람의 판단이 들어갑니다.
18
18
 
19
- 소비자 프로젝트에서는 AI가 1로 시작 버전을 파악 → 이 문서에서 해당 구간을 읽음 → 프로젝트에 맞춘 작업 계획을 사람에게 제시 → 승인 후 변환을 수행한다.
19
+ 소비자 프로젝트에서는 AI가 1로 시작 버전을 파악 → 이 문서에서 해당 구간을 읽음 → 프로젝트에 맞춘 작업 계획을 사람에게 제시 → 승인 후 변환을 수행합니다.
20
20
 
21
21
  ### 도구
22
22
 
23
- - **감지**: `bstage doctor` (`npx @bstage-sdk/cli@latest doctor`). 버전 드리프트·보일러플레이트 누락·적용 가능한 마이그레이션 항목을 보고한다. 진단 자체는 프로젝트 코드를 고치지 않지만, `--json` 없이 실행하면 SDK가 관리하는 스킬이 뒤처졌을 때 `ai install`과 같은 동기화(스킬·`AGENTS.md` 관리 영역, 없는 `AGENTS.md`·`CLAUDE.md` 생성)를 자동으로 한다. `--json`은 구조화 출력이며 아무것도 쓰지 않는다.
24
- - **변환**: `bstage-migrate` 스킬 (`.claude/skills/bstage-migrate/SKILL.md`). doctor 출력과 이 문서를 읽고 프로젝트에 맞춰 적용한다.
23
+ - **감지**: `bstage doctor` (`npx @bstage-sdk/cli@latest doctor`). 버전 어긋남·보일러플레이트 누락·적용 가능한 마이그레이션 항목을 보고합니다. 진단 자체는 프로젝트 코드를 고치지 않지만, `--json` 없이 실행하면 SDK가 관리하는 스킬이 뒤처졌을 때 `ai install`과 같은 동기화(스킬·`AGENTS.md` 관리 영역, 없는 `AGENTS.md`·`CLAUDE.md` 생성)를 자동으로 합니다. `--json`은 구조화 출력이며 아무것도 쓰지 않습니다.
24
+ - **변환**: `bstage-migrate` 스킬 (`.claude/skills/bstage-migrate/SKILL.md`). doctor 출력과 이 문서를 읽고 프로젝트에 맞춰 적용합니다.
25
25
 
26
26
  ### 마이그레이션 스킬 부트스트랩
27
27
 
28
- - **새 프로젝트** (이 기능 도입 이후 `bstage init`): `.claude/skills/`에 스킬이 이미 들어 있다. 별도 작업 없음.
29
- - **옛 프로젝트**: `npx @bstage-sdk/cli@latest ai install`로 스킬을 설치한다(`.claude/skills/`에 기록). SDK 버전업 후 다시 실행하면 최신으로 동기화된다. 스킬이 없어도 `bstage doctor` 출력 + 이 문서만으로 AI가 마이그레이션을 진행할 수 있다.
28
+ - **새 프로젝트** (이 기능 도입 이후 `bstage init`): `.claude/skills/`에 스킬이 이미 들어 있습니다. 별도 작업이 필요 없습니다.
29
+ - **옛 프로젝트**: `npx @bstage-sdk/cli@latest ai install`로 스킬을 설치합니다(`.claude/skills/`에 기록). SDK 버전업 후 다시 실행하면 최신으로 동기화됩니다. 스킬이 없어도 `bstage doctor` 출력 + 이 문서만으로 AI가 마이그레이션을 진행할 수 있습니다.
30
30
 
31
31
  ## 항목 작성 규칙
32
32
 
33
- 각 항목은 **소비자가 행동해야 하는 변경 하나**를 기술한다. 단순 내부 리팩터링은 적지 않는다(그건 CHANGELOG의 몫).
33
+ 각 항목은 **소비자가 행동해야 하는 변경 하나**를 기술합니다. 단순 내부 리팩터링은 적지 않습니다(그건 CHANGELOG의 몫).
34
34
 
35
- 항목 머리에 두 가지 배지를 단다.
35
+ 항목 머리에 두 가지 배지를 답니다.
36
36
 
37
37
  - 적용 난이도: `자동` (충돌 없이 기계적 적용 가능) / `판단` (사용자 코드 이해 필요)
38
38
  - 필요도: `필수` (안 하면 깨짐) / `선택` (새 기능을 쓸 때만)
39
39
 
40
- 각 항목은 다음 소제목을 갖는다.
40
+ 각 항목은 다음 소제목을 갖습니다.
41
41
 
42
42
  - **영향** — 어떤 프로젝트가 해당되는지 + 감지 방법(어떤 파일/버전을 보면 아는지)
43
43
  - **변경 내용** — 무엇이 왜 바뀌었는지 (배경은 한 줄, 상세는 관련 docs 링크)
44
- - **적용** — 단계. 자동 단계와 판단 단계를 구분해서 적는다.
44
+ - **적용** — 단계. 자동 단계와 판단 단계를 구분해서 적습니다.
45
45
 
46
- > **`적용` 단계는 옛 프로젝트에서 실제로 따라가 본 뒤 적는다.** 새 `bstage init` 프로젝트에서 되는 것과, 기존 프로젝트가 이 절차만 보고 도달하는 것은 다르다. 따라 했을 때 깨지는 선행 조건이 있으면 **그 조건까지 적는다** — 스크립트를 추가하던 항목이 그 사례다(스크립트만 넣으면 `@types/node` 부재로 `TS2688`이 난다. 스캐폴드 템플릿을 고쳐 새 프로젝트는 해결됐지만, 먼저 써둔 적용 절차를 되짚지 않아 기존 프로젝트용 지침이 깨진 채 남았다).
46
+ > **`적용` 단계는 옛 프로젝트에서 실제로 따라가 본 뒤 적습니다.** 새 `bstage init` 프로젝트에서 되는 것과, 기존 프로젝트가 이 절차만 보고 도달하는 것은 다릅니다. 따라 했을 때 깨지는 선행 조건이 있으면 **그 조건까지 적습니다** — 스크립트를 추가하던 항목이 그 사례입니다(스크립트만 넣으면 `@types/node` 부재로 `TS2688`이 납니다. 스캐폴드 템플릿을 고쳐 새 프로젝트는 해결됐지만, 먼저 써둔 적용 절차를 되짚지 않아 기존 프로젝트용 지침이 깨진 채 남았습니다).
47
47
 
48
- > **헤더 규칙**: `## → {패키지} {버전}` 형식으로, 그 변경을 실제로 낸 패키지와 버전을 명시한다(예: `→ cli 0.8.5`, `→ core 0.3.0`). 한 변경이 여러 패키지를 함께 범프시켰으면 소비자가 올려야 할 패키지를 `·`로 나열한다(예: `→ cli 0.8.5 · ai-toolkit 0.8.5`). 소비자는 이 헤더의 패키지를 해당 버전 **이상**으로 올려야 한다. 단순 의존성 재핀(dependency bump)만 된 패키지는 헤더에 적지 않는다.
48
+ > **헤더 규칙**: `## → {패키지} {버전}` 형식으로, 그 변경을 실제로 낸 패키지와 버전을 명시합니다(예: `→ cli 0.8.5`, `→ core 0.3.0`). 한 변경이 여러 패키지를 함께 범프시켰으면 소비자가 올려야 할 패키지를 `·`로 나열합니다(예: `→ cli 0.8.5 · ai-toolkit 0.8.5`). 소비자는 이 헤더의 패키지를 해당 버전 **이상**으로 올려야 합니다. 단순 의존성 재핀(dependency bump)만 된 패키지는 헤더에 적지 않습니다.
49
49
  >
50
- > **정렬**: 릴리즈 **시점 최신이 위**. 공개 패키지는 한 버전 라인을 쓰므로 헤더 숫자 순서가 곧 릴리즈 순서다.
50
+ > **정렬**: 릴리즈 **시점 최신이 위**. 공개 패키지는 한 버전 라인을 쓰므로 헤더 숫자 순서가 곧 릴리즈 순서입니다.
51
51
 
52
52
  ---
53
53
 
54
+ ## → cli 0.14.1 · ai-toolkit 0.14.1
55
+
56
+ ### 용어·문체 표준 적용(CLI 안내 문구·에이전트 스킬·AGENTS.md v18) — `자동`
57
+
58
+ **영향**
59
+
60
+ - 모든 프로젝트. 코드·빌드 동작과 기계 판독 출력은 바뀌지 않습니다.
61
+ - `bstage` 명령의 사람용 안내·프롬프트·도움말 문구, 에이전트 스킬 본문, `AGENTS.md` 관리 영역의 용어가 바뀌었습니다. CLI 출력 문구를 문자열로 비교하는 스크립트가 있다면 확인합니다(`--json` 출력의 키·종료 코드·오류 code는 그대로입니다).
62
+
63
+ **변경 내용**
64
+
65
+ - 콘솔(포털·관리도구·파트너스 → 콘솔), 스테이지(스페이스·Space ID → 스테이지), 페이지·위젯(배치 → 페이지·위젯), 게시·업데이트(적용·반영·배포 → 게시·업데이트), 사용자 화면·운영자 화면(유저·어드민 → 사용자 화면·운영자 화면), APP ID로 통일했습니다.
66
+ - 영어로 남아 있던 `bstage build` 출력과 `bstage dev --help`, host 런타임 오류 문구를 한국어로 바꿨습니다.
67
+ - **AGENTS.md 관리 영역 v18**: 문서 목록에 현행 슬롯 카탈로그(`SLOT_CATALOG_V2.md`)·`INIT.md`·`LIQUID.md`·`AI_TOOLKIT.md`를 넣고, 옛 슬롯 문서에는 "(옛, 참조용)"을 붙였습니다.
68
+ - 명령·옵션 이름(`--space`·`--placement`·`--portal`)과 환경변수 이름은 그대로입니다.
69
+
70
+ **적용**
71
+
72
+ 1. (자동) `npx @bstage-sdk/cli@latest ai update` — 스킬과 `AGENTS.md` 관리 영역을 갱신합니다.
73
+
54
74
  ## → cli 0.13.0
55
75
 
56
76
  ### 콘솔 기본 주소가 `bskit.*`으로 바뀌었다 — `자동`
@@ -125,7 +125,7 @@ function getLoginPageHtml(phase, mode = "user") {
125
125
  const tokenPath = AUTH_TOKEN_PATH_BY_MODE[mode].replace(/^\/svc/, AUTH_PATH_PREFIX);
126
126
  const twoFactorVerifyPath = `${AUTH_PATH_PREFIX}/api/v1/operators/two-factor/validate-and-register`;
127
127
  const modeLabel = mode === "admin" ? "admin" : "user";
128
- const subtitle = mode === "admin" ? "\uB85C\uCEEC \uAC1C\uBC1C \uD658\uACBD \uC5B4\uB4DC\uBBFC \uB85C\uADF8\uC778" : "\uB85C\uCEEC \uAC1C\uBC1C \uD658\uACBD \uB85C\uADF8\uC778";
128
+ const subtitle = mode === "admin" ? "\uB85C\uCEEC \uAC1C\uBC1C \uD658\uACBD \uC6B4\uC601\uC790 \uB85C\uADF8\uC778" : "\uB85C\uCEEC \uAC1C\uBC1C \uD658\uACBD \uB85C\uADF8\uC778";
129
129
  return (
130
130
  /* html */
131
131
  `<!DOCTYPE html>
@@ -281,7 +281,7 @@ function getLoginPageHtml(phase, mode = "user") {
281
281
 
282
282
  <form id="loginForm">
283
283
  <div class="field">
284
- <label for="tenantId">Space ID</label>
284
+ <label for="tenantId">\uC2A4\uD14C\uC774\uC9C0 ID</label>
285
285
  <input id="tenantId" type="text" placeholder="e.g. bmf" autocomplete="off" required />
286
286
  </div>
287
287
  <div class="field">
@@ -384,7 +384,7 @@ function getLoginPageHtml(phase, mode = "user") {
384
384
  }
385
385
 
386
386
  if (data.status === 'PASSWORD_RESET_NEEDED') {
387
- throw new Error('\uBE44\uBC00\uBC88\uD638 \uC7AC\uC124\uC815\uC774 \uD544\uC694\uD55C \uACC4\uC815\uC785\uB2C8\uB2E4. \uC5B4\uB4DC\uBBFC \uC6F9\uC5D0\uC11C \uBA3C\uC800 \uBE44\uBC00\uBC88\uD638\uB97C \uAC31\uC2E0\uD574 \uC8FC\uC138\uC694.');
387
+ throw new Error('\uBE44\uBC00\uBC88\uD638 \uC7AC\uC124\uC815\uC774 \uD544\uC694\uD55C \uACC4\uC815\uC785\uB2C8\uB2E4. \uC6B4\uC601\uC790 \uD654\uBA74\uC5D0\uC11C \uBA3C\uC800 \uBE44\uBC00\uBC88\uD638\uB97C \uAC31\uC2E0\uD574 \uC8FC\uC138\uC694.');
388
388
  }
389
389
 
390
390
  finishSuccess();
@@ -535,7 +535,7 @@ function addCfAccessHeaders(headers, phase) {
535
535
  `[bstage] ${phase}\uB294 \uC0AC\uB0B4 \uC804\uC6A9 \uD658\uACBD\uC774\uB77C Cloudflare Access \uAC8C\uC774\uD2B8 \uB4A4\uC5D0 \uC788\uC2B5\uB2C8\uB2E4.
536
536
  \uC790\uACA9\uC99D\uBA85\uC774 \uC5C6\uC5B4 \uB85C\uADF8\uC778\xB7API \uD504\uB85D\uC2DC\uAC00 302(Cloudflare \uB85C\uADF8\uC778)\uB85C \uB9C9\uD799\uB2C8\uB2E4.
537
537
  \xB7 \uC0AC\uB0B4: CF Access \uC11C\uBE44\uC2A4 \uD1A0\uD070\uC744 \uBC1C\uAE09\uBC1B\uC544 .env\uC5D0 ${idKey}\xB7${secretKey} \uC124\uC815
538
- \xB7 \uADF8 \uC678: --phase sandbox \uB85C \uAC1C\uBC1C\uD558\uC138\uC694 (\uAC8C\uC774\uD2B8\uAC00 \uC5C6\uC5B4 \uC124\uC815\uC774 \uD544\uC694 \uC5C6\uC2B5\uB2C8\uB2E4)`
538
+ \xB7 \uADF8 \uC678: --phase sandbox\uB85C \uAC1C\uBC1C\uD558\uC138\uC694 (\uAC8C\uC774\uD2B8\uAC00 \uC5C6\uC5B4 \uC124\uC815\uC774 \uD544\uC694 \uC5C6\uC2B5\uB2C8\uB2E4)`
539
539
  );
540
540
  }
541
541
  return;
@@ -604,7 +604,7 @@ function resolveDevHosts(phase, mode, cwd = process.cwd()) {
604
604
  `${phase}\uB294 \uC0AC\uB0B4 \uC804\uC6A9 \uD658\uACBD\uC774\uB77C \uD638\uC2A4\uD2B8\uAC00 SDK\uC5D0 \uB4E4\uC5B4 \uC788\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.
605
605
  \uC124\uC815\uB418\uC9C0 \uC54A\uC740 \uAC12: ${missing.join(", ")}
606
606
  \xB7 \uC0AC\uB0B4: \uC704 \uAC12\uC744 .env\uC5D0 \uC124\uC815\uD558\uC138\uC694 (\uD638\uC2A4\uD2B8 \uAC12\uC740 \uC0AC\uB0B4 \uBB38\uC11C\uB97C \uCC38\uACE0\uD558\uC138\uC694)
607
- \xB7 \uADF8 \uC678: --phase sandbox \uB85C \uAC1C\uBC1C\uD558\uC138\uC694 (\uC124\uC815\uC774 \uD544\uC694 \uC5C6\uC2B5\uB2C8\uB2E4)`
607
+ \xB7 \uADF8 \uC678: --phase sandbox\uB85C \uAC1C\uBC1C\uD558\uC138\uC694 (\uC124\uC815\uC774 \uD544\uC694 \uC5C6\uC2B5\uB2C8\uB2E4)`
608
608
  );
609
609
  }
610
610
  return {