project-auto-wizard 0.12.2 → 0.13.0

package/src/core/types.js

@@ -0,0 +1,113 @@
+// 프로젝트 타입 레지스트리 — 타입별 지식(감지 마커, 감지 순서, 버전·빌드 번호 파일)을 한 곳에 둔다.
+// 타입 목록·마커 맵·감지 체인은 모두 이 표에서 만들어지므로, 새 타입은 여기에 한 줄을 더하는 것에서 시작한다.
+// (릴리스 시점의 버전 파일 쓰기는 payload/scripts/version_manager.py가 따로 담당한다.)
+//
+// 필드:
+//   id                 CLI·version.yml에 쓰이는 타입 이름. 배열 순서가 곧 --help·대화형 선택지 표시 순서다.
+//   markers            그 타입의 근거 파일. [0]이 대표 파일이고, 모노레포 경로 탐색은 이 순서로 우선순위를 둔다.
+//   detectBy           자동 감지 방식 — "markers": markers 중 하나라도 있으면 감지
+//                      "package": package.json 의존성 키(packageDep)로 감지
+//                      "package-fallback": package.json은 있지만 위 어느 것도 아닐 때
+//                      없음: 자동 감지하지 않는다(basic은 아무것도 감지되지 않았을 때의 결과).
+//   detectOrder        같은 detectBy 안에서의 판정 순서. 앞선 규칙이 이긴다(expo 앱은 react-native 의존성도 가짐).
+//   versionSources     설치 시 버전을 읽을 파일 키(detect.js의 sources) — 주 타입일 때 이 순서로 먼저 읽는다.
+//   buildNumberSource  모바일 빌드 번호를 읽을 파일 키(detect.js의 detectBuildNumberFromFiles).
+//   singleServerCd     배포 방식 변형 없이 서버 배포 CD가 하나뿐일 때 그 워크플로우 파일명.
+export const TYPES = [
+  {
+    id: "spring",
+    markers: ["build.gradle", "build.gradle.kts", "pom.xml"],
+    detectBy: "markers", detectOrder: 2,
+    versionSources: ["gradle", "gradleKts", "pom"],
+  },
+  {
+    id: "flutter",
+    markers: ["pubspec.yaml"],
+    detectBy: "markers", detectOrder: 1,
+    versionSources: ["pubspec"],
+    buildNumberSource: "pubspec",
+  },
+  {
+    id: "next",
+    markers: ["package.json"],
+    detectBy: "package", packageDep: "next", detectOrder: 3,
+    versionSources: ["packageJson"],
+    singleServerCd: "PROJECT-NEXT-CICD.yaml",
+  },
+  {
+    id: "react",
+    markers: ["package.json"],
+    detectBy: "package", packageDep: "react", detectOrder: 4,
+    versionSources: ["packageJson"],
+    singleServerCd: "PROJECT-REACT-CICD.yaml",
+  },
+  {
+    id: "react-native",
+    markers: ["package.json"],
+    detectBy: "package", packageDep: "react-native", detectOrder: 2,
+    // 릴리스 때 동기화하는 네이티브 파일이 기준이고, 거기서 못 읽을 때만 package.json을 본다.
+    versionSources: ["reactNative", "packageJson"],
+    buildNumberSource: "androidGradle",
+  },
+  {
+    // Expo는 최신 create-expo-app 템플릿처럼 app.json 없이 app.config.ts/js만 쓸 수 있다.
+    // 구성 파일이 아예 없어도 expo 의존성이 있는 package.json이 곧 근거다.
+    id: "react-native-expo",
+    markers: ["app.json", "app.config.ts", "app.config.js", "package.json"],
+    detectBy: "package", packageDep: "expo", detectOrder: 1,
+    versionSources: ["appJson", "packageJson"],
+    buildNumberSource: "expoAppJson",
+  },
+  {
+    id: "node",
+    markers: ["package.json"],
+    detectBy: "package-fallback",
+    versionSources: ["packageJson"],
+  },
+  {
+    id: "python",
+    markers: ["pyproject.toml", "setup.py", "requirements.txt"],
+    detectBy: "markers", detectOrder: 3,
+    versionSources: ["pyproject", "setupPy"],
+  },
+  {
+    // 마커 파일이 없는 타입 — 아무것도 감지되지 않았을 때의 결과이자 경로가 필요 없는 타입.
+    id: "basic",
+    markers: [],
+  },
+  {
+    id: "go",
+    markers: ["go.mod"],
+    detectBy: "markers", detectOrder: 4,
+    versionSources: [],
+  },
+];
+
+// 감지 결과가 하나도 없을 때의 타입
+export const FALLBACK_TYPE = "basic";
+
+const BY_ID = new Map(TYPES.map((t) => [t.id, t]));
+
+// 알 수 없는 타입은 undefined — 호출부가 각자의 기본값을 정한다.
+export const typeInfo = (id) => BY_ID.get(id);
+
+// 표시 순서 그대로의 타입 이름 목록
+// VALID_TYPES·ALL_TYPES가 같은 배열을 공유하므로 한쪽에서 바꿔 다른 쪽이 오염되지 않게 고정한다.
+export const TYPE_IDS = Object.freeze(TYPES.map((t) => t.id));
+
+const byDetectOrder = (a, b) => a.detectOrder - b.detectOrder;
+
+// 파일 존재만으로 감지하는 타입 (감지 순서대로)
+export const MARKER_DETECTED_TYPES = TYPES.filter((t) => t.detectBy === "markers").sort(byDetectOrder);
+
+// package.json 의존성으로 가르는 타입 (판정 순서대로)
+export const PACKAGE_DETECTED_TYPES = TYPES.filter((t) => t.detectBy === "package").sort(byDetectOrder);
+
+// package.json이 있지만 알려진 프레임워크 의존성이 없을 때의 타입
+export const PACKAGE_FALLBACK_TYPE = TYPES.find((t) => t.detectBy === "package-fallback").id;
+
+// 모바일 빌드 번호(version_code)를 가진 타입
+export const BUILD_NUMBER_TYPES = new Set(TYPES.filter((t) => t.buildNumberSource).map((t) => t.id));
+
+// 배포 방식 변형 없이 서버 배포 CD가 하나뿐인 워크플로우 파일명
+export const SINGLE_SERVER_CD_FILES = new Set(TYPES.filter((t) => t.singleServerCd).map((t) => t.singleServerCd));

package/src/core/verify.js

@@ -48,31 +48,97 @@ const AUTO_SECRETS = new Set(["GITHUB_TOKEN"]);
 export const OPTIONAL_SECRETS = new Set(["AI_API_KEY", "WORKFLOW_PAT"]);
 const SECRET_RE = /secrets\.([A-Z][A-Z0-9_]*)/g;
 
-// 설치된 워크플로우가 요구하는 GitHub Secret 목록.
-// 완료 화면이 WORKFLOW_PAT와 권한만 안내하는 바람에, 배포 워크플로우가 실제로 필요로 하는
-// SERVER_HOST·SSH_KEY 같은 값이 하나도 안내되지 않았다. 설치 직후 상태로는 배포가 돌지 않는데
-// 그 사실이 어디에도 드러나지 않는다.
-//
-// 반환: Map<secretName, string[] 그 secret을 쓰는 파일명>
-export function collectRequiredSecrets(workflowsDir, filenames = []) {
-  const out = new Map();
+// 워크플로우 머리 주석의 "NAME (선택)" 표기 — 워크플로우가 비어 있어도 동작하도록 작성된 secret이다.
+const OPTIONAL_NOTE_RE = /^\s*#\s*-?\s*([A-Z][A-Z0-9_]*)\s*\(선택/;
+// `secrets.A || secrets.B` — 둘 중 하나만 있으면 된다.
+const EITHER_RE = /^\s*\|\|\s*secrets\.([A-Z][A-Z0-9_]*)/;
+// `secrets.A || '3000'`, `secrets.A || vars.A` — 기본값·대체값이 있다.
+const FALLBACK_AFTER_RE = /^\s*\|\|/;
+const FALLBACK_BEFORE_RE = /\|\|\s*$/;
+export const EITHER_SEP = " 또는 ";
+
+// 한 파일 안의 secret 참조를 필수 / 둘 중 하나 / 선택으로 가른다.
+function classifyFile(content) {
+  const lines = content.split(/\r?\n/);
+  const noted = new Set();
+  for (const line of lines) {
+    const m = line.match(OPTIONAL_NOTE_RE);
+    if (m) noted.add(m[1]);
+  }
+  const singles = new Set();
+  const pairs = [];
+  const optional = new Set();
+  for (const line of lines) {
+    if (isCommented(line)) continue;
+    const matches = [...line.matchAll(SECRET_RE)];
+    for (let i = 0; i < matches.length; i++) {
+      const m = matches[i];
+      const name = m[1];
+      const rest = line.slice(m.index + m[0].length);
+      const either = rest.match(EITHER_RE);
+      if (either) {
+        pairs.push([name, either[1]]);
+        i++; // 짝의 오른쪽은 이미 묶었다
+      } else if (FALLBACK_AFTER_RE.test(rest) || FALLBACK_BEFORE_RE.test(line.slice(0, m.index))) {
+        optional.add(name);
+      } else {
+        singles.add(name);
+      }
+    }
+  }
+  const out = { required: [], optional: [] };
+  for (const name of singles) (noted.has(name) ? out.optional : out.required).push(name);
+  for (const name of optional) out.optional.push(name);
+  for (const [a, b] of pairs) {
+    const key = `${a}${EITHER_SEP}${b}`;
+    (noted.has(a) || noted.has(b) ? out.optional : out.required).push(key);
+  }
+  return out;
+}
+
+// 설치된 워크플로우의 secret을 필수와 선택으로 나눈다.
+// 참조한 이름을 전부 필수로 세면 기본값이 있는 것·둘 중 하나면 되는 폴백 쌍까지 "등록해야 동작합니다"에
+// 섞여 개수가 부풀고, 처음 쓰는 사용자가 필요 없는 secret까지 등록하게 된다.
+// 반환: { required: Map<이름|"A 또는 B", 파일명[]>, optional: Map<같은 형식> }
+export function classifySecrets(workflowsDir, filenames = []) {
+  const required = new Map();
+  const optional = new Map();
+  const add = (map, key, filename) => {
+    if (!map.has(key)) map.set(key, []);
+    if (!map.get(key).includes(filename)) map.get(key).push(filename);
+  };
+  const skip = (key) => key.split(EITHER_SEP).some((n) => AUTO_SECRETS.has(n) || OPTIONAL_SECRETS.has(n));
   for (const filename of filenames) {
     const p = join(workflowsDir, filename);
     if (!existsSync(p)) continue;
     let content;
     try { content = readFileSync(p, "utf8"); } catch { continue; }
-    for (const line of content.split(/\r?\n/)) {
-      if (isCommented(line)) continue;
-      for (const m of line.matchAll(SECRET_RE)) {
-        const name = m[1];
-        if (AUTO_SECRETS.has(name) || OPTIONAL_SECRETS.has(name)) continue;
-        if (!out.has(name)) out.set(name, []);
-        const users = out.get(name);
-        if (!users.includes(filename)) users.push(filename);
-      }
-    }
+    const r = classifyFile(content);
+    for (const k of r.required) if (!skip(k)) add(required, k, filename);
+    for (const k of r.optional) if (!skip(k)) add(optional, k, filename);
   }
-  return new Map([...out.entries()].sort(([a], [b]) => a.localeCompare(b)));
+  // 한 파일에서라도 단독으로 필수인 이름은 필수다 — 그 이름이 든 폴백 쌍·선택 항목은 이미 충족되므로 뺀다.
+  const requiredNames = new Set([...required.keys()].filter((k) => !k.includes(EITHER_SEP)));
+  const coveredByRequired = (k) => k.split(EITHER_SEP).some((n) => requiredNames.has(n));
+  for (const k of [...required.keys()]) if (k.includes(EITHER_SEP) && coveredByRequired(k)) required.delete(k);
+  for (const k of [...optional.keys()]) if (required.has(k) || coveredByRequired(k)) optional.delete(k);
+  const sorted = (m) => new Map([...m.entries()].sort(([a], [b]) => a.localeCompare(b)));
+  return { required: sorted(required), optional: sorted(optional) };
+}
+
+// 설치된 워크플로우가 요구하는 GitHub Secret 목록.
+// 완료 화면이 WORKFLOW_PAT와 권한만 안내하는 바람에, 배포 워크플로우가 실제로 필요로 하는
+// SERVER_HOST·SSH_KEY 같은 값이 하나도 안내되지 않았다. 설치 직후 상태로는 배포가 돌지 않는데
+// 그 사실이 어디에도 드러나지 않는다.
+//
+// 반환: Map<secretName 또는 "A 또는 B", string[] 그 secret을 쓰는 파일명>
+export function collectRequiredSecrets(workflowsDir, filenames = []) {
+  return classifySecrets(workflowsDir, filenames).required;
+}
+
+// 없어도 워크플로우가 도는 secret(기본값·대체값이 있거나 머리 주석에 "(선택)"으로 적힌 것).
+export function collectOptionalSecrets(workflowsDir, filenames = []) {
+  return classifySecrets(workflowsDir, filenames).optional;
 }
 
 // SSH 인증 방식에 따라 둘 중 하나만 필요한 secret — 사용자가 이미 답한 값으로 목록을 좁힌다.

package/src/core/version-yml.js

@@ -4,7 +4,7 @@ import {
   ENV_MODES, DEPLOY_MODES, DEFAULT_ENV_MODE, DEFAULT_DEPLOY_MODE, STORE_PLATFORMS, formatStoreList,
 } from "./flutter-options.js";
 
-// version.yml 파싱·생성 (.sh create_version_yml 등가, 전체 재생성 전략).
+// version.yml 파싱·생성 (전체 재생성 전략).
 // ⚠️ YAML 재직렬화 금지 — 주석이 데이터.
 // 레이아웃 단일 진실 = payload/version.yml.template (호출부가 templateText로 주입).
 
@@ -43,7 +43,7 @@ const FLUTTER_OPTION_KEYS = {
   android_deploy_mode: "androidDeployMode", ios_deploy_mode: "iosDeployMode",
 };
 
-// metadata.template.options 상태머신 파싱 (.sh read_template_options L2361~2416 등가).
+// metadata.template.options 상태머신 파싱.
 // 반환: { semverAuto: bool|null, copilotAi: bool|null, deployStyle: string|null,
 //         envMode/flutterStore/androidDeployMode/iosDeployMode: string|null } — null=미기재.
 // 구 synology·coderabbit 키 등 다른 키는 어느 분기에도 안 걸려 자연히 무시된다(파싱 에러 없음).
@@ -52,7 +52,7 @@ export function parseTemplateOptions(content) {
     semverAuto: null, copilotAi: null, deployStyle: null,
     envMode: null, flutterStore: null, androidDeployMode: null, iosDeployMode: null,
   };
-  // 값 정규화: 따옴표 제거 + 트림 (.sh tr -d '"' | tr -d "'" | xargs 등가)
+  // 값 정규화: 따옴표 제거 + 트림
   // 인라인 주석(` # ...`)을 먼저 떼고 따옴표·공백을 정리한다. 문자열 값을 받는 키(deploy_style)는
   // 주석을 안 떼면 "simple # simple | nginx ..." 가 통째로 값이 된다.
   const strip = (s) => String(s).replace(/\s+#.*$/, "").replace(/["']/g, "").trim();
@@ -80,16 +80,16 @@ export function parseTemplateOptions(content) {
         if (v === "false") out.copilotAi = false;
         continue;
       }
-      // 들여쓰기 0~4칸의 다른 키 → options 섹션 종료 (.sh L2404~2408)
+      // 들여쓰기 0~4칸의 다른 키 → options 섹션 종료
       if (/^\s{0,4}[a-z_]+:/.test(line)) { inOptions = false; inTemplate = false; }
     }
-    // 최상위 키 → template 섹션 종료 (.sh L2411~2415)
+    // 최상위 키 → template 섹션 종료
     if (inTemplate && /^[a-z_]+:/.test(line)) { inTemplate = false; inOptions = false; }
   }
   return out;
 }
 
-// 기존 version.yml에서 값 추출 (.sh grep/sed 등가, 주석 라인 오탐 방지).
+// 기존 version.yml에서 값 추출 (라인 기반, 주석 라인 오탐 방지).
 export function parseExisting(content) {
   const text = String(content || "");
   const line = (re) => {
@@ -135,7 +135,31 @@ export function parseExisting(content) {
   const options = parseTemplateOptions(text);
   // metadata.template.branches — main/develop/mode (업데이트 모드 재질문 생략용)
   const branches = parseTemplateBranches(text);
-  return { version, versionCode, types, paths, templateVersion, options, branches, extraTopLevel: parseExtraTopLevel(text) };
+  return {
+    version, versionCode, types, paths, templateVersion, options, branches,
+    deploy: parseDeployBlock(text), extraTopLevel: parseExtraTopLevel(text),
+  };
+}
+
+// deploy 블록 파싱 — 설치 때 답한 배포 값을 다시 읽어 재실행·업데이트의 기본값으로 쓴다.
+// 쓰기만 하고 읽지 않으면 손대지 않은 파일은 치환을 건너뛰어 블록이 사라지고, 자동 갱신은
+// 사용자가 고른 값을 템플릿 기본값으로 되돌린다.
+// 반환: Map<type, Map<KEY, value>> (값은 buildVersionYml이 쓴 큰따옴표 이스케이프를 푼 원문)
+export function parseDeployBlock(content) {
+  const out = new Map();
+  let inDeploy = false;
+  let current = null;
+  for (const raw of String(content || "").split("\n")) {
+    const l = raw.replace(/\r$/, "");
+    if (/^deploy:/.test(l)) { inDeploy = true; current = null; continue; }
+    if (!inDeploy) continue;
+    if (/^\S/.test(l)) { inDeploy = false; continue; } // 다음 최상위 키 → 블록 종료
+    const t = l.match(/^ {2}([a-z][a-z-]*):\s*(?:#.*)?$/);
+    if (t) { current = new Map(); out.set(t[1], current); continue; }
+    const kv = l.match(/^ {4}([A-Za-z_][A-Za-z0-9_]*):\s*"((?:[^"\\]|\\.)*)"/);
+    if (kv && current) current.set(kv[1], kv[2].replace(/\\(["\\])/g, "$1"));
+  }
+  return out;
 }
 
 // metadata.template.branches 블록 파싱. 셋 다 있어야 유효 — 아니면 null.
@@ -245,6 +269,7 @@ export function buildVersionYml({
     if (t === "{{PROJECT_PATHS}}") { if (pathsBlock) out.push(pathsBlock); continue; }
     if (t === "{{FLUTTER_OPTIONS}}") { if (flutterBlock) out.push(flutterBlock); continue; }
     if (t === "{{DEPLOY}}") { if (deployBlock) out.push(deployBlock); continue; }
+    if (t.startsWith("deploy_style:") && deployStyle === null) continue; // 서버 배포가 없는 타입은 기록하지 않는다
     out.push(line.replace(/\{\{([A-Z][A-Z0-9_]*)\}\}/g, (_, name) => {
       if (name in scalars) return scalars[name];
       throw new Error(`version.yml.template에 알 수 없는 플레이스홀더: {{${name}}}`);
@@ -259,6 +284,14 @@ export function buildVersionYml({
   return text.replace(/\n{3,}$/, "\n"); // 말미 과잉 빈 줄 정리
 }
 
+// 설치 시각 줄(metadata.last_updated 등)만 다른가 — 바뀐 게 없는 재실행이 매번 파일을 고쳐
+// 작업트리를 dirty하게 만들지 않도록 호출부가 쓰기를 건너뛰는 데 쓴다.
+const TIMESTAMP_LINE = /^\s*(last_updated|integration_date|integrated_date|last_update_date):/;
+export function sameIgnoringTimestamps(a, b) {
+  const norm = (t) => String(t).replace(/\r\n/g, "\n").split("\n").filter((l) => !TIMESTAMP_LINE.test(l)).join("\n");
+  return norm(a) === norm(b);
+}
+
 // context 하나로 version.yml 최종형을 만든다 — 실제 설치(full)와 미리보기(dry-run)가
 // 같은 함수를 쓰게 해서 "미리보기와 결과가 다른" 상황을 구조적으로 막는다.
 // deployValues는 실제 설치에서만 존재한다(미리보기는 치환을 수행하지 않으므로 빈 Map).
@@ -275,7 +308,8 @@ export function renderVersionYml(context, templateText, { pathMarkers, deployVal
       templateVersion,
       includeSemverAuto: includeSemverAuto !== false,
       includeCopilotAi: includeCopilotAi === true,
-      deployStyle: deployStyle || DEFAULT_DEPLOY_STYLE,
+      // null = 서버 배포 워크플로우가 없는 타입이라 배포 방식이 의미 없음(기록 생략)
+      deployStyle: deployStyle === null ? null : (deployStyle || DEFAULT_DEPLOY_STYLE),
       optionsDate: today,
     },
   });

package/src/core/wizard-env.js

@@ -1,11 +1,11 @@
-// @wizard env 토큰 엔진 (.sh configure_workflow_env / _wf_set_env / _wf_is_unchanged 등가).
+// @wizard env 토큰 엔진 — 워크플로우의 ask/auto/fallback 마커 치환과 unchanged 판정.
 // ⚠️ YAML 파싱/재직렬화 금지 — 라인 단위 문자열 처리 (포맷·주석 보존이 unchanged 판정 전제).
-// 실측 기준: template_integrator.sh 3282~3360, 3003~3012.
 
-// KEY 정규식: .sh는 [A-Z_]+ (대문자+언더스코어만). ask/auto/fallback 마커가 있는 라인만 대상.
+// KEY 정규식: env 키(대문자)에 더해 workflow_dispatch 입력의 `default:`처럼 소문자 키도 받는다.
+// 마커가 붙은 줄만 대상이라 넓혀도 다른 줄에는 영향이 없다.
 // fallback은 `KEY: ${{ 런타임값 || 'literal' }}` 표현식 안의 기본 리터럴을 교체하는 마커다.
 const MARKER_RE = /#\s*@wizard\s+(ask|auto|fallback):(.*)$/;
-const KEY_RE = /^(\s*)([A-Z_]+):/;
+const KEY_RE = /^(\s*)([A-Za-z_]+):/;
 const PATHS_ANCHOR_RE = /#\s*@wizard\s+paths-anchor/;
 
 // 한 라인을 파싱해 {indent,key,action,arg} 반환. ask/auto/fallback 마커 없으면 null.
@@ -25,8 +25,8 @@ export function escapeYamlDoubleQuoted(value) {
   return String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
 
-// .sh _wf_set_env 등가: `KEY: "..."` 따옴표 안 값 치환 + 그 줄 끝 `# @wizard ...` 주석 제거.
-// 라인 하나에 대해 수행. value가 빈문자면 (.sh는 [ -n "$_val" ] 가드) 치환 스킵.
+// `KEY: "..."` 따옴표 안 값 치환 + 그 줄 끝 `# @wizard ...` 주석 제거.
+// 라인 하나에 대해 수행. value가 빈문자면 치환 스킵(템플릿 기본값을 남긴다).
 export function setEnvLine(line, key, value) {
   if (value === "" || value == null) return line;
   // CRLF 안전: 라인 끝 \r을 분리해 처리 후 복원 (autocrlf 프로젝트 대응)
@@ -61,7 +61,7 @@ export function setFallbackLine(line, value) {
   return expression.replace(LAST_LITERAL_RE, (_m, head, tail) => `${head}'${escaped}'${tail}`) + cr;
 }
 
-// resolver — .sh resolve_token 등가. 값 계산은 주입된 resolvers로 위임(순수성 유지).
+// resolver — 값 계산은 주입된 resolvers로 위임(순수성 유지).
 // resolvers: { repo, "spring-app-yml-dir"(type), "spring-app-yml-path"(type), "flutter-root",
 //              "project-path"(type), "flutter-env-mode", "android-deploy-mode", "ios-deploy-mode" }
 export function resolveToken(name, type, resolvers = {}) {
@@ -77,17 +77,22 @@ export function replaceProjectTokens(text, repoName) {
   return text.replaceAll("__PROJECT_NAME__", repoName).replaceAll("__APP_ARTIFACT_NAME__", repoName);
 }
 
-// 파일 전체 치환 (configure_workflow_env 등가).
+// 파일 전체 치환.
 // content: 원본 워크플로우 텍스트. 반환: 치환된 텍스트.
 // opts:
 //   type          - 프로젝트 타입 (resolver·값 조회용)
 //   values        - Map<key,value>: ask 키의 사용자 선택값 (없으면 기본값=arg 또는 resolver)
-//   useDefaults   - true면 ask도 기본값 사용 (WF_USE_DEFAULTS=true, unchanged 비교의 전제)
+//   useDefaults   - true면 ask도 기본값 사용 (unchanged 비교의 전제)
 //   resolvers     - resolveToken용
 //   repoName      - __PROJECT_NAME__/__APP_ARTIFACT_NAME__ 치환값
 //   projectPath   - paths-anchor 치환용 ('.'이면 anchor 미변경)
+//   savedValues   - Map<key,value>: version.yml deploy 블록에 저장된 이 타입의 값. ask 기본값보다 우선한다
+//                   (재실행·자동 갱신이 설치 때 답한 값을 템플릿 기본값으로 되돌리지 않도록).
 export function substituteEnv(content, opts = {}) {
-  const { type = "", values = new Map(), useDefaults = true, resolvers = {}, repoName = "", projectPath = ".", collectAsks = null } = opts;
+  const {
+    type = "", values = new Map(), useDefaults = true, resolvers = {}, repoName = "", projectPath = ".",
+    collectAsks = null, savedValues = null,
+  } = opts;
   if (!content.includes("@wizard")) return content;
 
   // CRLF 안전: EOL을 분리해 LF 기준으로 파싱·치환하고, 원래 EOL 스타일을 복원한다.
@@ -107,20 +112,22 @@ export function substituteEnv(content, opts = {}) {
       val = resolveToken(p.arg, type, resolvers);
     } else { // ask
       let def = p.arg.startsWith("@") ? resolveToken(p.arg.slice(1), type, resolvers) : p.arg;
+      const saved = savedValues?.get(p.key);
+      if (saved != null && saved !== "") def = saved;
       const chosen = values.get(p.key);
       if (chosen != null && chosen !== "" && !useDefaults) val = chosen;
       else val = def;
-      // ask 키만 수집 (.sh wf_deploy_set — auto는 저장 안 함). deploy 블록용.
+      // ask 키만 수집 (auto는 매번 다시 계산하므로 저장 안 함). deploy 블록용.
       if (collectAsks) collectAsks.set(p.key, replaceProjectTokens(val, repoName));
     }
     lines[i] = setEnvLine(lines[i], p.key, val);
   }
   let out = lines.join(usesCRLF ? "\r\n" : "\n");
 
-  // 잔여 전역 토큰 (.sh 3347~3351)
+  // 잔여 전역 토큰
   out = replaceProjectTokens(out, repoName);
 
-  // paths-anchor (.sh 3353~3360): 경로가 '.'이 아니면 주석 라인 전체를 paths 라인으로 교체
+  // paths-anchor: 경로가 '.'이 아니면 주석 라인 전체를 paths 라인으로 교체
   if (PATHS_ANCHOR_RE.test(out) && projectPath && projectPath !== ".") {
     const eol = out.includes("\r\n") ? "\r\n" : "\n";
     out = out.split(/\r?\n/).map((line) => {
@@ -134,7 +141,7 @@ export function substituteEnv(content, opts = {}) {
   return out;
 }
 
-// .sh _wf_is_unchanged 등가: 원본을 "기본값으로 가상 치환한 최종형"과 설치본을 바이트 비교.
+// unchanged 판정: 원본을 "기본값으로 가상 치환한 최종형"과 설치본을 바이트 비교.
 export function isUnchanged(templateContent, installedContent, opts = {}) {
   const virtual = substituteEnv(templateContent, { ...opts, useDefaults: true });
   return virtual === installedContent;

package/src/core/wizard-labels.js

@@ -1,7 +1,5 @@
-// wizard-prompts.yml 라벨 메타 파서 (.sh _wf_labels_path/_wf_read_field/wf_field/wf_workflow_name 등가).
-// 실측 기준: template_integrator.sh 2809~2814(_wf_labels_path), 2895~2932(wf_workflow_name),
-//           2934~2960(_wf_read_field), 2962~2970(wf_field).
-// ⚠️ YAML 라이브러리 금지 — .sh와 동일하게 라인 기반 파싱만 한다(외부 의존성 0 + 포맷 관용성 동일).
+// wizard-prompts.yml 라벨 메타 파서.
+// ⚠️ YAML 라이브러리 금지 — 라인 기반 파싱만 한다(외부 의존성 0, 형식이 조금 어긋난 사용자 파일도 읽힌다).
 import { join } from "node:path";
 import * as nodeFs from "node:fs";
 import { PAYLOAD } from "./paths.js";
@@ -9,7 +7,7 @@ import { PAYLOAD } from "./paths.js";
 // wizard-prompts.yml 위치 — 사용자 레포(커스텀 오버라이드용) 기준 상대경로
 export const LABELS_FILE = ".github/config/wizard-prompts.yml";
 
-// 따옴표 감싸진 값이면 벗기고 trim ("값" → 값). .sh sub(/^"/)/sub(/"$/) 등가.
+// 따옴표 감싸진 값이면 벗기고 trim ("값" → 값).
 function unquote(s) {
   const t = s.trim();
   if (t.startsWith('"') && t.endsWith('"') && t.length >= 2) return t.slice(1, -1);
@@ -19,7 +17,7 @@ function unquote(s) {
 // wizard-prompts.yml 텍스트 → 파싱 객체 (순수 함수 — 테스트 직접 사용 가능).
 // 반환: { fields: Map<조회키, {label?,help?,example?}>, workflowNames: [{key,value}] }
 //  - 조회키: "PROJECT_NAME" 또는 "flutter.APP_ARTIFACT_NAME" (dotted 타입 오버라이드)
-//  - 구형 1줄(KEY: "라벨")은 fields의 label로 흡수 (.sh _wf_read_field 형식1 등가 — label만 의미)
+//  - 구형 1줄(KEY: "라벨")은 fields의 label로 흡수 (label만 의미)
 export function parseWizardPrompts(text) {
   const fields = new Map();
   const workflowNames = [];
@@ -28,10 +26,10 @@ export function parseWizardPrompts(text) {
 
   for (const raw of String(text).split(/\r?\n/)) {
     const line = raw.replace(/\r$/, "");
-    if (!line.trim() || line.trim().startsWith("#")) continue; // 빈 줄·주석은 블록을 끊지 않음(.sh awk도 동일하게 무해)
+    if (!line.trim() || line.trim().startsWith("#")) continue; // 빈 줄·주석은 블록을 끊지 않음
 
     if (!/^\s/.test(line)) {
-      // 최상위 키 라인 — 이전 블록 종료 (.sh awk `/^[^[:space:]]/ { inblk=0 }` 등가)
+      // 최상위 키 라인 — 이전 블록 종료
       current = null; inWfNames = false;
       const m = line.match(/^([A-Za-z_][A-Za-z0-9_.\-]*):(.*)$/);
       if (!m) continue;
@@ -40,7 +38,7 @@ export function parseWizardPrompts(text) {
       if (key === "_workflow_names") { inWfNames = true; continue; }
       const entry = fields.get(key) || {};
       if (rest) {
-        // 구형 1줄: KEY: "라벨" (.sh 형식1 — label로만 사용)
+        // 구형 1줄: KEY: "라벨" (label로만 사용)
         const q = rest.match(/^"([^"]*)"\s*$/);
         if (q) entry.label = q[1];
       }
@@ -53,35 +51,46 @@ export function parseWizardPrompts(text) {
     const m = line.match(/^\s+([A-Za-z_][A-Za-z0-9_.\-]*):\s*(.*)$/);
     if (!m) continue;
     if (inWfNames) {
-      // "  KEY: "값"" 형식만 인정 (.sh _wf_load_workflow_names의 `*:\ \"*\"` case 등가)
+      // "  KEY: "값"" 형식만 인정
       const q = m[2].match(/^"(.*)"\s*$/);
       if (q) workflowNames.push({ key: m[1], value: q[1] });
       continue;
     }
     if (current && (m[1] === "label" || m[1] === "help" || m[1] === "example")) {
-      // 블록 내 첫 등장만 채택 (.sh awk `print line; exit` — 첫 매치 사용)
+      // 블록 내 첫 등장만 채택
       if (current[m[1]] == null) current[m[1]] = unquote(m[2]);
     }
   }
   return { fields, workflowNames };
 }
 
-// wizard-prompts.yml을 찾아 읽고 파싱 (.sh _wf_labels_path 등가).
-// 우선순위: 대상 프로젝트(targetRoot — 사용자 커스텀) → 패키지 payload/config 번들본 → null.
-// WHY 폴백: 사용자 레포에는 이 파일을 설치하지 않는다(payload 단일 진실) —
-//          번들본 폴백이 없으면 label/help/example이 전부 빈값(KEY명만 출력)이 된다.
+// wizard-prompts.yml을 찾아 읽고 파싱.
+// 번들본(payload/config)을 바탕으로 대상 프로젝트의 사용자 파일(커스텀 오버라이드)을 키 단위로 덮어쓴다.
+// WHY 병합: 사용자 파일에는 바꾸고 싶은 키만 적는 것이 자연스럽다 — 파일째 대체하면 적지 않은 나머지
+//          질문의 label/help/example과 워크플로우 표시명이 전부 사라져 KEY명만 보인다.
 // fs 주입 가능(테스트용) — 기본 node:fs.
 export function loadWizardPrompts(targetRoot = ".", payloadRoot = "", fs = nodeFs) {
-  // 우선순위: 대상 프로젝트(사용자 커스텀 오버라이드) → 패키지 payload/config 번들본 → null.
-  const candidates = [join(targetRoot, LABELS_FILE)];
-  if (payloadRoot) candidates.push(join(payloadRoot, PAYLOAD.configDir, "wizard-prompts.yml"));
-  for (const p of candidates) {
-    if (fs.existsSync(p)) return parseWizardPrompts(fs.readFileSync(p, "utf8"));
+  const read = (p) => (fs.existsSync(p) ? parseWizardPrompts(fs.readFileSync(p, "utf8")) : null);
+  const bundled = payloadRoot ? read(join(payloadRoot, PAYLOAD.configDir, "wizard-prompts.yml")) : null;
+  const user = read(join(targetRoot, LABELS_FILE));
+  if (!bundled || !user) return user || bundled;
+  return mergeWizardPrompts(bundled, user);
+}
+
+// 번들 + 사용자 파싱 결과 병합. 같은 키는 사용자가 적은 필드만 덮어쓴다(label만 바꾸면 help/example은 번들 유지).
+export function mergeWizardPrompts(base, override) {
+  const fields = new Map([...base.fields].map(([k, v]) => [k, { ...v }]));
+  for (const [key, entry] of override.fields) {
+    const merged = { ...(fields.get(key) || {}) };
+    for (const [f, v] of Object.entries(entry)) if (v != null && v !== "") merged[f] = v;
+    fields.set(key, merged);
   }
-  return null;
+  const overridden = new Set(override.workflowNames.map((w) => w.key));
+  const workflowNames = [...base.workflowNames.filter((w) => !overridden.has(w.key)), ...override.workflowNames];
+  return { fields, workflowNames };
 }
 
-// 필드 조회 (.sh wf_field 등가). field: "label" | "help" | "example".
+// 필드 조회. field: "label" | "help" | "example".
 // 우선순위: "{type}.KEY" 블록 → "KEY" 블록(구형 1줄 포함) → 폴백(label이면 KEY명, 아니면 "").
 export function wfField(prompts, type, key, field) {
   if (prompts && prompts.fields) {
@@ -93,11 +102,11 @@ export function wfField(prompts, type, key, field) {
   return field === "label" ? key : "";
 }
 
-// 워크플로우 파일명 → 사람이 읽는 짧은 이름 (.sh wf_workflow_name 등가).
+// 워크플로우 파일명 → 사람이 읽는 짧은 이름.
 // _workflow_names에서 "키가 파일명에 포함되면" 그 값 사용 — 최장 키 우선(REACT-CI vs REACT-CICD 구분).
-// 미매칭이면 .yaml/.yml 확장자만 제거해 반환 (.sh `${_base%.y*ml}` 등가).
+// 미매칭이면 .yaml/.yml 확장자만 제거해 반환.
 export function workflowDisplayName(prompts, filename) {
-  const base = String(filename).split("/").pop().split("\\").pop(); // 경로 제거 (.sh `${_file##*/}`)
+  const base = String(filename).split("/").pop().split("\\").pop(); // 경로 제거
   let best = null; let bestLen = 0;
   for (const { key, value } of prompts?.workflowNames ?? []) {
     if (base.includes(key) && key.length > bestLen) { best = value; bestLen = key.length; }