@bstage-sdk/cli 0.4.1 → 0.5.0

package/dist/MIGRATION.md

@@ -50,6 +50,164 @@
 > **정렬**: 릴리즈 **시점 최신이 위**. 패키지가 독립 버전이라 헤더 숫자만으로는 시간순 정렬이 되지 않으므로 릴리즈 순서를 기준으로 한다.
 
 ---
+## → cli 0.5.0
+
+### liquid 에셋은 포털 미디어에 올린다 — 레포 상대 경로는 배포 후 깨진다 — `판단` · `필수`
+
+**영향**
+
+- liquid 템플릿 레포 전부. 이미지·영상을 레포에 두고 상대 경로(`images/logo.png`·`/user/home/images/logo.png`)로 참조하는 템플릿이 해당한다.
+- 감지: 배포한 화면에서 이미지가 뜨지 않는다(요청이 404). **로컬 프리뷰에서는 정상으로 보이므로 프리뷰로는 감지되지 않는다.**
+
+**변경 내용**
+
+포털은 템플릿 폴더를 그대로 복사하지만, 렌더된 HTML이 스페이스 도메인 페이지 안으로 들어간다. 그래서 상대 경로는 그 도메인 기준으로 풀리고 산출물이 놓인 주소를 가리키지 않는다. 옛 가이드에 있던 "`public`에 두고 상대 경로로 참조" 안내는 신규 포털에서 맞지 않는다.
+
+지금 방법은 포털 화면의 스테이지 > 미디어에 파일을 올리고, 받은 URL을 템플릿에 절대 주소로 넣는 것이다. 이미지와 영상만 올릴 수 있고, 허용 형식·용량 한도는 업로드할 때 화면이 알려 준다.
+
+`bstage ai install`·`update`가 놓는 `AGENTS.md`·`bstage-liquid` 스킬도 같은 내용으로 바뀌었다(관리 영역 v12).
+
+**적용**
+
+1. (판단) 템플릿에서 상대 경로로 참조하는 에셋을 찾는다.
+2. (판단) 해당 파일을 포털 미디어에 올리고 받은 URL로 참조를 바꾼다.
+3. (자동) `npx @bstage-sdk/cli@latest ai update`로 스킬·`AGENTS.md`를 최신 안내로 갱신한다.
+
+### liquid `data.json` 샘플 키를 플랫폼 계약에 맞춘다 — `판단` · `선택`
+
+**영향**
+
+- liquid 템플릿 레포. `data.json`이 `title`·`heading`·`description` 같은 임의 이름을 쓰고 있으면 해당한다.
+- 감지: 로컬 프리뷰에서는 값이 그려지는데 배포하면 그 자리가 빈다.
+
+**변경 내용**
+
+플랫폼이 유저 화면 템플릿에 넣는 최상위 값은 `lounges` · `stories` · `contentSections` · `latestContents` · `shopCategories` 다섯 개다. 그 밖의 이름은 빈 문자열이 된다. 스캐폴드가 만드는 `data.json`과 첫 `template.liquid`가 이 이름을 쓰도록 바뀌었다. 각 항목의 필드는 계약이 아니라 모양을 보기 위한 예시이므로 실제 렌더 결과로 확인한다. 어드민 화면이 받는 값은 확인되지 않았다.
+
+**적용**
+
+1. (판단) `data.json`의 최상위 키를 위 다섯 개 중 쓰는 것으로 바꾸고, 템플릿의 변수 이름도 함께 맞춘다.
+2. (자동) 새로 만드는 프로젝트는 `bstage init --kind liquid`가 이미 맞춰 준다.
+
+### `bstage docs`가 문서를 못 찾으면 종료 코드 2 — `자동` · `선택`
+
+**영향**
+
+- `bstage docs`의 종료 코드를 확인하는 스크립트·CI. SDK 의존이 없는 레포(예: `.liquid` 파일만 둔 레포)에서 이 경로를 탄다.
+
+**변경 내용**
+
+예전에는 "문서를 찾을 수 없습니다"를 출력하고도 0으로 끝나서, 종료 코드로 갈래를 잡는 호출자가 문서를 읽은 것으로 착각했다. 이제 2로 끝나고, liquid 레포에서는 `bstage-liquid` 스킬을 보라는 안내가 함께 나온다.
+
+**적용**
+
+1. (자동) 문서 유무를 그냥 확인만 하던 자리라면 종료 코드 2를 허용하도록 고친다.
+
+### `bstage skills install` → `bstage ai install` — `자동` · `선택`
+
+**영향**
+
+- 스크립트·문서·CI에 `bstage skills install`을 적어 둔 프로젝트. 명령 자체는 아직 동작하므로 당장 깨지지는 않는다.
+- 감지: 레포에서 `skills install` 문자열을 찾는다. 실행하면 `bstage ai install`로 바뀌었다는 경고가 뜬다.
+
+**변경 내용**
+
+스킬만이 아니라 `AGENTS.md`·`CLAUDE.md`·pre-commit 시크릿 가드까지 다루게 되어 이름이 맞지 않게 됐다. `bstage ai install`(설치·갱신) · `bstage ai update`(있는 파일만 갱신) · `bstage ai doctor`(진단, `--json`, 종료코드 0·2)로 나뉘었고, `bstage skills install`은 deprecated 별칭으로 남아 경고 후 `ai install`을 그대로 수행한다. 별칭은 **다음 릴리즈에서 제거된다.** 설치되는 콘텐츠는 새 패키지 `@bstage-sdk/ai-toolkit`이 들고 있고, cli가 그 패키지를 의존하므로 따로 설치할 필요는 없다.
+
+이 명령들은 **프로젝트 종류(`sdk`·`liquid`)를 판정해 그 종류의 자산만 설치한다.** 판정은 레포의 파일 구조로 한다(포털 빌더와 같은 규칙). 템플릿 파일이 아직 없어 판정이 안 되는 레포에서는 종료 코드 2로 끝나므로 `bstage ai install --kind sdk` 또는 `--kind liquid`로 지정한다. 두 종류가 한 레포에 섞여 있으면 포털이 빌드하지 못하므로 역시 종료 코드 2로 멈춘다.
+
+자세한 내용은 `AI_TOOLKIT.md`를 참고한다.
+
+**적용**
+
+1. (자동) 스크립트·문서의 `bstage skills install`을 `bstage ai install`로 바꾼다.
+2. (자동) CI에서 최신 여부만 확인하려면 `bstage ai doctor --json`을 쓴다 — 전부 최신이면 0, 하나라도 어긋나면 2로 끝난다.
+3. (판단) 판정이 실패하는 빈 레포에서만 `--kind`를 붙인다. 판정 결과와 다른 값을 주면 덮어쓰지 않고 멈추므로, 어긋나면 옵션을 빼고 다시 실행한다.
+
+### AGENTS.md 관리 영역 갱신 · 스킬 2종 추가(`bstage-onboarding`·`bstage-deploy`) — `자동` · `선택`
+
+**영향**
+
+- `bstage init`으로 만든 모든 프로젝트. 관리 영역이 낡았거나 새 스킬이 없으면 해당한다.
+- 감지: `bstage ai doctor`가 해당 항목을 `stale`·`missing`으로 보고한다(`bstage doctor`의 에이전트 스킬 절에도 나온다).
+
+**변경 내용**
+
+- `AGENTS.md`의 SDK 관리 영역에 배포 절이 추가되고, 프로젝트 종류(`sdk`·`liquid`)에 따라 본문이 갈린다. 마커 바깥 자유 영역은 그대로 보존된다.
+- 스킬이 둘 늘었다. `bstage-onboarding`(빈손에서 첫 배포까지 안내) · `bstage-deploy`(배포·롤백·게시). 기존 `bstage-template`·`bstage-migrate`는 그대로다.
+- 스캐폴드 `package.json`에 `bstage.kind`가 기록된다. **기존 프로젝트는 없어도 동작한다** — 종류 판정은 파일 구조로 하고 이 값은 읽지 않는다. 추가는 선택이다.
+- `bstage doctor --json`에 `skillsSkipped` 필드가 생겼다(두 종류가 섞여 스킬 검사를 건너뛴 경우 `true`). 기존 필드는 그대로이므로 비파괴적 추가다.
+
+**적용**
+
+1. (자동) `npx @bstage-sdk/cli@latest ai install` — 없는 스킬을 만들고 관리 영역을 갱신한다. 이미 있는 것만 최신화하려면 `ai update`.
+2. (판단) `AGENTS.md`에 관리 영역 마커가 없는 레거시 파일이면 자동 갱신 대상이 아니다. 명령이 레거시로 표시하고 건드리지 않으므로 `bstage-migrate` 스킬로 기존 내용과 reconcile한다.
+3. (자동) 다른 종류의 스킬이 남아 있으면 `extra`로 보고되지만 지우지 않는다. 필요 없으면 직접 삭제한다 — 종료 코드에는 영향이 없다.
+
+### liquid 템플릿 레포 지원 — `자동` · `선택`
+
+**영향**
+
+- liquid 템플릿(`public/{user|admin}/{이름}/template.liquid`)으로 포털에 배포하는 레포. 기존 SDK 프로젝트에는 영향이 없다.
+- 감지: 레포에 위 경로의 `template.liquid`가 있으면 cli가 liquid 레포로 판정한다.
+
+**변경 내용**
+
+- `bstage init --kind liquid`가 liquid 레포를 스캐폴드한다. React·Vite 없이 cli 하나만 의존한다.
+- `bstage dev`가 liquid 레포에서는 liquidjs 로컬 프리뷰를 띄운다(템플릿 목록·데이터 렌더·정적 파일·자동 리로드). 루프백에만 바인딩하고 템플릿 디렉터리 밖을 가리키는 경로는 차단한다. 인증 프록시는 없다.
+- `bstage build`는 liquid 레포에서 **검증만** 한다(파스 오류·규약 밖 파일·폴더명·데이터 파일). 오류면 종료 코드 2. 포털이 파일을 그대로 패키징하므로 빌드 산출물은 만들지 않는다.
+- `bstage doctor`에 liquid 진단 절이 생겼고, 배포 명령(`deploy`·`list`·`rollback`·`publish`)은 종류와 무관하게 같은 방식으로 동작한다.
+
+**적용**
+
+1. (자동) 기존 liquid 레포에서 `npx @bstage-sdk/cli@latest ai install`을 실행하면 liquid용 스킬과 `AGENTS.md`가 놓인다.
+2. (자동) 로컬 확인은 `bstage dev`, 배포 전 검증은 `bstage build`.
+3. (판단) SDK 템플릿과 liquid 템플릿을 한 레포에 섞지 않는다 — 포털 빌더가 빌드하지 못하고 cli도 종료 코드 2로 멈춘다.
+
+자세한 내용은 `LIQUID.md`를 참고한다.
+
+---
+
+### liquid 파셜(`{% render %}`·`{% include %}`)은 배포에서 동작하지 않는다 — `판단` · `필수`
+
+**영향**
+
+- liquid 템플릿 레포 중 템플릿을 파셜로 쪼갠 곳. 옛 문서가 "탐색 루트는 `public/`"이라고만 적어 프리뷰에서 되는 것을 배포에서도 되는 것으로 읽게 했다.
+- 감지: `bstage build`가 파셜 태그를 경고로 짚는다. 배포 화면에서는 그 자리가 비어 보인다.
+
+**변경 내용**
+
+배포 뷰어의 엔진은 레포의 파일을 찾지 못해 파셜 자리를 빈 문자열로 렌더한다. 문서·`bstage-liquid` 스킬·`AGENTS.md` 관리 영역이 그렇게 안내한다.
+
+**적용**
+
+1. (판단) 파셜 내용을 `template.liquid`에 인라인으로 옮긴다.
+2. (자동) `npx @bstage-sdk/cli@latest ai update`로 스킬·`AGENTS.md`를 갱신한다.
+
+### pre-commit 시크릿 가드 보강 — `자동` · `선택`
+
+가드(`.husky/check-secrets.mjs`)가 포털 CLI 토큰 형태를 잡고, 크기 때문에 읽지 못한 파일을 검사 없이 통과시키던 것을 막으며(읽지 못하면 차단), NUL 바이트가 든 파일도 훑고, `.env.{phase}`의 SECRET·TOKEN·PASSWORD 계열 키에 실제 값이 있으면 차단한다. 알림에 값의 앞부분을 드러내지 않는다(길이만). `.env.example` 계열은 값 검사에서 빠지지만 키·토큰 검사는 그대로 받는다. `npx @bstage-sdk/cli@latest ai install`이 갱신한다.
+
+### pre-commit 가드 줄이 정본 자리·정본 형태로 재배치된다 — `자동` · `선택`
+
+가드 줄은 **shebang 다음 첫 줄에 `node .husky/check-secrets.mjs || exit 1`** 형태일 때만 그대로 둔다. 기존 훅의 가드 줄이 함수 본문·조건 블록 안에 있거나, 상태를 전파하지 않거나, `exit` 뒤에 있으면 `bstage ai install`·`update`가 그 줄을 지우고 정본 자리에 다시 넣는다(훅의 나머지 내용은 보존). 셸 제어 흐름을 정규식으로 판정할 수 없어 "애매하면 다시 넣는" 쪽으로 정했다.
+
+### SDK 소유 파일 쓰기가 링크를 따라가지 않는다 — `자동` · `선택`
+
+`ai install`·`update`가 파일을 쓸 때 대상과 경로 중간 디렉터리를 realpath로 검사하고, 여는 순간 심볼릭 링크를 거부하며, 하드 링크가 걸렸거나 일반 파일이 아니면(디렉터리·FIFO) 손대지 않는다. 레포에 커밋된 링크로 프로젝트 밖 파일이 바뀌는 경로를 막는다. 기존 파일의 느슨한 권한도 함께 바로잡는다.
+
+### 손수정한 스킬은 `.bak`으로 남긴다 — `자동` · `선택`
+
+`bstage ai install`·`update`가 손으로 고친 `SKILL.md`를 SDK 본문으로 되돌릴 때 기존 본문을 `SKILL.md.bak`에 남긴다. 프로젝트 고유 규칙은 `AGENTS.md` 자유 영역에 옮긴 뒤 `.bak`은 지운다.
+
+### `bstage build`가 빌드할 것을 못 찾으면 종료 코드 2 — `자동` · `선택`
+
+`src/pages`·`src/slots`에 `template.tsx`가 없거나 `.liquid`가 전부 규약 밖 자리에 있을 때 1로 끝나던 것을 2(사전조건 미충족)로 바꿨다 — liquid 검증 실패·`deploy` 사전점검과 같은 부류다. 종료 코드로 갈래를 잡는 스크립트만 영향받는다. `bstage dev`도 규약 밖 `.liquid`를 시작 전에 경고한다.
+
+### 프로젝트에 고정된 옛 CLI로 실행하면 하향임을 알린다 — `판단` · `선택`
+
+옛 `bstage`로 `doctor`·`ai install`을 돌리면 새 CLI가 놓은 스킬·가드를 "구버전/수정됨"으로만 표시하고 옛 본문으로 덮었다. 이제 설치본의 버전이 더 높으면 **하향**임을 분명히 알리고 최신 CLI로 다시 실행하라고 안내한다. 덮어쓰기 자체는 막지 않는다 — 파일 안의 버전 표기는 누구나 적을 수 있어, 그것으로 덮어쓰기를 막으면 높은 버전을 자칭한 임의 본문이 가드·스킬 자리에 영구히 남는다. 진단·갱신은 항상 `npx @bstage-sdk/cli@latest`로 실행한다.
+
 ## → core 0.3.0 · cli 0.3.0
 
 ### 앱 키 이름 정리(`appSecret` → `appKey`, `VITE_BSTAGE_APP_SECRET` → `VITE_BSTAGE_APP_KEY`) — `판단` · `선택`