@bstage-sdk/core 0.5.0 → 0.6.1

package/dist/index.cjs

@@ -174,7 +174,7 @@ var HttpTimeoutError = class extends Error {
 };
 
 // src/version.ts
-var VERSION = "0.5.0";
+var VERSION = "0.6.1";
 
 // src/client/BstageClient.ts
 function resolveBaseUrl() {

package/dist/index.js

@@ -119,7 +119,7 @@ var HttpTimeoutError = class extends Error {
 };
 
 // src/version.ts
-var VERSION = "0.5.0";
+var VERSION = "0.6.1";
 
 // src/client/BstageClient.ts
 function resolveBaseUrl() {

package/docs/AI_TOOLKIT.md

@@ -22,16 +22,19 @@
 
 스킬 세트는 프로젝트 종류(kind)로 갈립니다.
 
-| kind     | 설치되는 스킬                                                                |
-| -------- | ---------------------------------------------------------------------------- |
-| `sdk`    | `bstage-template` · `bstage-migrate` · `bstage-onboarding` · `bstage-deploy` |
-| `liquid` | `bstage-liquid` · `bstage-migrate` · `bstage-onboarding` · `bstage-deploy`   |
+| kind     | 설치되는 스킬                                                                                                        |
+| -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `sdk`    | `bstage-template` · `bstage-migrate` · `bstage-onboarding` · `bstage-deploy`                                         |
+| `liquid` | `bstage-liquid` · `bstage-migrate` · `bstage-onboarding` · `bstage-deploy`                                           |
+| `mixed`  | 위 두 세트의 합집합 — `bstage-template` · `bstage-liquid` · `bstage-migrate` · `bstage-onboarding` · `bstage-deploy` |
 
 kind는 레포의 **파일 구조**로 판정합니다. `public/{user|admin}/{이름}/template.liquid`가 하나 이상이면
 liquid, liquid 파일이 없고 `src/pages|slots/**/template.tsx`가 있거나 SDK 패키지를 의존하면 sdk입니다.
-템플릿 파일이 **양쪽 다** 있으면 `mixed`이고, 포털이 빌드하지 못하므로 명령이 종료 코드 2로 멈춥니다.
-의존성만으로는 mixed가 되지 않습니다 — liquid 파일이 있으면 `@bstage-sdk/cli`를 의존해도
-liquid입니다(liquid 스캐폴드도 저작 도구로 CLI를 씁니다).
+템플릿 파일이 **양쪽 다** 있으면 `mixed`(혼합 레포)이고, 두 세트의 스킬을 모두 설치하며 `AGENTS.md`는
+두 구조와 혼합 규칙(sdk 페이지 `user`·`admin` 금지 · `bstage dev --kind` · `bstage build` 동작)을 담은
+혼합 본문이 됩니다. `mixed`는 판정으로만 나오고 `--kind`로 지정하는 값이 아닙니다 — 혼합 레포에
+`--kind sdk|liquid`를 주면 판정과 어긋나 멈춥니다. 의존성만으로는 mixed가 되지 않습니다 — liquid 파일이
+있으면 `@bstage-sdk/cli`를 의존해도 liquid입니다(liquid 스캐폴드도 저작 도구로 CLI를 씁니다).
 
 ## 3. 어느 도구가 무엇을 읽나
 
@@ -61,7 +64,7 @@ liquid입니다(liquid 스캐폴드도 저작 도구로 CLI를 씁니다).
 
 `doctor`의 종료 코드는 전부 최신이면 0, 하나라도 어긋나면 2입니다. 상태 값은 `ok` · `stale` · `missing` ·
 `extra`이며, **`extra`(지금 kind에 속하지 않는 SDK 스킬이 남아 있음)는 경고일 뿐 종료 코드에 영향을 주지
-않습니다.** 설치가 남의 파일을 지우지 않는 것이 설계라, 실패로 치면 사람이 손으로 지울 때까지 CI가 계속
+않습니다.** 혼합 레포에서는 어느 SDK 스킬도 `extra`가 아닙니다(두 세트가 모두 대상). 설치가 남의 파일을 지우지 않는 것이 설계라, 실패로 치면 사람이 손으로 지울 때까지 CI가 계속
 빨간불이 되기 때문입니다.
 
 ## 5. 처음 시작하는 법

package/docs/BUILD_SYSTEM.md

@@ -162,10 +162,10 @@ bstage build --json   # { "kind": "liquid", "issues": [...] } 한 덩어리
 
 종료코드는 오류가 하나라도 있으면 `2`, 없으면 `0`입니다. `dist/`는 만들어지지 않습니다.
 
-| 수준  | 검사                                                                                                                                                               |
-| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| error | `template.liquid` 문법 오류(줄 번호 표시) · `data.json` JSON 파싱 실패 · 폴더 이름 규칙(`^[a-z][a-z0-9-]*$`) 위반 · sdk 템플릿과 혼재 · liquid 템플릿 0개          |
-| warn  | `public/{user\|admin}/{이름}/` 밖이거나 깊이가 다른 `template.liquid`(포털이 무시) · `layout.json` 존재(포털이 지움) · 폴더에 `template.liquid`가 아닌 이름만 있음 |
+| 수준  | 검사                                                                                                                                                                          |
+| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| error | `template.liquid` 문법 오류(줄 번호 표시) · `data.json` JSON 파싱 실패 · 폴더 이름 규칙(`^[a-z][a-z0-9-]*$`) 위반 · liquid 템플릿 0개 · (혼합 레포) sdk 페이지 `user`·`admin` |
+| warn  | `public/{user\|admin}/{이름}/` 밖이거나 깊이가 다른 `template.liquid`(포털이 무시) · `layout.json` 존재(포털이 지움) · 폴더에 `template.liquid`가 아닌 이름만 있음            |
 
 같은 검사를 `bstage doctor`도 "liquid 검증" 절에서 보여 줍니다(`--json`의 `liquid.issues`).
 
@@ -174,11 +174,25 @@ bstage build --json   # { "kind": "liquid", "issues": [...] } 한 덩어리
 - `public/user/` · `public/admin/` 아래 **한 단계** 폴더만 템플릿으로 인정합니다 — `public/user/events/summer/template.liquid` 는 무시됩니다.
 - 그 폴더를 통째로 복사한 뒤 `data.json` · `layout.json` 을 지웁니다. 두 파일은 로컬 프리뷰와 관리도구의 것이라 배포에 나가지 않습니다 — 배포에 필요한 값을 거기 두지 마세요.
 - 그 밖의 위치에 있는 `template.liquid` 는 무시합니다.
-- sdk(`src/pages` · `src/slots` 의 `template.tsx`)와 섞인 레포는 지원하지 않습니다. `bstage build` · `bstage deploy` 가 포털에 가기 전에 막습니다.
+- sdk(`src/pages` · `src/slots` 의 `template.tsx`)와 섞인 레포(혼합 레포)는 sdk를 빌드한 뒤 liquid를 함께 패키징합니다 — 아래 "혼합 레포"를 참고하세요.
 - 배치는 페이지(PAGE)만 가능합니다. 위젯(SLOT) 자리에 liquid 산출물을 붙이면 포털이 400을 냅니다 — `bstage deploy` 가 빌드를 만들기 전에 사전조건 오류로 끊습니다.
 
 로컬에서 화면을 보려면 `bstage dev`를 씁니다(같은 폴더의 `data.json`으로 렌더). 자세한 내용은 [DEV_SERVER.md](./DEV_SERVER.md)를 참고하세요.
 
+### 혼합 레포(sdk + liquid)
+
+한 레포에 `src/pages|slots/**/template.tsx`와 `public/{user|admin}/{이름}/template.liquid`가 함께 있으면 **혼합 레포**입니다. 포털 빌더는 sdk 경로(의존성 설치 → `bstage build`)를 탄 뒤 liquid 폴더를 함께 `dist/{user|admin}/{이름}/`으로 패키징하고, 포털은 산출물 항목마다 종류(`sdk`·`liquid`)를 따로 봅니다.
+
+```bash
+bstage build          # sdk 엔트리 번들 + liquid 검증 (dist/에 liquid는 넣지 않음 — 포털이 public/에서 패키징)
+bstage build --json   # { "kind": "mixed", "issues": [...], "sdk": { "templates": [...], "outputs": [...] }, "liquid": { "templates": [...] } }
+```
+
+- 검증(liquid 문법·규약 + 아래 충돌)을 번들보다 먼저 합니다. 오류가 있으면 번들하지 않고 종료코드 `2`, 번들 실패는 sdk 레포와 같이 `1`입니다.
+- **`src/pages/user/…`·`src/pages/admin/…` 페이지는 만들 수 없습니다(대소문자 무시 — `User`도 같습니다).** 산출물이 `dist/user/…`로 나가 liquid 자리와 같은 트리에 놓이고, 같은 디렉터리에 `template.js`와 `template.liquid`가 함께 있으면 포털이 sdk로만 판정해 liquid가 조용히 사라집니다. `bstage build`와 포털 빌더가 모두 여기서 막습니다. 위젯(`src/slots`)은 슬롯 id로 나가므로 해당 없습니다.
+- `--json` 동안 진행 로그는 stderr로 나갑니다 — stdout에는 JSON 객체 하나만 있습니다.
+- `bstage deploy`는 혼합 레포를 그대로 배포합니다(안내 한 줄). 위젯(SLOT) 배치 사전점검은 liquid 전용 레포에서만 하고, 혼합 레포의 항목별 판정은 포털이 합니다.
+
 liquid 레포를 만드는 것부터 배포까지의 전체 흐름은 [LIQUID.md](./LIQUID.md)에 정리돼 있습니다.
 
 ---

package/docs/DEV_SERVER.md

@@ -375,9 +375,16 @@ bstage dev -p 5180    # 포트 지정
 - `public/user/events/summer/template.liquid` — 한 단계 더 깊어 무시됩니다(프리뷰는 렌더해 줍니다).
 - `public/shared/hero/template.liquid` — user·admin 밖이라 무시됩니다(경로만 경고로 표시).
 
-### 한 레포에 섞여 있으면
+### 한 레포에 섞여 있으면 — `--kind`로 고릅니다
 
-liquid 템플릿과 React 템플릿(`src/**/template.tsx`)이 함께 있으면 포털 빌더가 빌드하지 못합니다. `bstage dev`는 이 경우 서버를 띄우지 않고 종료코드 **2**로 안내합니다.
+liquid 템플릿과 React 템플릿(`src/pages|slots/**/template.tsx`)이 함께 있는 혼합 레포에서 `bstage dev`는 서버를 **하나만** 띄웁니다. 기본은 sdk(Vite) 프리뷰이고, 시작할 때 liquid 프리뷰를 띄우는 방법을 한 줄 안내합니다.
+
+```bash
+bstage dev                 # 혼합 레포: sdk(Vite) 프리뷰
+bstage dev --kind liquid   # 혼합 레포: liquid 프리뷰
+```
+
+단일 종류 레포에서 판정과 어긋난 `--kind`(liquid 레포에 `--kind sdk` 등)를 주면 종료코드 **2**로 멈춥니다 — 없는 쪽을 띄우면 "엔트리를 못 찾았다"는 엉뚱한 오류로 끝나기 때문입니다.
 
 ---
 

package/docs/LIQUID.md

@@ -112,7 +112,7 @@ bstage build --json    # { "kind": "liquid", "issues": [...] } 한 덩어리
 
 ## 8. 함정
 
-- **sdk와 섞지 않습니다.** 섞이면 `bstage dev`·`build`·`deploy`가 종료 코드 2로 멈추고 포털 빌드도 실패합니다.
+- **sdk와 함께 둘 수 있습니다(혼합 레포).** `bstage build`는 sdk 템플릿만 번들하고 liquid는 검증만 하며(`dist/`에 liquid를 넣지 않습니다), 포털은 sdk를 빌드한 뒤 liquid를 함께 패키징합니다. 단 `src/pages/user`·`src/pages/admin` 페이지는 산출물이 liquid 자리(`dist/{user|admin}/`)와 겹쳐 `bstage build`가 종료 코드 2로 멈춥니다 — 폴더 이름을 바꾸세요. `bstage dev`는 혼합 레포에서 기본으로 sdk 프리뷰를 띄우고, `--kind liquid`로 liquid 프리뷰를 띄웁니다.
 - **깊이가 규약입니다.** `public/{user|admin}/{이름}/template.liquid`, 정확히 이 자리만 인정됩니다. 어긋나면 빌드는 성공하는데 화면에 나오지 않습니다.
 - **페이지(PAGE) 배치만** 됩니다. 위젯 자리에 붙이면 포털이 400을 냅니다.
 - **`data.json`·`layout.json`은 로컬 전용입니다.** 포털이 패키징에서 지우므로 배포에 필요한 값을 여기에 담지 마세요.

package/docs/MIGRATION.md

@@ -50,6 +50,53 @@
 > **정렬**: 릴리즈 **시점 최신이 위**. 패키지가 독립 버전이라 헤더 숫자만으로는 시간순 정렬이 되지 않으므로 릴리즈 순서를 기준으로 한다.
 
 ---
+
+## → cli 0.6.0
+
+### sdk와 liquid 템플릿이 한 레포에 있어도 빌드·배포된다(혼합 레포) — `자동` · `선택`
+
+**영향**
+
+- **단일 종류(sdk만·liquid만) 레포가 할 일은 없다.** 명령·산출물이 그대로다.
+- `mixed`(sdk 템플릿 + liquid 템플릿)로 판정돼 `bstage build`·`dev`·`deploy`가 종료 코드 2로 멈추던 레포는 이제 진행한다.
+- 감지: `bstage build`가 "liquid 템플릿 N개 … 포털이 … 패키징합니다" 안내를 낸다. `bstage deploy`도 혼합 안내 한 줄을 낸다.
+
+**변경 내용**
+
+- **`bstage build`**: 혼합 레포에서 sdk 엔트리만 번들하고 liquid는 검증만 한다 — `dist/`에 liquid를 넣지 않는다(포털 빌더가 push된 커밋의 `public/{user|admin}/{이름}/`을 sdk 산출물과 함께 패키징한다). 검증은 번들보다 먼저 하고, 오류가 있으면 번들 없이 종료 코드 2다. `--json`은 `{ "kind": "mixed", "issues", "sdk": { "templates", "outputs" }, "liquid": { "templates" } }` 객체 하나를 stdout에 쓰고 진행 로그는 stderr로 보낸다.
+- **예약 이름**: 혼합 레포에서 `src/pages/user/…`·`src/pages/admin/…` 페이지는 error다. 산출물이 `dist/{user|admin}/…`로 나가 liquid 자리와 겹치고, 같은 디렉터리에 `template.js`와 `template.liquid`가 함께 있으면 포털이 sdk로만 판정해 liquid가 조용히 사라진다. 포털 빌더도 같은 자리에서 막는다. 위젯(`src/slots`)은 해당 없다.
+- **`bstage deploy`**: 혼합 레포를 막지 않는다. 위젯(SLOT) 배치 사전점검은 liquid 전용 레포에서만 하고, 혼합 레포의 항목별 판정(liquid 항목에 SLOT을 걸면 400)은 포털이 한다.
+- **`bstage dev --kind <sdk|liquid>`**: 혼합 레포에서 어느 프리뷰를 띄울지 고른다. 기본은 sdk(Vite)이고 시작할 때 liquid 프리뷰 방법을 안내한다. 두 서버를 함께 띄우지 않는다. 단일 종류 레포에서 판정과 어긋난 값은 종료 코드 2다.
+- **liquid 검증기**(`bstage build`·`bstage doctor`의 liquid 절)는 sdk와 섞인 것을 더 이상 error로 보고하지 않는다.
+- **포털 빌더는 별도로 갱신된다.** 갱신 전 포털은 혼합 레포에서 liquid만 패키징하므로, CLI와 빌더가 모두 반영된 뒤 혼합 레포를 배포한다.
+
+**적용**
+
+1. (자동) 단일 종류 레포는 그대로 둔다 — 올리기만 하면 된다.
+2. (판단) 혼합 레포를 만들 때: liquid는 `public/{user|admin}/{이름}/template.liquid`, sdk 페이지는 `src/pages/{이름}/template.tsx`(`user`·`admin` 제외), 위젯은 `src/slots/…`. `bstage build`가 겹치는 자리를 짚어 준다.
+3. (자동) 혼합 레포의 liquid 프리뷰는 `bstage dev --kind liquid`.
+
+### AGENTS.md 관리 영역 v14 · 혼합 레포 스킬 세트(`bstage ai install`·`doctor`) — `자동` · `선택`
+
+**영향**
+
+- `bstage init`으로 만든 모든 프로젝트. 관리 영역이 v14보다 낮으면 해당한다(본문 문구 변경 — liquid 본문의 "sdk와 섞지 않는다"가 공존 규칙으로 바뀌었다).
+- `mixed`로 판정돼 `bstage ai install`·`update`가 종료 코드 2로 멈추고 `bstage doctor`가 스킬 검사를 건너뛰던 혼합 레포.
+- 감지: `bstage ai doctor`가 `AGENTS.md`를 `stale`로 보고한다. 혼합 레포에서는 `bstage-template`·`bstage-liquid` 둘 다 검사 대상이 된다.
+
+**변경 내용**
+
+- `bstage ai install`·`update`·`doctor`가 혼합 레포를 지원한다 — 스킬은 sdk 세트와 liquid 세트의 **합집합**(5종)을 설치하고, `AGENTS.md` 관리 영역은 두 구조와 혼합 규칙(어느 방식으로 만들지 · sdk 페이지 `user`·`admin` 금지 · `bstage build`·`dev --kind` 동작)을 담은 **혼합 본문**이 된다. `mixed`는 판정으로만 나오며 `--kind`로 지정하는 값이 아니다 — 혼합 레포에 `--kind sdk|liquid`를 주면 판정과 어긋나 멈춘다.
+- `bstage doctor`는 혼합 레포에서 스킬 검사를 건너뛰지 않고 두 세트를 모두 보며, liquid 검증 결과도 함께 낸다. `--json`의 `skillsSkipped`는 항상 `false`다(필드는 비파괴적으로 남긴다).
+- **레포 종류가 바뀐 뒤의 `AGENTS.md`** — sdk 레포에 liquid 템플릿을 더해 혼합이 되면 관리 영역 마커 버전은 그대로라, 예전에는 옛 sdk 본문이 "최신"으로 남았다. 이제 `bstage ai install`·`update`·`doctor`가 본문을 현재 종류의 렌더 결과와 비교해 다르면 갱신(`update`)·`stale`로 본다. 자유 영역은 보존된다.
+- **관리 영역이 이 CLI보다 새 버전이면 하향임을 알린다.** 프로젝트에 고정된 옛 CLI로 `ai install`·`update`·`doctor`를 돌리면 새 CLI가 놓은 관리 영역을 옛 본문으로 되돌리게 된다 — 그 사실을 알리고 최신 CLI로 다시 실행하라고 안내한다. 덮어쓰기 자체는 막지 않는다(마커 버전은 파일 안의 자기선언 값이다).
+- `bstage-onboarding`·`bstage-liquid` 스킬과 `AGENTS.md`의 "한 레포에 한 방식만" 문구를 공존 규칙(예약 이름 · `dev --kind liquid`)으로 바꿨다.
+
+**적용**
+
+1. (자동) `npx @bstage-sdk/cli@latest ai update` — 스킬·`AGENTS.md` 관리 영역을 v14로 갱신한다. 혼합 레포에서는 없는 스킬도 만들어야 하므로 `ai install`을 쓴다.
+2. (판단) 혼합 레포의 `AGENTS.md` 자유 영역에 "한 레포에 한 방식만" 류의 자체 규칙을 적어 두었다면 지운다 — 관리 영역과 어긋난다.
+
 ## → cli 0.5.0
 
 ### liquid 에셋은 포털 미디어에 올린다 — 레포 상대 경로는 배포 후 깨진다 — `판단` · `필수`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bstage-sdk/core",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "bstage SDK core — HTTP client for b.stage API",
   "type": "module",
   "publishConfig": {