@bstage-sdk/cli 0.2.0 → 0.3.0

package/dist/MIGRATION.md

@@ -45,6 +45,35 @@
 
 > **`적용` 단계는 옛 프로젝트에서 실제로 따라가 본 뒤 적는다.** 새 `bstage init` 프로젝트에서 되는 것과, 기존 프로젝트가 이 절차만 보고 도달하는 것은 다르다. 따라 했을 때 깨지는 선행 조건이 있으면 **그 조건까지 적는다** — `core 0.44.0` 항목이 그 사례다(스크립트만 넣으면 `@types/node` 부재로 `TS2688`이 난다. 스캐폴드 템플릿을 고쳐 새 프로젝트는 해결됐지만, 먼저 써둔 적용 절차를 되짚지 않아 기존 프로젝트용 지침이 깨진 채 남았다).
 
-> **헤더 규칙**: `
+> **헤더 규칙**: `## → {패키지} {버전}` 형식으로, 그 변경을 실제로 낸 패키지와 버전을 명시한다(예: `→ cli 0.3.0`, `→ core 0.3.0`). 한 변경이 여러 패키지를 함께 범프시켰으면 소비자가 올려야 할 패키지를 `·`로 나열한다(예: `→ core 0.3.0 · cli 0.3.0`). 소비자는 이 헤더의 패키지를 해당 버전 **이상**으로 올려야 한다. 단순 의존성 재핀(dependency bump)만 된 패키지는 헤더에 적지 않는다.
+>
+> **정렬**: 릴리즈 **시점 최신이 위**. 패키지가 독립 버전이라 헤더 숫자만으로는 시간순 정렬이 되지 않으므로 릴리즈 순서를 기준으로 한다.
 
-아직 항목이 없다. 소비자에게 영향이 있는 변경을 릴리즈할 때 여기에 추가한다.
+---
+## → core 0.3.0 · cli 0.3.0
+
+### 앱 키 이름 정리(`appSecret` → `appKey`, `VITE_BSTAGE_APP_SECRET` → `VITE_BSTAGE_APP_KEY`) — `판단` · `선택`
+
+**영향**
+
+- **기존 프로젝트가 반드시 할 일은 없다.** `appSecret`·`VITE_BSTAGE_APP_SECRET`은 deprecated 별칭으로 그대로 동작한다. 별칭은 **0.4.0**에서 제거되므로 그 전에 옮긴다.
+- 감지: `src/shared/client.ts`에 `appSecret:`이 있거나, `.env`·`.env.example`에 `VITE_BSTAGE_APP_SECRET`이 있는 경우.
+
+**변경 내용**
+
+- 같은 값을 포털 화면(APP KEY)·포털 API(`appKey`)·게이트웨이 헤더(`X-BSTAGE-APP-KEY`)는 모두 KEY라고 부르는데 SDK만 `secret`이라고 불렀다. 이 값은 `VITE_` 환경변수라 **빌드 결과물에 평문으로 실려 브라우저에서 보이는 값**이고 비밀값이 아니다 — 이름이 사실과 반대여서 "숨겨야 하는 값"으로 오해하게 했다. SDK 이름을 나머지와 맞췄다.
+- `BstageConfig.appKey`가 정본이고 `appSecret`은 deprecated 별칭이다(둘 다 주면 `appKey` 우선). 타입 주석도 "앱 시크릿"에서 "앱 키(APP KEY) — 브라우저에 노출되는 값"으로 바꿨다.
+- 새 `bstage init` 스캐폴드는 `.env`·`.env.example`·`client.ts`·`vite-env.d.ts`에 새 이름을 쓴다.
+- **소스와 `.env`가 다른 이름을 써도 빌드가 이어 붙인다.** `bstage build`(프리셋)와 `bstageDevPlugin`이 `VITE_BSTAGE_APP_KEY`·`VITE_BSTAGE_APP_SECRET` 중 한쪽만 있으면 다른 이름으로도 같은 값이 읽히게 `define`한다. 그래서 옛 `client.ts`(`appSecret: import.meta.env.VITE_BSTAGE_APP_SECRET`)를 둔 채 `.env`만 새 이름으로 바꿔도, 포털의 환경변수 입력이 새 이름으로 들어와도 번들에 값이 실린다. 둘 다 있으면 각자 실제 값이 그대로 쓰인다.
+- `bstage build`의 인증 값 점검도 같은 순서로 본다 — 소스가 읽는 이름의 값이 우선, 다른 이름은 폴백. 보고에는 소스가 실제로 읽는 이름을 쓴다.
+- 앱 키가 아예 없으면 `X-BSTAGE-APP-KEY` 헤더에 `"undefined"` 문자열을 실던 것을 헤더 생략 + 생성 시 콘솔 경고로 바꿨다. 게이트웨이 응답(401)은 같다.
+
+**적용**
+
+1. (자동) `@bstage-sdk/core`·`@bstage-sdk/cli`를 `0.3.0` 이상으로 올린다.
+2. (판단) `src/shared/client.ts`의 `appSecret: import.meta.env.VITE_BSTAGE_APP_SECRET`을 `appKey: import.meta.env.VITE_BSTAGE_APP_KEY`로 바꾼다. 리터럴 키를 박아 둔 옛 프로젝트는 키 이름만 `appSecret` → `appKey`로 바꾼다.
+3. (판단) `.env`·`.env.example`의 `VITE_BSTAGE_APP_SECRET=`을 `VITE_BSTAGE_APP_KEY=`로 바꾼다. 값은 그대로다 — 재발급이 아니다.
+4. (판단) `src/vite-env.d.ts`의 `readonly VITE_BSTAGE_APP_SECRET: string`을 `readonly VITE_BSTAGE_APP_KEY: string`으로 바꾼다.
+5. CI·배포 환경에 `VITE_BSTAGE_APP_SECRET`을 주입하고 있었다면 같은 값을 `VITE_BSTAGE_APP_KEY`로 주입한다. 2~4를 한 번에 못 옮기는 기간에는 위 별칭 덕에 어느 한쪽 이름만 있어도 빌드가 통과한다.
+
+---

package/dist/{chunk-FER3TEK7.js → chunk-COUDGZIA.js}

@@ -2,14 +2,14 @@
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 
-// src/dev/devVitePlugin.ts
-import { createRequire } from "module";
-import { readFileSync as readFileSync2 } from "fs";
-import { join, dirname } from "path";
+// src/vite/appKeyEnvAlias.ts
+import { loadEnv } from "vite";
 
 // src/constants.ts
 import { readFileSync } from "fs";
 import { resolve } from "path";
+var APP_KEY_VAR = "VITE_BSTAGE_APP_KEY";
+var LEGACY_APP_KEY_VAR = "VITE_BSTAGE_APP_SECRET";
 var BSTAGE_INTERNAL_PREFIX = "/__bstage__";
 var LOGIN_PATH = `${BSTAGE_INTERNAL_PREFIX}/login`;
 var PROXY_PATH_PREFIX = "/__proxy__";
@@ -88,6 +88,31 @@ function resolveProjectTarget(root) {
   return pkg.bstage?.target === "admin" ? "admin" : "user";
 }
 
+// src/vite/appKeyEnvAlias.ts
+function appKeyEnvDefine(env) {
+  const key = env[APP_KEY_VAR]?.trim();
+  const legacy = env[LEGACY_APP_KEY_VAR]?.trim();
+  if (key && !legacy) return { [`import.meta.env.${LEGACY_APP_KEY_VAR}`]: JSON.stringify(key) };
+  if (legacy && !key) return { [`import.meta.env.${APP_KEY_VAR}`]: JSON.stringify(legacy) };
+  return {};
+}
+function loadProjectEnv(config, mode) {
+  return loadEnv(mode, config.envDir ?? config.root ?? process.cwd(), "VITE_");
+}
+function appKeyEnvAliasPlugin() {
+  return {
+    name: "bstage-app-key-env-alias",
+    config(config, { mode }) {
+      return { define: appKeyEnvDefine(loadProjectEnv(config, mode)) };
+    }
+  };
+}
+
+// src/dev/devVitePlugin.ts
+import { createRequire } from "module";
+import { readFileSync as readFileSync2 } from "fs";
+import { join, dirname } from "path";
+
 // src/dev/loginPage.ts
 function getLoginPageHtml(phase, mode = "user") {
   const tokenPath = AUTH_TOKEN_PATH_BY_MODE[mode].replace(/^\/svc/, AUTH_PATH_PREFIX);
@@ -415,14 +440,14 @@ function getLoginPageHtml(phase, mode = "user") {
 // src/dev/proxyUtils.ts
 import { request as httpsRequest } from "https";
 import { gunzipSync, brotliDecompressSync, inflateSync } from "zlib";
-import { loadEnv } from "vite";
+import { loadEnv as loadEnv2 } from "vite";
 var CF_ACCESS_ENV_KEYS = ["VITE_CF_ACCESS_CLIENT_ID", "VITE_CF_ACCESS_CLIENT_SECRET"];
 var cachedCreds;
 var missingWarned = false;
 function resolveCfAccessCreds() {
   if (cachedCreds !== void 0) return cachedCreds;
   const [idKey, secretKey] = CF_ACCESS_ENV_KEYS;
-  const fileEnv = loadEnv("development", process.cwd(), "");
+  const fileEnv = loadEnv2("development", process.cwd(), "");
   const id = process.env[idKey] || fileEnv[idKey] || "";
   const secret = process.env[secretKey] || fileEnv[secretKey] || "";
   cachedCreds = id && secret ? { id, secret } : null;
@@ -542,7 +567,7 @@ function collectBody(req, maxBytes = MAX_REQUEST_BODY_BYTES) {
 }
 
 // src/dev/resolveHosts.ts
-import { loadEnv as loadEnv2 } from "vite";
+import { loadEnv as loadEnv3 } from "vite";
 var HOST_ENV_KEYS = {
   gateway: "VITE_BSTAGE_GATEWAY_HOST",
   auth: "VITE_BSTAGE_AUTH_HOST",
@@ -559,7 +584,7 @@ function resolveDevHosts(phase, mode, cwd = process.cwd()) {
       auth: (tenantId) => getAuthHost(mode, phase, tenantId)
     };
   }
-  const fileEnv = loadEnv2("development", cwd, "");
+  const fileEnv = loadEnv3("development", cwd, "");
   const read = (key) => (process.env[key] || fileEnv[key] || "").trim();
   const authKey = authKeyFor(mode);
   const gatewayHost = read(HOST_ENV_KEYS.gateway);
@@ -582,7 +607,7 @@ function resolveDevHosts(phase, mode, cwd = process.cwd()) {
 }
 
 // src/dev/resolvePhase.ts
-import { loadEnv as loadEnv3 } from "vite";
+import { loadEnv as loadEnv4 } from "vite";
 var PHASES = ["dev", "qa", "real", "sandbox"];
 var DEFAULT_PHASE = "sandbox";
 function isPhase(value) {
@@ -597,7 +622,7 @@ function resolvePhase(explicit, cwd = process.cwd(), env = process.env) {
     }
     return { phase: explicit, source: "flag" };
   }
-  const fileEnv = loadEnv3("development", cwd, "");
+  const fileEnv = loadEnv4("development", cwd, "");
   const fromEnv = env.VITE_BSTAGE_PHASE || fileEnv.VITE_BSTAGE_PHASE || "";
   if (fromEnv) {
     if (isPhase(fromEnv)) return { phase: fromEnv, source: "env" };
@@ -1949,10 +1974,13 @@ function bstageDevPlugin(options = {}) {
   return {
     name: "bstage-dev",
     enforce: "pre",
-    config() {
+    config(config, { mode: mode2 }) {
       const root = process.cwd();
       projectRequire = createRequire(join(root, "package.json"));
       return {
+        // 앱 키 env 별칭 — 소비자 `vite.config.ts`는 이 플러그인만 얹으므로 여기서도 이어 붙인다
+        // (`bstage build`는 프리셋이 맡는다). 상세는 appKeyEnvAlias.ts.
+        define: appKeyEnvDefine(loadProjectEnv(config, mode2)),
         optimizeDeps: {
           exclude: ["@bstage-sdk/core", "@bstage-sdk/react"]
         },
@@ -2064,7 +2092,7 @@ function bstageDevPlugin(options = {}) {
 // src/vite/preset.ts
 function createViteConfig(options = {}) {
   return defineConfig({
-    plugins: [react()],
+    plugins: [react(), appKeyEnvAliasPlugin()],
     define: {
       "process.env.NODE_ENV": JSON.stringify("production")
     },
@@ -2091,6 +2119,8 @@ function createViteConfig(options = {}) {
 }
 
 export {
+  APP_KEY_VAR,
+  LEGACY_APP_KEY_VAR,
   LOGIN_PATH,
   isPublicPhase,
   TRANSLATION_LANGUAGES,
@@ -2101,6 +2131,8 @@ export {
   PORTAL_HOSTS,
   PORTAL_HOST_ENV_KEY,
   resolveProjectTarget,
+  appKeyEnvDefine,
+  appKeyEnvAliasPlugin,
   resolvePhase,
   describePhase,
   bstageDevPlugin,

package/dist/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import {
+  APP_KEY_VAR,
   DEFAULT_TRANSLATION_TIER,
+  LEGACY_APP_KEY_VAR,
   LOGIN_PATH,
   PORTAL_HOSTS,
   PORTAL_HOST_ENV_KEY,
@@ -14,7 +16,7 @@ import {
   isPublicPhase,
   resolvePhase,
   resolveProjectTarget
-} from "./chunk-FER3TEK7.js";
+} from "./chunk-COUDGZIA.js";
 
 // src/index.ts
 import { readFileSync as readFileSync2 } from "fs";
@@ -157,10 +159,11 @@ __reg__.forEach(__registerTemplate__);
 // src/build/credentialCheck.ts
 var CLIENT_MARKER = "X-BSTAGE-APP-ID";
 var APP_ID_PREFIX = "bsa_";
-var APP_SECRET_PREFIX = "bsp_";
+var APP_KEY_PREFIX = "bsp_";
 var CREDENTIAL_ENV_VARS = [
   "VITE_BSTAGE_APP_ID",
-  "VITE_BSTAGE_APP_SECRET",
+  APP_KEY_VAR,
+  LEGACY_APP_KEY_VAR,
   "VITE_BSTAGE_TENANT_ID"
 ];
 function usesBstageClient(bundle) {
@@ -180,54 +183,77 @@ function collectReferencedVars(sources) {
   return referenced;
 }
 function checkCredentials(env2, referenced) {
-  const issues = [];
-  for (const varName of CREDENTIAL_ENV_VARS) {
-    if (!referenced.has(varName)) continue;
-    const value = env2[varName]?.trim();
+  const appId = referenced.has("VITE_BSTAGE_APP_ID") ? env2.VITE_BSTAGE_APP_ID?.trim() : void 0;
+  const appKeys = resolveAppKeys(env2, referenced);
+  const targets = [
+    ...referenced.has("VITE_BSTAGE_APP_ID") ? [{ varName: "VITE_BSTAGE_APP_ID", value: appId }] : [],
+    ...appKeys,
+    ...referenced.has("VITE_BSTAGE_TENANT_ID") ? [{ varName: "VITE_BSTAGE_TENANT_ID", value: env2.VITE_BSTAGE_TENANT_ID?.trim() }] : []
+  ];
+  const presenceIssues = targets.flatMap(({ varName, value }) => {
     if (!value) {
-      issues.push({
-        level: "error",
-        varName,
-        message: "\uAC12\uC774 \uC5C6\uC2B5\uB2C8\uB2E4 \u2014 \uBC88\uB4E4\uC5D0 undefined\uAC00 \uBC15\uD600 \uBC30\uD3EC \uD6C4 401\uC774 \uB0A9\uB2C8\uB2E4."
-      });
-      continue;
+      return [
+        {
+          level: "error",
+          varName,
+          message: "\uAC12\uC774 \uC5C6\uC2B5\uB2C8\uB2E4 \u2014 \uBC88\uB4E4\uC5D0 undefined\uAC00 \uBC15\uD600 \uBC30\uD3EC \uD6C4 401\uC774 \uB0A9\uB2C8\uB2E4."
+        }
+      ];
     }
     if (isPlaceholderValue(value)) {
-      issues.push({
-        level: "error",
-        varName,
-        message: "\uC790\uB9AC\uD45C\uC2DC\uC790\uAC00 \uADF8\uB300\uB85C\uC785\uB2C8\uB2E4 \u2014 \uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09\uBC1B\uC740 \uAC12\uC73C\uB85C \uBC14\uAFB8\uC138\uC694."
-      });
+      return [
+        {
+          level: "error",
+          varName,
+          message: "\uC790\uB9AC\uD45C\uC2DC\uC790\uAC00 \uADF8\uB300\uB85C\uC785\uB2C8\uB2E4 \u2014 \uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09\uBC1B\uC740 \uAC12\uC73C\uB85C \uBC14\uAFB8\uC138\uC694."
+        }
+      ];
     }
-  }
-  const appId = referenced.has("VITE_BSTAGE_APP_ID") ? env2.VITE_BSTAGE_APP_ID?.trim() : void 0;
-  const appSecret = referenced.has("VITE_BSTAGE_APP_SECRET") ? env2.VITE_BSTAGE_APP_SECRET?.trim() : void 0;
-  const appIdUsable = !!appId && !isPlaceholderValue(appId);
-  const appSecretUsable = !!appSecret && !isPlaceholderValue(appSecret);
-  const swapped = appIdUsable && appId.startsWith(APP_SECRET_PREFIX) || appSecretUsable && appSecret.startsWith(APP_ID_PREFIX);
+    return [];
+  });
+  const usableAppId = appId && !isPlaceholderValue(appId) ? appId : void 0;
+  const usableAppKeys = appKeys.filter(
+    (k) => !!k.value && !isPlaceholderValue(k.value)
+  );
+  const swappedKey = usableAppKeys.find((k) => k.value.startsWith(APP_ID_PREFIX));
+  const swapped = usableAppId?.startsWith(APP_KEY_PREFIX) || swappedKey !== void 0;
   if (swapped) {
-    issues.push({
-      level: "error",
-      varName: "VITE_BSTAGE_APP_ID",
-      message: `APP_ID\uC640 APP_SECRET\uC774 \uC11C\uB85C \uBC14\uB010 \uAC83 \uAC19\uC2B5\uB2C8\uB2E4 \u2014 APP_ID\uB294 "${APP_ID_PREFIX}", APP_SECRET\uC740 "${APP_SECRET_PREFIX}"\uB85C \uC2DC\uC791\uD574\uC57C \uD569\uB2C8\uB2E4.`
-    });
-    return issues;
-  }
-  if (appIdUsable && !appId.startsWith(APP_ID_PREFIX)) {
-    issues.push({
-      level: "warn",
-      varName: "VITE_BSTAGE_APP_ID",
-      message: `"${APP_ID_PREFIX}"\uB85C \uC2DC\uC791\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 \uD30C\uD2B8\uB108 \uCF58\uC194 \uBC1C\uAE09 \uAC12\uC774 \uB9DE\uB294\uC9C0 \uD655\uC778\uD558\uC138\uC694.`
-    });
-  }
-  if (appSecretUsable && !appSecret.startsWith(APP_SECRET_PREFIX)) {
-    issues.push({
-      level: "warn",
-      varName: "VITE_BSTAGE_APP_SECRET",
-      message: `"${APP_SECRET_PREFIX}"\uB85C \uC2DC\uC791\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 \uD30C\uD2B8\uB108 \uCF58\uC194 \uBC1C\uAE09 \uAC12\uC774 \uB9DE\uB294\uC9C0 \uD655\uC778\uD558\uC138\uC694.`
-    });
-  }
-  return issues;
+    const keyLabel = shortName(swappedKey?.varName ?? appKeys[0]?.varName ?? APP_KEY_VAR);
+    return [
+      ...presenceIssues,
+      {
+        level: "error",
+        varName: "VITE_BSTAGE_APP_ID",
+        message: `APP_ID\uC640 ${keyLabel}\uAC00 \uC11C\uB85C \uBC14\uB010 \uAC83 \uAC19\uC2B5\uB2C8\uB2E4 \u2014 APP_ID\uB294 "${APP_ID_PREFIX}", ${keyLabel}\uB294 "${APP_KEY_PREFIX}"\uB85C \uC2DC\uC791\uD574\uC57C \uD569\uB2C8\uB2E4.`
+      }
+    ];
+  }
+  const prefixWarnings = [
+    ...usableAppId && !usableAppId.startsWith(APP_ID_PREFIX) ? [
+      {
+        level: "warn",
+        varName: "VITE_BSTAGE_APP_ID",
+        message: `"${APP_ID_PREFIX}"\uB85C \uC2DC\uC791\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 \uD30C\uD2B8\uB108 \uCF58\uC194 \uBC1C\uAE09 \uAC12\uC774 \uB9DE\uB294\uC9C0 \uD655\uC778\uD558\uC138\uC694.`
+      }
+    ] : [],
+    ...usableAppKeys.filter((k) => !k.value.startsWith(APP_KEY_PREFIX)).map(
+      (k) => ({
+        level: "warn",
+        varName: k.varName,
+        message: `"${APP_KEY_PREFIX}"\uB85C \uC2DC\uC791\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 \uD30C\uD2B8\uB108 \uCF58\uC194 \uBC1C\uAE09 \uAC12\uC774 \uB9DE\uB294\uC9C0 \uD655\uC778\uD558\uC138\uC694.`
+      })
+    )
+  ];
+  return [...presenceIssues, ...prefixWarnings];
+}
+function resolveAppKeys(env2, referenced) {
+  return [APP_KEY_VAR, LEGACY_APP_KEY_VAR].filter((varName) => referenced.has(varName)).map((varName) => {
+    const other = varName === APP_KEY_VAR ? LEGACY_APP_KEY_VAR : APP_KEY_VAR;
+    return { varName, value: env2[varName]?.trim() || env2[other]?.trim() || void 0 };
+  });
+}
+function shortName(varName) {
+  return varName.replace(/^VITE_BSTAGE_/, "");
 }
 
 // src/commands/build.ts
@@ -1739,7 +1765,7 @@ ${commandsSection}
 - \uC804\uC5ED CSS \uD30C\uC77C(\`<link>\`, \uC678\uBD80 \uC2A4\uD0C0\uC77C\uC2DC\uD2B8)\uC744 \uC0AC\uC6A9\uD558\uC9C0 \uC54A\uB294\uB2E4 \u2014 Shadow DOM \uB0B4\uBD80\uC5D0 \uC801\uC6A9\uB418\uC9C0 \uC54A\uB294\uB2E4.
 - **\`import './style.css'\`\uB85C \uC2A4\uD0C0\uC77C\uC744 \uB123\uC9C0 \uC54A\uB294\uB2E4 \u2014 \uBC30\uD3EC \uC0B0\uCD9C\uBB3C\uC5D0\uC11C \uC0AC\uB77C\uC9C4\uB2E4.** \uB85C\uCEEC \uAC1C\uBC1C \uD654\uBA74\uC5D0\uC11C\uB294 \uC801\uC6A9\uB418\uC5B4 \uB208\uCE58\uCC44\uAE30 \uC5B4\uB835\uB2E4. CSS \uD30C\uC77C\uC744 \uC4F0\uB824\uBA74 \`import css from './style.css?inline'\`\uC73C\uB85C \uBB38\uC790\uC5F4\uC744 \uAC00\uC838\uC640 \`createTemplate(..., { styles: css })\`\uC5D0 \uB118\uAE30\uAC70\uB098 \uCEF4\uD3EC\uB10C\uD2B8 \uC548 \`<style>{css}</style>\`\uB85C \uB80C\uB354\uD55C\uB2E4. inline \`style={{}}\`\uB3C4 \uB41C\uB2E4
 - UI \uC0C9\xB7\uD0C0\uC774\uD3EC\xB7\uADF8\uB9BC\uC790\uB97C hex/rgb\uB85C \uD558\uB4DC\uCF54\uB529\uD558\uC9C0 \uC54A\uB294\uB2E4 \u2014 \uC704 '\uB514\uC790\uC778' \uC139\uC158\uC758 \uB514\uC790\uC778 \uD1A0\uD070\uC744 \uC0AC\uC6A9
-- \uC571\uD0A4(APP-ID \`bsa_\u2026\`\xB7Secret \`bsp_\u2026\`, \uC5B4\uB4DC\uBBFC \uAC8C\uC774\uD2B8\uC6E8\uC774 \`bsm_\u2026\`)\uB97C \uC18C\uC2A4 \uCF54\uB4DC\uC5D0 \uB9AC\uD130\uB7F4\uB85C \uB123\uC9C0 \uC54A\uB294\uB2E4 \u2014 \uC778\uC99D \uAC12\uC740 \`.env\`(\uCEE4\uBC0B \uC548 \uB428)\uC5D0\uC11C \`import.meta.env.VITE_BSTAGE_*\`\uB85C\uB9CC \uC8FC\uC785\uD55C\uB2E4. pre-commit \uD6C5\uC774 \uCEE4\uBC0B \uC804 \uAC80\uCD9C\xB7\uCC28\uB2E8\uD558\uBA70 \`--no-verify\`\uB85C \uC6B0\uD68C\uD558\uC9C0 \uC54A\uB294\uB2E4
+- \uC571\uD0A4(APP-ID \`bsa_\u2026\`\xB7APP KEY \`bsp_\u2026\`, \uC5B4\uB4DC\uBBFC \uAC8C\uC774\uD2B8\uC6E8\uC774 \`bsm_\u2026\`)\uB97C \uC18C\uC2A4 \uCF54\uB4DC\uC5D0 \uB9AC\uD130\uB7F4\uB85C \uB123\uC9C0 \uC54A\uB294\uB2E4 \u2014 \uC778\uC99D \uAC12\uC740 \`.env\`(\uCEE4\uBC0B \uC548 \uB428)\uC5D0\uC11C \`import.meta.env.VITE_BSTAGE_*\`\uB85C\uB9CC \uC8FC\uC785\uD55C\uB2E4. pre-commit \uD6C5\uC774 \uCEE4\uBC0B \uC804 \uAC80\uCD9C\xB7\uCC28\uB2E8\uD558\uBA70 \`--no-verify\`\uB85C \uC6B0\uD68C\uD558\uC9C0 \uC54A\uB294\uB2E4
 ${apiForbidBullet}
 `;
 }
@@ -1761,14 +1787,15 @@ function claudeMd() {
 }
 
 // src/templates/env.ts
-function env({ phase, appId, appSecret, tenantId }) {
+function env({ phase, appId, appKey, tenantId }) {
   return `VITE_BSTAGE_PHASE=${phase}
 
 # \uC778\uC99D \uC815\uBCF4(\uC120\uD0DD) \u2014 BstageClient\uB85C API\uB97C \uD638\uCD9C\uD560 \uB54C\uB9CC \uD544\uC694\uD569\uB2C8\uB2E4.
 # API \uC5C6\uC774 UI\uB9CC \uB80C\uB354\uD558\uB294 \uD15C\uD50C\uB9BF\uC740 \uAC12\uC744 \uCC44\uC6B0\uC9C0 \uC54A\uC544\uB3C4 \uB429\uB2C8\uB2E4.
 # .env\uB294 \uCEE4\uBC0B\uB418\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4(.gitignore). \uAC12\uC740 b.stage \uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09.
+# APP_KEY\uB294 \uD3EC\uD138\uC758 "APP KEY"\uC640 \uAC19\uC740 \uAC12\uC785\uB2C8\uB2E4. \uBE0C\uB77C\uC6B0\uC800\uC5D0 \uB178\uCD9C\uB418\uB294 \uAC12\uC774\uB77C \uBE44\uBC00\uAC12\uC774 \uC544\uB2D9\uB2C8\uB2E4.
 VITE_BSTAGE_APP_ID=${appId}
-VITE_BSTAGE_APP_SECRET=${appSecret}
+VITE_BSTAGE_APP_KEY=${appKey}
 VITE_BSTAGE_TENANT_ID=${tenantId}
 
 # CF Access \uC790\uACA9\uC99D\uBA85 \u2014 dev\xB7qa phase\uB85C \uAC1C\uBC1C\uD560 \uB54C\uB9CC \uD544\uC694\uD569\uB2C8\uB2E4.
@@ -1892,9 +1919,9 @@ createTemplate(MyWidget, {
 VITE_BSTAGE_PHASE=dev   # dev | qa | real | sandbox
 \`\`\`
 
-API \uD0A4(APP-ID/Secret)\uB294 \`.env\`\uC5D0\uC11C \uC124\uC815\uD569\uB2C8\uB2E4. \`.env\`\uB294 \uCEE4\uBC0B\uB418\uC9C0 \uC54A\uC73C\uB2C8, clone \uD6C4 \`.env.example\`\uC744 \`.env\`\uB85C \uBCF5\uC0AC\uD574 \uAC12\uC744 \uCC44\uC6B0\uC138\uC694.
+API \uD0A4(APP-ID/APP KEY)\uB294 \`.env\`\uC5D0\uC11C \uC124\uC815\uD569\uB2C8\uB2E4. \`.env\`\uB294 \uCEE4\uBC0B\uB418\uC9C0 \uC54A\uC73C\uB2C8, clone \uD6C4 \`.env.example\`\uC744 \`.env\`\uB85C \uBCF5\uC0AC\uD574 \uAC12\uC744 \uCC44\uC6B0\uC138\uC694.
 
-> **\uBCF4\uC548**: \uC571\uD0A4 \uAC12\uC744 \uC18C\uC2A4 \uCF54\uB4DC(\uC608: \`client.ts\`)\uC5D0 \uC9C1\uC811 \uB123\uC9C0 \uB9C8\uC138\uC694 \u2014 \uBC18\uB4DC\uC2DC \`.env\`\uB85C\uB9CC \uC8FC\uC785\uD569\uB2C8\uB2E4. \`bstage init\`\uC774 \uC124\uCE58\uD55C pre-commit \uD6C5\uC774 \uCEE4\uBC0B \uC804 \uD0A4 \uB9AC\uD130\uB7F4\uC744 \uCC28\uB2E8\uD558\uBA70, \`--no-verify\`\uB85C \uC6B0\uD68C\uD558\uC9C0 \uB9C8\uC138\uC694.
+> **\uADDC\uCE59**: \uC571\uD0A4 \uAC12\uC744 \uC18C\uC2A4 \uCF54\uB4DC(\uC608: \`client.ts\`)\uC5D0 \uC9C1\uC811 \uB123\uC9C0 \uB9C8\uC138\uC694 \u2014 \uBC18\uB4DC\uC2DC \`.env\`\uB85C\uB9CC \uC8FC\uC785\uD569\uB2C8\uB2E4. APP KEY\uB294 \uBE0C\uB77C\uC6B0\uC800\uC5D0 \uB178\uCD9C\uB418\uB294 \uAC12\uC774\uB77C \uBE44\uBC00\uC740 \uC544\uB2C8\uC9C0\uB9CC, \uD658\uACBD\uB9C8\uB2E4 \uAC12\uC774 \uB2E4\uB974\uACE0 \uC800\uC7A5\uC18C\uC5D0 \uBC15\uD788\uBA74 \uC7AC\uBC1C\uAE09 \uB54C \uCF54\uB4DC \uC218\uC815\uC774 \uB530\uB77C\uC635\uB2C8\uB2E4. \`bstage init\`\uC774 \uC124\uCE58\uD55C pre-commit \uD6C5\uC774 \uCEE4\uBC0B \uC804 \uD0A4 \uB9AC\uD130\uB7F4\uC744 \uCC28\uB2E8\uD558\uBA70, \`--no-verify\`\uB85C \uC6B0\uD68C\uD558\uC9C0 \uB9C8\uC138\uC694.
 
 ## SDK \uC5C5\uB370\uC774\uD2B8
 
@@ -2541,7 +2568,7 @@ function viteEnvDts() {
 interface ImportMetaEnv {
   readonly VITE_BSTAGE_PHASE: string
   readonly VITE_BSTAGE_APP_ID: string
-  readonly VITE_BSTAGE_APP_SECRET: string
+  readonly VITE_BSTAGE_APP_KEY: string
   readonly VITE_BSTAGE_TENANT_ID: string
 }
 
@@ -2559,7 +2586,7 @@ function clientTs() {
 // clone \uD6C4 .env.example\uC744 .env\uB85C \uBCF5\uC0AC\uD574 \uAC12\uC744 \uCC44\uC6B0\uC138\uC694.
 export const client = new BstageClient({
   appId: import.meta.env.VITE_BSTAGE_APP_ID,
-  appSecret: import.meta.env.VITE_BSTAGE_APP_SECRET,
+  appKey: import.meta.env.VITE_BSTAGE_APP_KEY,
   tenantId: import.meta.env.VITE_BSTAGE_TENANT_ID,
 })
 `;
@@ -2665,7 +2692,7 @@ async function initCommand(options) {
   let phase;
   let target;
   let appId = "";
-  let appSecret = "";
+  let appKey = "";
   let tenantId = "";
   if (options.yes) {
     const targetOpt = options.target ?? "user";
@@ -2758,11 +2785,11 @@ async function initCommand(options) {
         message: "\uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09\uBC1B\uC740 APP-ID\uB97C \uC785\uB825\uD574 \uC8FC\uC138\uC694."
       }) ?? "";
       if (p2.isCancel(appId)) return cancelled();
-      appSecret = await p2.text({
-        message: "\uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09\uBC1B\uC740 Secret \uAC12\uC744 \uC785\uB825\uD574 \uC8FC\uC138\uC694."
+      appKey = await p2.text({
+        message: "\uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09\uBC1B\uC740 APP KEY\uB97C \uC785\uB825\uD574 \uC8FC\uC138\uC694."
       }) ?? "";
-      if (p2.isCancel(appSecret)) return cancelled();
-      warnIfCredentialsSwapped(appId, appSecret);
+      if (p2.isCancel(appKey)) return cancelled();
+      warnIfCredentialsSwapped(appId, appKey);
       tenantId = space;
     }
   }
@@ -2816,7 +2843,7 @@ async function initCommand(options) {
       env({
         phase,
         appId: appId || "YOUR_APP_ID",
-        appSecret: appSecret || "YOUR_APP_SECRET",
+        appKey: appKey || "YOUR_APP_KEY",
         tenantId: tenantId || "YOUR_TENANT_ID"
       })
     ],
@@ -2825,7 +2852,7 @@ async function initCommand(options) {
       env({
         phase,
         appId: "YOUR_APP_ID",
-        appSecret: "YOUR_APP_SECRET",
+        appKey: "YOUR_APP_KEY",
         tenantId: "YOUR_TENANT_ID"
       })
     ]
@@ -2925,12 +2952,12 @@ function validateElementName(v) {
   }
 }
 var APP_ID_PREFIX2 = "bsa_";
-var APP_SECRET_PREFIX2 = "bsp_";
-function warnIfCredentialsSwapped(appId, appSecret) {
-  if (!appId.startsWith(APP_SECRET_PREFIX2) && !appSecret.startsWith(APP_ID_PREFIX2)) return;
+var APP_KEY_PREFIX2 = "bsp_";
+function warnIfCredentialsSwapped(appId, appKey) {
+  if (!appId.startsWith(APP_KEY_PREFIX2) && !appKey.startsWith(APP_ID_PREFIX2)) return;
   p2.log.warn(
-    `APP-ID\uC640 Secret\uC774 \uC11C\uB85C \uBC14\uB010 \uAC83 \uAC19\uC2B5\uB2C8\uB2E4.
-  APP-ID\uB294 "${APP_ID_PREFIX2}", Secret\uC740 "${APP_SECRET_PREFIX2}"\uB85C \uC2DC\uC791\uD569\uB2C8\uB2E4.
+    `APP-ID\uC640 APP KEY\uAC00 \uC11C\uB85C \uBC14\uB010 \uAC83 \uAC19\uC2B5\uB2C8\uB2E4.
+  APP-ID\uB294 "${APP_ID_PREFIX2}", APP KEY\uB294 "${APP_KEY_PREFIX2}"\uB85C \uC2DC\uC791\uD569\uB2C8\uB2E4.
   \uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09\uBC1B\uC740 \uAC12\uC744 \uB2E4\uC2DC \uD655\uC778\uD574 \uC8FC\uC138\uC694.`
   );
 }

package/dist/vite/preset.d.ts

@@ -28,6 +28,25 @@ interface BstageDevPluginOptions {
  */
 declare function bstageDevPlugin(options?: BstageDevPluginOptions): Plugin;
 
+/**
+ * 앱 키 환경변수의 새 이름(`VITE_BSTAGE_APP_KEY`)과 옛 이름(`VITE_BSTAGE_APP_SECRET`)을 서로 이어 붙이는
+ * `define` 항목을 만든다.
+ *
+ * 별칭 기간에는 소스와 `.env`가 다른 이름을 쓰는 조합이 실제로 생긴다 — 기존 프로젝트의 `client.ts`는
+ * 옛 이름을 읽는데 포털의 환경변수 입력은 새 이름을 넣고, 반대로 새 스캐폴드에 옛 `.env`를 복사해
+ * 오기도 한다. Vite는 `import.meta.env.X`를 빌드 시점에 문자열로 치환하므로 이 조합은 번들에
+ * undefined가 박혀 배포 뒤 401로만 드러난다. 한쪽만 있으면 다른 이름으로도 같은 값이 읽히게 한다.
+ *
+ * - 둘 다 있으면 손대지 않는다(각자 실제 값). 둘 다 없으면 아무것도 정의하지 않는다(UI 전용 템플릿).
+ * - 값은 `JSON.stringify`로 감싼다 — define은 코드 조각 치환이라 따옴표가 없으면 식별자가 된다.
+ */
+declare function appKeyEnvDefine(env: Record<string, string | undefined>): Record<string, string>;
+/**
+ * `appKeyEnvDefine`을 Vite 설정에 얹는 플러그인. `bstage build`(프리셋)와 `bstageDevPlugin`(dev 서버)이
+ * 함께 쓴다.
+ */
+declare function appKeyEnvAliasPlugin(): Plugin;
+
 interface VitePresetOptions {
     /** Entry file path (default: 'src/index.tsx') */
     entry?: string;
@@ -40,7 +59,8 @@ interface VitePresetOptions {
  *
  * `<script>` 태그로 로드 가능한 IIFE 번들(`template.js`)을 출력.
  * React를 번들에 포함(외부화하지 않음). CSS는 Shadow DOM 주입을 위해 JS에 인라인.
+ * 앱 키 env 별칭(`appKeyEnvAliasPlugin`)을 얹어 옛 이름·새 이름 어느 쪽 `.env`든 번들에 실리게 한다.
  */
 declare function createViteConfig(options?: VitePresetOptions): UserConfig;
 
-export { type BstageDevPluginOptions, type VitePresetOptions, bstageDevPlugin, createViteConfig };
+export { type BstageDevPluginOptions, type VitePresetOptions, appKeyEnvAliasPlugin, appKeyEnvDefine, bstageDevPlugin, createViteConfig };

package/dist/vite/preset.js

@@ -1,8 +1,12 @@
 import {
+  appKeyEnvAliasPlugin,
+  appKeyEnvDefine,
   bstageDevPlugin,
   createViteConfig
-} from "../chunk-FER3TEK7.js";
+} from "../chunk-COUDGZIA.js";
 export {
+  appKeyEnvAliasPlugin,
+  appKeyEnvDefine,
   bstageDevPlugin,
   createViteConfig
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bstage-sdk/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "bstage SDK CLI — build b.stage templates",
   "type": "module",
   "publishConfig": {
@@ -31,13 +31,13 @@
     "commander": "^12.0.0",
     "picocolors": "^1.1.1",
     "vite": "^7.0.0",
-    "@bstage-sdk/core": "0.2.0"
+    "@bstage-sdk/core": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
-    "@bstage-sdk/design": "0.2.0"
+    "@bstage-sdk/design": "0.3.0"
   },
   "license": "MIT",
   "scripts": {