@bstage-sdk/cli 0.5.0 → 0.6.1

package/dist/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/dist/index.js

@@ -662,6 +662,13 @@ function detectProjectKind(root) {
     hasSdkDependency: sdkDependency
   };
 }
+function collidingSdkPages(report2) {
+  if (report2.liquidTemplates.length === 0) return [];
+  return report2.sdkTemplates.filter((t) => {
+    const [root, first] = t.split("/");
+    return root === "pages" && first !== void 0 && LIQUID_SURFACES.has(first.toLowerCase());
+  });
+}
 
 // src/commands/ai/context.ts
 var DEFAULT_SKILLS_DIR = ".claude/skills";
@@ -703,10 +710,13 @@ function resolveKind(root, requested) {
   const wanted = parseKindOption(requested);
   const detected = detectProjectKind(root).kind;
   if (detected === "mixed") {
-    fail(
-      ExitCode.PRECONDITION,
-      "sdk\uC640 liquid\uAC00 \uD55C \uB808\uD3EC\uC5D0 \uC11E\uC5EC \uC788\uC2B5\uB2C8\uB2E4 \u2014 \uD3EC\uD138\uC774 \uBE4C\uB4DC\uD558\uC9C0 \uBABB\uD569\uB2C8\uB2E4. \uD558\uB098\uB9CC \uB0A8\uAE30\uC138\uC694."
-    );
+    if (wanted) {
+      fail(
+        ExitCode.PRECONDITION,
+        `--kind ${wanted}\uB85C \uC9C0\uC815\uD588\uC9C0\uB9CC \uC774 \uB808\uD3EC\uB294 mixed(sdk + liquid \uD63C\uD569)\uB85C \uD310\uC815\uB429\uB2C8\uB2E4 \u2014 \uC635\uC158\uC744 \uBE7C\uACE0 \uC2E4\uD589\uD558\uC138\uC694(\uB450 \uC138\uD2B8\uB97C \uBAA8\uB450 \uC124\uCE58\uD569\uB2C8\uB2E4).`
+      );
+    }
+    return "mixed";
   }
   if (detected === "unknown") {
     if (!wanted) {
@@ -1099,7 +1109,7 @@ async function aiDoctorCommand(o, deps = {}) {
 }
 
 // src/commands/build.ts
-import { resolve as resolve2, join as join6, relative as relative2 } from "path";
+import { resolve as resolve2, join as join6, relative as relative2, sep as sep3 } from "path";
 import { readFile as readFile2, access, readdir, rename, mkdir, rm } from "fs/promises";
 import { build as viteBuild, loadEnv } from "vite";
 import pc7 from "picocolors";
@@ -1523,13 +1533,6 @@ function findMisnamedTemplates(root) {
 function validateLiquid(root) {
   const detected = detectProjectKind(root);
   const issues = [];
-  if (detected.kind === "mixed") {
-    issues.push({
-      level: "error",
-      path: ".",
-      message: "sdk \uD15C\uD50C\uB9BF(src/pages\xB7src/slots\uC758 template.tsx)\uACFC liquid \uD15C\uD50C\uB9BF\uC774 \uD55C \uB808\uD3EC\uC5D0 \uC11E\uC5EC \uC788\uC2B5\uB2C8\uB2E4 \u2014 \uD3EC\uD138 \uBE4C\uB354\uB294 \uB458\uC744 \uD568\uAED8 \uD328\uD0A4\uC9D5\uD558\uC9C0 \uBABB\uD569\uB2C8\uB2E4. \uD558\uB098\uB9CC \uB0A8\uACA8 \uC8FC\uC138\uC694."
-    });
-  }
   if (detected.liquidTemplates.length === 0) {
     issues.push({
       level: "error",
@@ -1746,8 +1749,9 @@ ${pc7.red("Error")} ${label}: name "${elementName}"\uC744 ${elementNameOwner}\uA
   const finalDir = outputName ? join6(cwd, DIST_DIR, outputName) : join6(cwd, DIST_DIR);
   await mkdir(finalDir, { recursive: true });
   await rename(join6(cwd, outDir, "template.js"), join6(finalDir, "template.js"));
-  console.log(`  ${relative2(cwd, finalDir)}/template.js  (${formatSize(bundleSize)})`);
-  return { usesClient };
+  const output = relative2(cwd, finalDir).split(sep3).join("/");
+  console.log(`  ${output}/template.js  (${formatSize(bundleSize)})`);
+  return { usesClient, output };
 }
 function printCredentialReport(env2, referenced) {
   const issues = checkCredentials(env2, referenced);
@@ -1813,19 +1817,101 @@ function printLiquidIssues(issues) {
     console.log(pc7.green("\u2713 liquid \uAC80\uC99D \uD1B5\uACFC"));
   }
 }
+async function bundleAll(cwd, entries, bundleEntry) {
+  await rm(join6(cwd, DIST_DIR), { recursive: true, force: true });
+  const ctx = {
+    cwd,
+    takenOutputs: /* @__PURE__ */ new Map(),
+    takenElementNames: /* @__PURE__ */ new Map()
+  };
+  console.log(
+    `Found ${entries.length} template${entries.length > 1 ? "s" : ""}: ${entries.map(entryLabel).join(", ")}`
+  );
+  const results = [];
+  for (const entry of entries) {
+    results.push(await bundleEntry(ctx, entry));
+  }
+  await rm(join6(cwd, DIST_DIR, STAGING_DIR), { recursive: true, force: true });
+  return results;
+}
+async function reportCredentials(cwd, results) {
+  if (!results.some((r) => r.usesClient)) return;
+  const referenced = collectReferencedVars(await readProjectSources(cwd));
+  printCredentialReport(loadEnv("production", cwd, "VITE_"), referenced);
+}
+function collisionIssues(report2) {
+  return collidingSdkPages(report2).map((t) => ({
+    level: "error",
+    path: `src/${t}`,
+    message: `\uC0B0\uCD9C\uBB3C\uC774 ${DIST_DIR}/${t.slice("pages/".length)}/ \uB85C \uB098\uAC00 liquid \uD15C\uD50C\uB9BF \uC790\uB9AC(${DIST_DIR}/{user|admin}/{\uC774\uB984}/)\uC640 \uACB9\uCE69\uB2C8\uB2E4 \u2014 ${PAGES_ROOT}/ \uBC14\uB85C \uC544\uB798 \uD3F4\uB354 \uC774\uB984\uC5D0 user\xB7admin \uC744 \uC4F8 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4. \uD3F4\uB354 \uC774\uB984\uC744 \uBC14\uAFD4 \uC8FC\uC138\uC694.`
+  }));
+}
+async function withStdoutQuiet(fn) {
+  const { log: log3, info } = console;
+  console.log = (...args) => console.error(...args);
+  console.info = (...args) => console.error(...args);
+  try {
+    return await fn();
+  } finally {
+    console.log = log3;
+    console.info = info;
+  }
+}
+async function buildMixed(cwd, options, report2, bundleEntry) {
+  const issues = [...validateLiquid(cwd), ...collisionIssues(report2)];
+  const hasError = issues.some((i) => i.level === "error");
+  const liquid = { templates: report2.liquidTemplates };
+  if (options.json) {
+    if (hasError) {
+      printJson({ kind: "mixed", issues, liquid });
+      process.exitCode = ExitCode.PRECONDITION;
+      return;
+    }
+    const entries2 = await discoverEntries(cwd);
+    const results2 = await withStdoutQuiet(() => bundleAll(cwd, entries2, bundleEntry));
+    printJson({
+      kind: "mixed",
+      issues,
+      sdk: { templates: entries2.map(entryLabel), outputs: results2.map((r) => r.output) },
+      liquid
+    });
+    return;
+  }
+  printLiquidIssues(issues);
+  if (hasError) {
+    console.error(
+      `
+${pc7.red("\u2717")} \uAC80\uC99D \uC2E4\uD328 \u2014 \uC704 \uD56D\uBAA9\uC744 \uACE0\uCE5C \uB4A4 \uB2E4\uC2DC \uC2E4\uD589\uD558\uC138\uC694. \uC774\uB300\uB85C push\uD558\uBA74 \uD3EC\uD138 \uBE4C\uB4DC\uB3C4 \uAC19\uC740 \uC790\uB9AC\uC5D0\uC11C \uB9C9\uD799\uB2C8\uB2E4.`
+    );
+    process.exit(ExitCode.PRECONDITION);
+  }
+  const entries = await discoverEntries(cwd);
+  const results = await bundleAll(cwd, entries, bundleEntry);
+  console.log(`
+Build complete.`);
+  console.log(
+    `liquid \uD15C\uD50C\uB9BF ${report2.liquidTemplates.length}\uAC1C(${report2.liquidTemplates.join(", ")})\uB294 \uB85C\uCEEC \uC0B0\uCD9C\uBB3C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4 \u2014 \uD3EC\uD138\uC774 push\uB41C \uCEE4\uBC0B\uC758 public/{user|admin}/{name}/ \uC744 \uADF8\uB300\uB85C \uD328\uD0A4\uC9D5\uD569\uB2C8\uB2E4(data.json\xB7layout.json \uC81C\uC678)`
+  );
+  await reportCredentials(cwd, results);
+}
 async function buildCommand(options = {}, deps = {}) {
   const cwd = deps.cwd ?? process.cwd();
+  const bundleEntry = deps.bundleEntry ?? buildEntry;
   const report2 = detectProjectKind(cwd);
   const kind = report2.kind;
-  if (kind === "liquid" || kind === "mixed") {
+  if (kind === "liquid") {
     reportLiquid(cwd, options);
     return;
   }
+  if (kind === "mixed") {
+    await buildMixed(cwd, options, report2, bundleEntry);
+    return;
+  }
   const entries = await discoverEntries(cwd);
   if (entries.length === 0) {
-    const ignored = ignoredLiquidNotice(report2.ignoredLiquid);
-    if (ignored !== null) {
-      console.error(`Error: ${ignored}`);
+    const ignored2 = ignoredLiquidNotice(report2.ignoredLiquid);
+    if (ignored2 !== null) {
+      console.error(`Error: ${ignored2}`);
       await printLegacyHint(cwd);
       process.exit(ExitCode.PRECONDITION);
     }
@@ -1835,26 +1921,13 @@ async function buildCommand(options = {}, deps = {}) {
     await printLegacyHint(cwd);
     process.exit(ExitCode.PRECONDITION);
   }
-  await rm(join6(cwd, DIST_DIR), { recursive: true, force: true });
-  const ctx = {
-    cwd,
-    takenOutputs: /* @__PURE__ */ new Map(),
-    takenElementNames: /* @__PURE__ */ new Map()
-  };
-  console.log(
-    `Found ${entries.length} template${entries.length > 1 ? "s" : ""}: ${entries.map(entryLabel).join(", ")}`
-  );
-  const results = [];
-  for (const entry of entries) {
-    results.push(await buildEntry(ctx, entry));
-  }
-  await rm(join6(cwd, DIST_DIR, STAGING_DIR), { recursive: true, force: true });
+  const ignored = ignoredLiquidNotice(report2.ignoredLiquid);
+  if (ignored !== null) console.log(`${pc7.yellow("\u26A0")} ${ignored}
+`);
+  const results = await bundleAll(cwd, entries, bundleEntry);
   console.log(`
 Build complete.`);
-  if (results.some((r) => r.usesClient)) {
-    const referenced = collectReferencedVars(await readProjectSources(cwd));
-    printCredentialReport(loadEnv("production", cwd, "VITE_"), referenced);
-  }
+  await reportCredentials(cwd, results);
 }
 function formatSize(bytes) {
   if (bytes < 1024) return `${bytes} B`;
@@ -2511,13 +2584,8 @@ async function deployCommand(options, deps = {}) {
     fail(ExitCode.PRECONDITION, "--json \uC740 --yes \uC640 \uD568\uAED8 \uC4F0\uC138\uC694.");
   }
   if (!options.yes) assertCanConfirm(deps);
-  const kind = detectProjectKind(deps.cwd ?? process.cwd()).kind;
-  if (kind === "mixed") {
-    fail(
-      ExitCode.PRECONDITION,
-      "sdk \uD15C\uD50C\uB9BF\uACFC liquid \uD15C\uD50C\uB9BF\uC774 \uD55C \uB808\uD3EC\uC5D0 \uC11E\uC5EC \uC788\uC2B5\uB2C8\uB2E4 \u2014 \uD3EC\uD138 \uBE4C\uB354\uAC00 \uD328\uD0A4\uC9D5\uD558\uC9C0 \uBABB\uD569\uB2C8\uB2E4. bstage build \uB85C \uC5B4\uB290 \uD30C\uC77C\uC774 \uAC78\uB9AC\uB294\uC9C0 \uD655\uC778\uD55C \uB4A4 \uD558\uB098\uB9CC \uB0A8\uACA8 \uC8FC\uC138\uC694."
-    );
-  }
+  const report2 = detectProjectKind(deps.cwd ?? process.cwd());
+  const kind = report2.kind;
   const out = deps.out ?? console.log;
   const ctx = await resolveContext({ cwd: deps.cwd, env: deps.env, fetch: deps.fetch });
   const defaultBranch = await repoDefaultBranch(ctx);
@@ -2525,13 +2593,20 @@ async function deployCommand(options, deps = {}) {
   const targets = await fetchTargets(ctx, options.placement);
   if (kind === "liquid") {
     assertNoSlotPlacement(targets);
-    if (!options.json) {
-      out(
-        pc10.dim(
-          "[bstage] liquid \uB808\uD3EC \u2014 \uB85C\uCEEC \uBE4C\uB4DC \uC5C6\uC774 \uD3EC\uD138\uC774 push\uB41C \uCEE4\uBC0B\uC758 public/{user|admin}/ \uC744 \uADF8\uB300\uB85C \uD328\uD0A4\uC9D5\uD569\uB2C8\uB2E4."
-        )
-      );
-    }
+  }
+  if (!options.json && kind === "liquid") {
+    out(
+      pc10.dim(
+        "[bstage] liquid \uB808\uD3EC \u2014 \uB85C\uCEEC \uBE4C\uB4DC \uC5C6\uC774 \uD3EC\uD138\uC774 push\uB41C \uCEE4\uBC0B\uC758 public/{user|admin}/ \uC744 \uADF8\uB300\uB85C \uD328\uD0A4\uC9D5\uD569\uB2C8\uB2E4."
+      )
+    );
+  }
+  if (!options.json && kind === "mixed") {
+    out(
+      pc10.dim(
+        `[bstage] \uD63C\uD569 \uB808\uD3EC \u2014 sdk \uD15C\uD50C\uB9BF\uC740 \uD3EC\uD138\uC774 \uBE4C\uB4DC\uD558\uACE0, liquid \uD15C\uD50C\uB9BF ${report2.liquidTemplates.length}\uAC1C\uB294 push\uB41C \uCEE4\uBC0B\uC758 public/{user|admin}/ \uC744 \uADF8\uB300\uB85C \uD328\uD0A4\uC9D5\uD569\uB2C8\uB2E4.`
+      )
+    );
   }
   const created = await createAndAnnounceBuild(ctx, options);
   if (options.noWait) {
@@ -2555,7 +2630,7 @@ import pc11 from "picocolors";
 import { existsSync as existsSync5, realpathSync as realpathSync2, statSync, watch } from "fs";
 import { readFile as readFile5 } from "fs/promises";
 import { createServer } from "http";
-import { join as join9, relative as relative3, sep as sep3 } from "path";
+import { join as join9, relative as relative3, sep as sep4 } from "path";
 
 // src/liquid/routes.ts
 var RELOAD_PATH = "/__bstage__/reload";
@@ -2788,7 +2863,7 @@ function isInside(publicDir, full) {
   try {
     const base = realpathSync2(publicDir);
     const real = realpathSync2(full);
-    return real === base || real.startsWith(base + sep3);
+    return real === base || real.startsWith(base + sep4);
   } catch {
     return false;
   }
@@ -2961,6 +3036,27 @@ async function startLiquidDevServer(options) {
 }
 
 // src/commands/dev.ts
+function resolveDevMode(kind, requested) {
+  if (requested !== void 0 && requested !== "sdk" && requested !== "liquid") {
+    fail(ExitCode.PRECONDITION, `--kind \uAC12\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4: ${requested} (sdk \uB610\uB294 liquid)`);
+  }
+  const detected = kind === "liquid" ? "liquid" : "sdk";
+  if (kind === "mixed") {
+    if (requested === "liquid") return { mode: "liquid" };
+    if (requested === "sdk") return { mode: "sdk" };
+    return {
+      mode: "sdk",
+      hint: "sdk\uC640 liquid \uD15C\uD50C\uB9BF\uC774 \uD568\uAED8 \uC788\uB294 \uB808\uD3EC\uC785\uB2C8\uB2E4 \u2014 \uC9C0\uAE08\uC740 sdk(Vite) \uD504\uB9AC\uBDF0\uB97C \uB744\uC6C1\uB2C8\uB2E4. liquid \uD504\uB9AC\uBDF0\uB294 `bstage dev --kind liquid` \uB85C \uB530\uB85C \uB744\uC6B0\uC138\uC694."
+    };
+  }
+  if (requested !== void 0 && requested !== detected) {
+    fail(
+      ExitCode.PRECONDITION,
+      `--kind ${requested}\uB85C \uC9C0\uC815\uD588\uC9C0\uB9CC \uC774 \uB808\uD3EC\uB294 ${kind}\uB85C \uD310\uC815\uB429\uB2C8\uB2E4 \u2014 \uC635\uC158\uC744 \uBE7C\uACE0 \uB2E4\uC2DC \uC2E4\uD589\uD558\uC138\uC694.`
+    );
+  }
+  return { mode: detected };
+}
 async function runLiquidPreview(root, port, phase) {
   if (phase !== void 0) {
     console.log("[bstage] liquid \uD504\uB9AC\uBDF0\uB294 phase\uB97C \uC4F0\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 --phase \uB97C \uBB34\uC2DC\uD569\uB2C8\uB2E4.");
@@ -2977,7 +3073,6 @@ async function runLiquidPreview(root, port, phase) {
   console.log(`  admin \uBAA9\uB85D:     ${base}/admin`);
   console.log("  phase\uC640 \uC778\uC99D \uD504\uB85D\uC2DC\uB294 liquid \uD504\uB9AC\uBDF0\uC5D0 \uC5C6\uC2B5\uB2C8\uB2E4. \uAC12\uC740 data.json\uC5D0\uC11C \uC635\uB2C8\uB2E4.\n");
 }
-var MIXED_MESSAGE = "liquid \uD15C\uD50C\uB9BF(public/{user|admin}/{\uC774\uB984}/template.liquid)\uACFC React \uD15C\uD50C\uB9BF(src/**/template.tsx)\uC774 \uD55C \uB808\uD3EC\uC5D0 \uC11E\uC5EC \uC788\uC2B5\uB2C8\uB2E4. \uD3EC\uD138 \uBE4C\uB354\uAC00 \uBE4C\uB4DC\uD558\uC9C0 \uBABB\uD558\uBBC0\uB85C \uD55C\uCABD\uC73C\uB85C \uC815\uB9AC\uD55C \uB4A4 \uB2E4\uC2DC \uC2E4\uD589\uD558\uC138\uC694.";
 async function runViteDevServer(root, port, phaseOption) {
   let resolved;
   try {
@@ -3020,12 +3115,13 @@ async function devCommand(options) {
   const port = parseInt(options.port, 10);
   const root = process.cwd();
   const report2 = detectProjectKind(root);
-  const kind = report2.kind;
+  const decision = resolveDevMode(report2.kind, options.kind);
   const ignored = ignoredLiquidNotice(report2.ignoredLiquid);
   if (ignored !== null) console.log(`[bstage] ${pc11.yellow("\uACBD\uACE0")}: ${ignored}
 `);
-  if (kind === "liquid") return await runLiquidPreview(root, port, options.phase);
-  if (kind === "mixed") fail(ExitCode.PRECONDITION, MIXED_MESSAGE);
+  if (decision.hint !== void 0) console.log(`[bstage] ${decision.hint}
+`);
+  if (decision.mode === "liquid") return await runLiquidPreview(root, port, options.phase);
   await runViteDevServer(root, port, options.phase);
 }
 
@@ -4525,11 +4621,15 @@ import { readFile as readFile8 } from "fs/promises";
 import { join as join14 } from "path";
 import {
   VERSION as TOOLKIT_VERSION,
+  AGENTS_MANAGED_VERSION,
   agentsMdStatus,
   compareVersions,
+  extractManagedBlock,
   parseAgentsIdentity as parseAgentsIdentity2,
+  readManagedVersion as readManagedVersion2,
   readSkillStamp as readSkillStamp2,
   renderManagedBlock,
+  sanitizeIdentity as sanitizeIdentity2,
   skillsFor as skillsFor4
 } from "@bstage-sdk/ai-toolkit";
 async function autoSyncSkills(root, report2) {
@@ -4555,10 +4655,10 @@ async function diagnoseSkills(root, kind) {
   );
 }
 function resolveSkillKind(detected) {
-  if (detected === "mixed") return null;
+  if (detected === "mixed") return "mixed";
   return detected === "liquid" ? "liquid" : "sdk";
 }
-async function diagnoseAgentsMd(root, pkgName) {
+async function diagnoseAgentsMd(root, pkgName, kind = "sdk") {
   let content;
   try {
     content = await readFile8(join14(root, "AGENTS.md"), "utf-8");
@@ -4566,12 +4666,18 @@ async function diagnoseAgentsMd(root, pkgName) {
     return { status: "missing", managedBlock: null };
   }
   const status = agentsMdStatus(content);
-  if (status === "ok") return { status, managedBlock: null };
   const parsed = parseAgentsIdentity2(content);
-  const projectName = parsed.projectName ?? pkgName ?? "custom-templates";
-  const space = parsed.space ?? projectName.split("-custom-templates-")[0] ?? projectName;
+  const projectName = sanitizeIdentity2(parsed.projectName) ?? sanitizeIdentity2(pkgName) ?? "custom-templates";
+  const space = sanitizeIdentity2(parsed.space) ?? projectName.split("-custom-templates-")[0] ?? projectName;
   const target = resolveProjectTarget(root);
-  return { status, managedBlock: renderManagedBlock({ space, projectName, target }) };
+  const block = renderManagedBlock({ space, projectName, target, kind });
+  if (status === "ok") {
+    if (extractManagedBlock(content) === block) return { status, managedBlock: null };
+    const fileVersion = readManagedVersion2(content);
+    const downgrade = fileVersion !== null && fileVersion > AGENTS_MANAGED_VERSION;
+    return downgrade ? { status: "stale", managedBlock: block, downgrade: true } : { status: "stale", managedBlock: block };
+  }
+  return { status, managedBlock: block };
 }
 
 // src/commands/doctor/report.ts
@@ -4646,7 +4752,8 @@ async function diagnose2(root) {
   const deps = pkg.deps;
   const kind = detectProjectKind(root).kind;
   const isLiquid = kind === "liquid";
-  const isBstageProject = isLiquid || SDK_PACKAGES2.some((p5) => p5 in deps);
+  const hasLiquid = isLiquid || kind === "mixed";
+  const isBstageProject = hasLiquid || SDK_PACKAGES2.some((p5) => p5 in deps);
   const installed = await collectInstalledVersions(root, deps);
   const { versions, latestChecked } = await diagnoseVersions(
     deps,
@@ -4667,11 +4774,11 @@ async function diagnose2(root) {
     scripts: diagnoseScripts(pkg.scripts, tables.scripts),
     recommendedDeps: diagnoseRecommendedDeps(deps, tables.deps),
     migrations: await readApplicableMigrations(migrationResolver(root, deps, installed)),
-    agentsMd: await diagnoseAgentsMd(root, pkg.name),
-    skills: skillKind === null ? [] : await diagnoseSkills(root, skillKind),
-    skillsSkipped: skillKind === null,
+    agentsMd: await diagnoseAgentsMd(root, pkg.name, skillKind),
+    skills: await diagnoseSkills(root, skillKind),
+    skillsSkipped: false,
     latestChecked,
-    liquid: isLiquid ? { issues: validateLiquid(root) } : null
+    liquid: hasLiquid ? { issues: validateLiquid(root) } : null
   };
 }
 async function readInstalledVersion(root, pkg) {
@@ -4862,6 +4969,14 @@ function printAgentsMd(r) {
       console.log(pc15.dim("  \xB7 \uD30C\uC77C \uC5C6\uC74C \u2014 bstage \uD504\uB85C\uC81D\uD2B8\uB77C\uBA74 init/\uB9C8\uC774\uADF8\uB808\uC774\uC158\uC73C\uB85C \uC0DD\uC131\uD558\uC138\uC694."));
       break;
     case "stale":
+      if (r.agentsMd.downgrade) {
+        console.log(
+          pc15.yellow("  ! \uAD00\uB9AC \uC601\uC5ED\uC774 \uC774 CLI\uBCF4\uB2E4 \uC0C8 \uBC84\uC804") + pc15.dim(
+            " \u2014 \uC774 CLI\uAC00 \uC624\uB798\uB3FC \uAC31\uC2E0\uD558\uBA74 \uC61B \uBCF8\uBB38\uC73C\uB85C \uB418\uB3CC\uC544\uAC11\uB2C8\uB2E4(\uD558\uD5A5). \uCD5C\uC2E0 CLI(npx @bstage-sdk/cli@latest)\uB85C \uB2E4\uC2DC \uC2E4\uD589\uD558\uC138\uC694."
+          )
+        );
+        break;
+      }
       console.log(
         pc15.yellow("  \u2192 \uAD00\uB9AC \uC601\uC5ED\uC774 \uC624\uB798\uB428") + pc15.dim(" \u2014 `bstage ai update`\uB85C \uAC31\uC2E0(\uC790\uC720 \uC601\uC5ED\uC740 \uBCF4\uC874).")
       );
@@ -4943,8 +5058,8 @@ function printReport(r) {
   }
   printVersions(r);
   printFiles(r);
-  if (r.liquid === null) printLayout(r);
-  else printLiquid(r);
+  if (r.kind !== "liquid") printLayout(r);
+  if (r.liquid !== null) printLiquid(r);
   printPnpmWorkspace(r);
   printScripts(r);
   printRecommendedDeps(r);
@@ -5882,8 +5997,8 @@ function readVersion() {
 var program = new Command().name("bstage").description("b.stage \uC11C\uB4DC\uD30C\uD2F0 \uD15C\uD50C\uB9BF SDK CLI \u2014 \uD15C\uD50C\uB9BF \uAC1C\uBC1C\xB7\uBE4C\uB4DC\xB7\uB85C\uCEEC \uC11C\uBC84\xB7\uB9C8\uC774\uADF8\uB808\uC774\uC158").version(readVersion(), "-v, --version", "\uBC84\uC804 \uCD9C\uB825");
 program.command("init").description("\uC0C8 bstage \uD15C\uD50C\uB9BF \uD504\uB85C\uC81D\uD2B8 \uC0DD\uC131").option("-y, --yes", "\uAE30\uBCF8\uAC12\uC73C\uB85C \uBE44\uC778\uD130\uB799\uD2F0\uBE0C \uC2E4\uD589").option("--space <space>", "Space \uC774\uB984").option("--target <target>", "\uC2A4\uCE90\uD3F4\uB4DC \uB300\uC0C1 (user, admin)", "user").option("--kind <kind>", "\uD504\uB85C\uC81D\uD2B8 \uC885\uB958 (sdk: React \uCEF4\uD3EC\uB10C\uD2B8, liquid: liquid \uD15C\uD50C\uB9BF)", "sdk").option("--template <template>", "\uCCAB \uBC88\uC9F8 \uD15C\uD50C\uB9BF \uC774\uB984 (\uAE30\uBCF8: sdk {space}-hello, liquid hello)").option("--phase <phase>", "\uBC30\uD3EC \uD658\uACBD (dev, qa, real, sandbox)", "sandbox").option("--pm <pm>", "\uD328\uD0A4\uC9C0 \uB9E4\uB2C8\uC800 (npm, pnpm)", "npm").action(initCommand);
 program.command("build").description(
-  "\uD15C\uD50C\uB9BF\uC744 IIFE \uBC88\uB4E4\uB85C \uBE4C\uB4DC (\uD398\uC774\uC9C0\uB294 \uACBD\uB85C\uBCC4, \uC704\uC82F\uC740 \uC2AC\uB86F\uBCC4 \uB514\uB809\uD1A0\uB9AC) \u2014 liquid \uB808\uD3EC\uB294 \uAC80\uC99D\uB9CC"
-).option("--json", "\uAC80\uC99D \uACB0\uACFC\uB97C JSON\uC73C\uB85C \uCD9C\uB825 (liquid \uB808\uD3EC \uC804\uC6A9)").action((options) => buildCommand(options));
+  "\uD15C\uD50C\uB9BF\uC744 IIFE \uBC88\uB4E4\uB85C \uBE4C\uB4DC (\uD398\uC774\uC9C0\uB294 \uACBD\uB85C\uBCC4, \uC704\uC82F\uC740 \uC2AC\uB86F\uBCC4 \uB514\uB809\uD1A0\uB9AC) \u2014 liquid \uB808\uD3EC\uB294 \uAC80\uC99D\uB9CC, \uD63C\uD569 \uB808\uD3EC\uB294 sdk \uBC88\uB4E4 + liquid \uAC80\uC99D"
+).option("--json", "\uAC80\uC99D \uACB0\uACFC\xB7\uC0B0\uCD9C\uBB3C \uC694\uC57D\uC744 JSON\uC73C\uB85C \uCD9C\uB825 (liquid\xB7\uD63C\uD569 \uB808\uD3EC)").action((options) => buildCommand(options));
 program.command("docs").description("\uC124\uCE58\uB41C SDK \uBB38\uC11C \uBAA9\uB85D\xB7\uACBD\uB85C \uCD9C\uB825").action(docsCommand);
 program.command("doctor").description(
   "SDK \uBC84\uC804\xB7\uBCF4\uC77C\uB7EC\uD50C\uB808\uC774\uD2B8 \uB4DC\uB9AC\uD504\uD2B8 \uC9C4\uB2E8 (\uC9C4\uB2E8 + SDK \uC18C\uC720 \uC2A4\uD0AC \uC790\uB3D9 \uB3D9\uAE30\uD654; package.json\xB7\uD6C5\uC740 \uAC74\uB4DC\uB9AC\uC9C0 \uC54A\uC74C)"
@@ -5891,6 +6006,9 @@ program.command("doctor").description(
 program.command("dev").description("\uC778\uC99D \uD504\uB85D\uC2DC \uD3EC\uD568 \uB85C\uCEEC \uAC1C\uBC1C \uC11C\uBC84 (liquid \uB808\uD3EC\uB294 liquidjs \uD504\uB9AC\uBDF0)").option("-p, --port <port>", "Dev server port", "5173").option(
   "--phase <phase>",
   "Target phase (dev, qa, real, sandbox). \uC0DD\uB7B5 \uC2DC .env\uC758 VITE_BSTAGE_PHASE, \uADF8\uAC83\uB3C4 \uC5C6\uC73C\uBA74 sandbox"
+).option(
+  "--kind <kind>",
+  "\uD63C\uD569 \uB808\uD3EC(sdk + liquid)\uC5D0\uC11C \uB744\uC6B8 \uD504\uB9AC\uBDF0 (sdk: Vite \uAE30\uBCF8, liquid: liquidjs)"
 ).action((o) => runCommand(() => devCommand(o)));
 var ai = program.command("ai").description("\uC5D0\uC774\uC804\uD2B8\uC6A9 \uC2A4\uD0AC\xB7AGENTS.md \uC124\uCE58\xB7\uB3D9\uAE30\uD654\xB7\uC9C4\uB2E8");
 ai.command("install").description("\uC2A4\uD0AC(.claude/skills)\xB7AGENTS.md\xB7CLAUDE.md \uC124\uCE58 \uBC0F \uCD5C\uC2E0\uD654 + pre-commit \uC2DC\uD06C\uB9BF \uAC00\uB4DC").option("--dir <dir>", "\uC2A4\uD0AC \uB514\uB809\uD130\uB9AC", ".claude/skills").option("--kind <kind>", "\uD504\uB85C\uC81D\uD2B8 \uC885\uB958(sdk|liquid) \u2014 \uC790\uB3D9 \uD310\uC815\uC774 \uC548 \uB420 \uB54C").action((o) => runCommand(() => aiInstallCommand(o)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bstage-sdk/cli",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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.5.0",
-    "@bstage-sdk/core": "0.5.0"
+    "@bstage-sdk/ai-toolkit": "0.6.1",
+    "@bstage-sdk/core": "0.6.1"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
-    "@bstage-sdk/design": "0.5.0"
+    "@bstage-sdk/design": "0.6.1"
   },
   "license": "MIT",
   "scripts": {