projectops 4.0.3 → 4.1.1

package/src/core/options-ask.js

@@ -0,0 +1,100 @@
+// 선택(opt-in) 워크플로우 포함 여부 질문 (.sh ask_optional_workflow L2651~2702 /
+// ask_all_optional_workflows L2708~2732 등가). Nexus publish + Secret 서버 백업.
+//
+// io 주입 계약(readline-engine 시그니처):
+//   io.confirm({message, initialValue}) → bool | CANCEL(symbol)
+//   io.log(line)                        → 안내 출력 (없으면 stderr)
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { listYamlFiles } from "./fsutil.js";
+import { PATHS } from "./paths.js";
+import { parseTemplateOptions } from "./version-yml.js";
+
+// 재노출 — 파서 본체는 version-yml.js에 있다 (순환 import 방지: options-ask → version-yml 방향만 허용)
+export { parseTemplateOptions };
+
+const isCancel = (v) => typeof v === "symbol";
+
+// 옵션 1종 질문 (.sh ask_optional_workflow 등가).
+// 반환: true/false/null(폴더 없음·파일 0개로 질문 자체 생략 → 현재값 유지).
+async function askOptionalWorkflow({ dir, icon, short, desc, current, force, tty, io, forceAsk, say }) {
+  // 폴더가 없거나 yaml이 0개면 조용히 건너뜀 (.sh L2664~2669) — 질문 자체가 성립 안 함
+  if (!existsSync(dir)) return current;
+  const files = listYamlFiles(dir);
+  if (files.length === 0) return current;
+
+  // 이미 값이 설정돼 있고 force-ask 아니면 유지 (CLI/version.yml 우선, .sh L2672~2674)
+  if (!forceAsk && (current === true || current === false)) return current;
+
+  // 비대화형(--force 또는 TTY 없음)이면 기본 제외 (.sh L2677~2679)
+  if (force || !tty) return false;
+
+  say("");
+  say(`${icon} ${short} 워크플로우를 발견했습니다. (${files.length}개 파일)`);
+  say(`   ${desc}`);
+  say("");
+  say("   포함되는 워크플로우:");
+  for (const f of files) say(`     • ${f}`);
+  say("");
+
+  const ans = await io.confirm({ message: `${short} 워크플로우를 포함할까요?`, initialValue: false });
+  // ESC(취소)는 '아니오'와 동일 취급 (.sh ask_yes_no 비-0 반환 등가)
+  const include = ans === true && !isCancel(ans);
+  say(include
+    ? `${short} 워크플로우를 포함합니다 — GitHub Actions에 추가됩니다`
+    : `${short} 워크플로우를 제외합니다 (나중에 옵션으로 추가 가능)`);
+  return include;
+}
+
+// 모든 opt-in 워크플로우를 순서대로 질문 (.sh ask_all_optional_workflows 등가).
+// tempDir: 템플릿 다운로드 루트 — project-types는 {tempDir}/.github/workflows/project-types
+//          (copyWorkflows와 동일 규약. 테스트 픽스처용으로 {tempDir}/project-types 도 허용.)
+// current: { nexus: bool|null, secretBackup: bool|null } — CLI(--nexus 등) 명시값
+// 반환: { nexus: bool, secretBackup: bool } (미결정 null은 false로 확정)
+export async function askAllOptionalWorkflows({
+  tempDir, types = [], current = {}, targetRoot = ".",
+  force = false, tty = true, io = {}, forceAsk = false,
+}) {
+  const say = io.log || ((m) => process.stderr.write(`${m}\n`));
+  let nexus = current.nexus ?? null;
+  let secretBackup = current.secretBackup ?? null;
+
+  // ① --force-ask가 아니면 version.yml 저장값을 먼저 읽어 재질문을 건너뛴다 (.sh L2715~2717).
+  //    CLI 명시값(current)이 이미 있으면 그쪽이 우선 — 저장값은 빈 자리만 채운다.
+  if (!forceAsk) {
+    const vy = join(targetRoot, PATHS.versionFile);
+    if (existsSync(vy)) {
+      const saved = parseTemplateOptions(readFileSync(vy, "utf8"));
+      if (nexus === null && saved.nexus !== null) {
+        nexus = saved.nexus;
+        say(`Nexus 옵션: version.yml 저장값(${nexus}) 유지 — 재질문 생략`);
+      }
+      if (secretBackup === null && saved.secretBackup !== null) {
+        secretBackup = saved.secretBackup;
+        say(`Secret 백업 옵션: version.yml 저장값(${secretBackup}) 유지 — 재질문 생략`);
+      }
+    }
+  }
+
+  // project-types 루트 결정 — 실제 temp 레이아웃 우선, 픽스처(직하위) 폴백
+  const real = join(tempDir, PATHS.workflowsDir, PATHS.projectTypesDir);
+  const ptDir = existsSync(real) ? real : join(tempDir, PATHS.projectTypesDir);
+
+  // ② Nexus: 각 타입의 nexus/ 폴더 (현재 spring만 존재, .sh L2719~2725)
+  for (const t of types) {
+    nexus = await askOptionalWorkflow({
+      dir: join(ptDir, t, "nexus"), icon: "📦", short: "Nexus 라이브러리 publish",
+      desc: "라이브러리/모듈을 Maven 저장소(Nexus)에 배포하는 워크플로우입니다. 일반 서버 배포가 아니라 라이브러리 프로젝트에만 필요합니다.",
+      current: nexus, force, tty, io, forceAsk, say,
+    });
+  }
+  // ③ Secret 백업: 공통 폴더 (.sh L2726~2729)
+  secretBackup = await askOptionalWorkflow({
+    dir: join(ptDir, "common", "secret-backup"), icon: "🔐", short: "Secret 서버 백업",
+    desc: "GitHub Secret에 저장한 설정 파일을 SSH로 서버에 업로드·이력관리하는 워크플로우입니다.",
+    current: secretBackup, force, tty, io, forceAsk, say,
+  });
+
+  // ④ 미결정(null)은 false로 확정 — .sh에서 빈 INCLUDE_* 가 이후 false 취급되는 것과 동일
+  return { nexus: nexus === true, secretBackup: secretBackup === true };
+}

package/src/core/paths-resolve.js

@@ -0,0 +1,261 @@
+// 타입별 프로젝트 경로 감지·확정 (.sh find_type_path_candidates L1249~1311 /
+// resolve_project_paths L1362~1589 등가). 모노레포에서 각 타입의 버전 파일이
+// 어느 폴더에 있는지 5단계 우선순위로 확정한다.
+//
+// io 주입 계약(readline-engine 시그니처 그대로):
+//   io.select({message, options:[{value,label}]}) → value | CANCEL(symbol)
+//   io.text({message, defaultValue})              → string | CANCEL
+//   io.confirm({message, initialValue})           → bool | CANCEL
+//   io.log(line)                                   → 안내 출력 (없으면 stderr)
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { markerForType as baseMarkerForType, extraMarkers } from "./detect.js";
+import { normalizePath } from "../cli/args.js";
+
+// 취소(ESC/Ctrl+C)는 CANCEL 심볼 — ui를 import하지 않고 심볼 여부로만 판정 (core→ui 역참조 방지)
+const isCancel = (v) => typeof v === "symbol";
+
+// 타입의 대표 마커 파일명 (.sh marker_for_type L1220~1229 등가).
+// detect.js는 미지 타입에 package.json을 기본 반환하지만 .sh는 빈 문자열 — 등가를 위해 래핑.
+const KNOWN_MARKER_TYPES = new Set([
+  "flutter", "react", "node", "react-native", "react-native-expo", "python", "spring",
+]);
+export function markerForType(type) {
+  return KNOWN_MARKER_TYPES.has(type) ? baseMarkerForType(type) : "";
+}
+
+// 디렉토리에 실재하는 마커 파일명 반환 — 보조 마커 포함, 없으면 대표 마커 (표시용).
+// (.sh existing_marker_in_dir L1232~1245: spring build.gradle/.kts/pom.xml, python pyproject/setup.py/requirements.txt)
+export function existingMarkerInDir(type, dir) {
+  const primary = markerForType(type);
+  const names = primary ? [primary, ...extraMarkers(type)] : [];
+  for (const n of names) {
+    if (existsSync(join(dir, n))) return n;
+  }
+  return primary;
+}
+
+// maxdepth 3 재귀 파일 탐색 — 매치 파일의 "디렉토리" 상대경로(루트는 ".")를 수집.
+// find의 maxdepth는 파일 경로 컴포넌트 수 기준(./a/b/f = depth 3)이므로 동일하게 계산.
+function walkFindDirs(root, { prune, match, maxDepth = 3 }) {
+  const hits = [];
+  const walk = (rel, depth) => {
+    let entries;
+    try { entries = readdirSync(join(root, rel || "."), { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const childDepth = depth + 1;
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        // prune 폴더는 하위 전체 제외 (.sh find -prune 등가)
+        if (prune.has(e.name)) continue;
+        // 자식 파일이 depth ≤ maxDepth 안에 들어올 때만 하강
+        if (childDepth < maxDepth) walk(childRel, childDepth);
+        // childDepth === maxDepth-0 인 디렉토리 내부 파일은 depth maxDepth+1 → find가 안 봄
+        else if (childDepth === maxDepth) { /* 파일만 maxDepth까지 — 디렉토리 하강 불필요 */ }
+      } else if (childDepth <= maxDepth && match(e.name)) {
+        hits.push(rel === "" ? "." : rel);
+      }
+    }
+  };
+  walk("", 0);
+  return [...new Set(hits)].sort(); // sort -u 등가
+}
+
+// 타입별 마커 파일 후보 검색 (.sh find_type_path_candidates L1249~1311 등가).
+// 반환: 후보 디렉토리 상대경로 배열 (루트는 ".").
+export function findTypePathCandidates(root, type) {
+  // ── Spring 멀티모듈: settings.gradle(.kts) 폴더 = 모듈 루트로 축약 (.sh L1255~1268) ──
+  // version_manager가 그 폴더 아래 build.gradle 전부를 갱신하므로 하위 모듈을 펼치지 않는다.
+  // android/ 의 settings.gradle(Flutter/RN)은 spring이 아니므로 prune.
+  if (type === "spring") {
+    const mm = walkFindDirs(root, {
+      prune: new Set(["node_modules", ".git", "build", "dist", ".gradle", "android", "ios"]),
+      match: (n) => n === "settings.gradle" || n === "settings.gradle.kts",
+    });
+    if (mm.length) return mm;
+    // settings.gradle 없음 → 단일 모듈, 아래 build.gradle 폴백
+  }
+
+  const namesByType = {
+    flutter: ["pubspec.yaml"],
+    react: ["package.json"], node: ["package.json"],
+    "react-native": ["package.json"],
+    "react-native-expo": ["app.json"],
+    python: ["pyproject.toml", "setup.py", "requirements.txt"],
+    spring: ["build.gradle", "build.gradle.kts", "pom.xml"],
+  };
+  const names = namesByType[type];
+  if (!names) return [];
+
+  const prune = new Set([
+    "node_modules", ".git", "build", "dist", ".dart_tool", "android", "ios",
+    ".gradle", "venv", ".venv", "__pycache__",
+  ]);
+  // 우선순위 높은 마커에서 발견되면 그것만 사용 (.sh L1281~1288)
+  let found = [];
+  for (const n of names) {
+    found = walkFindDirs(root, { prune, match: (name) => name === n });
+    if (found.length) break;
+  }
+
+  return found.filter((d) => {
+    if (type === "flutter") {
+      // example/ 제외 + lib/ 동반 확인 — 오탐 방지 (.sh L1298~1303)
+      if (d.includes("example")) return false;
+      const libDir = d === "." ? join(root, "lib") : join(root, d, "lib");
+      if (!existsSync(libDir)) return false;
+    }
+    if (type === "spring") {
+      // Flutter/RN의 android/build.gradle 오탐 제외 (.sh L1304~1307)
+      if (d.includes("android")) return false;
+    }
+    return true;
+  });
+}
+
+// 선택된 모든 타입의 경로를 감지·확인하여 Map<type,path> 확정
+// (.sh resolve_project_paths L1362~1589 등가 — 5단계 우선순위).
+//   ① paths에 이미 있음(--paths) → 유지
+//   ② 루트에 마커 존재 → "." 자동
+//   ③ existingPaths(version.yml 저장값)
+//   ④ 후보 스캔
+//   ⑤ 분기 — 비대화형: 기존값→후보1개→루트 폴백 / 대화형: 확인·선택·직접입력
+export async function resolveProjectPaths({
+  root, types = [], paths = new Map(), existingPaths = new Map(),
+  force = false, tty = true, io = {},
+}) {
+  const say = io.log || ((m) => process.stderr.write(`${m}\n`));
+  const result = new Map(paths); // --paths 사전값 유지 (호출부 Map은 불변)
+  const targets = types.filter((t) => t !== "basic"); // basic은 경로 불필요 (.sh L1400)
+  if (targets.length === 0) return result;
+
+  const total = targets.length;
+  // ── 도입부 안내 (.sh L1407~1434 — 감지 결과 + 무엇을 할지 설명) ──
+  say("");
+  if (total > 1) say(`🔍 멀티타입 프로젝트가 감지되었습니다 — 총 ${total}개 타입`);
+  else say(`🔍 ${targets[0]} 프로젝트가 감지되었습니다 — 총 1개 타입`);
+  for (const t of targets) say(`   • ${t.padEnd(8)} → ${existingMarkerInDir(t, root)}`);
+  say("");
+  say("💡 '프로젝트 루트' = 그 타입의 버전 파일이 있는 폴더 (레포 루트 기준 상대경로)");
+  say("");
+
+  let idx = 0;
+  for (const t of targets) {
+    idx += 1;
+    const prog = `[${idx}/${total}]`;
+
+    // ① --paths 등으로 이미 지정됨 → 최우선 (.sh L1441~1446)
+    if (result.get(t)) {
+      say(`  ${t} → ${result.get(t)} (--paths 지정)`);
+      continue;
+    }
+
+    // ② 루트에 마커 존재 → "." 자동 확정 (.sh L1449~1455, 보조 마커 포함)
+    const rootMarker = existingMarkerInDir(t, root);
+    if (rootMarker && existsSync(join(root, rootMarker))) {
+      result.set(t, ".");
+      say(`  ${t} → . (루트의 ${rootMarker})`);
+      continue;
+    }
+
+    // ③ 기존 version.yml 저장값 → 기본 제안값 (.sh L1458~1466)
+    const existing = existingPaths.get(t) || "";
+
+    // ④ 후보 검색 (.sh L1469~1471)
+    const candidates = findTypePathCandidates(root, t);
+    let chosen = "";
+
+    // ── ⑤-a 비대화형 (--force 또는 TTY 없음, .sh L1476~1489) ──
+    if (force || !tty) {
+      if (existing) {
+        chosen = existing;
+        say(`  ${t} → ${chosen} (기존 project_paths 유지)`);
+      } else if (candidates.length === 1) {
+        chosen = candidates[0];
+        say(`  ${t} → ${chosen} (자동 감지)`);
+      } else {
+        chosen = ".";
+        say(`  ⚠️ ${t} → 후보 ${candidates.length}개로 자동 확정 불가, 루트(.)로 기록 (--paths "${t}=경로"로 지정 가능)`);
+      }
+      result.set(t, chosen);
+      continue;
+    }
+
+    // ── ⑤-b 대화형: 후보 개수별 분기 (.sh L1492~1525) ──
+    if (candidates.length === 1) {
+      const cand = candidates[0];
+      const candMarker = existingMarkerInDir(t, cand === "." ? root : join(root, cand));
+      const candFull = cand === "." ? candMarker : `${cand}/${candMarker}`;
+      say("");
+      say(`  ${prog} 🔍 ${t} — ${candMarker} 발견`);
+      say(`      위치: <레포루트>/${candFull}`);
+      // '아니오'/취소 시 chosen 미설정 → 아래 직접입력 루프로
+      const ok = await io.confirm({
+        message: `  ${t} 프로젝트 루트를 '${cand}'(으)로 설정할까요? (${candFull} 기준 — 아니오 선택 시 직접 입력)`,
+        initialValue: true,
+      });
+      if (ok === true) chosen = cand;
+    } else if (candidates.length > 1) {
+      say("");
+      say(`  ${prog} 🔍 ${t}: 경로 후보 ${candidates.length}개 발견`);
+      // 후보들 + '직접 입력' 메뉴 — value 자체를 한국어로 (센티넬 노출 방지, .sh L1508~1521)
+      const options = candidates.map((c) => ({
+        value: c,
+        label: `${c} (${existingMarkerInDir(t, c === "." ? root : join(root, c))})`,
+      }));
+      options.push({ value: "직접 입력", label: "직접 입력" });
+      const sel = await io.select({ message: `  ${t} 프로젝트 루트를 선택하세요`, options });
+      // ESC(취소)도 직접 입력으로 폴백 (.sh `|| _sel="직접 입력"`)
+      if (!isCancel(sel) && sel != null && sel !== "직접 입력") chosen = sel;
+    } else {
+      say("");
+      say(`  ⚠️ ${prog} ${t}: 프로젝트를 찾지 못했습니다 (maxdepth 3).`);
+    }
+
+    // ── 직접 입력 루프 (위에서 미확정 시, .sh L1528~1553) ──
+    while (!chosen) {
+      const hintMarker = existingMarkerInDir(t, root);
+      let prompt = `  ${t} 프로젝트 루트 경로 입력 (${hintMarker} 이 있는 폴더, 예: server, app — 루트면 그냥 Enter`;
+      if (existing) prompt += `, 현재값: ${existing}`;
+      prompt += "): ";
+      let input = await io.text({ message: prompt, defaultValue: "" });
+      if (isCancel(input) || input == null) input = ""; // ESC → 빈값 (아래 폴백)
+      input = String(input).trim();
+      // 빈값 → 기존값 또는 루트 (.sh L1541~1543) — normalizePath 전에 판정
+      input = input === "" ? (existing || ".") : normalizePath(input);
+      // 검증: 입력 경로에 마커 존재 확인 (보조 마커 포함, .sh L1544~1552)
+      const m = existingMarkerInDir(t, input === "." ? root : join(root, input));
+      if (m && existsSync(join(root, input === "." ? "" : input, m))) {
+        chosen = input;
+      } else {
+        say(`  ⚠️ ${input}/${m} 파일이 없습니다.`);
+        const forceOk = await io.confirm({ message: "  그래도 이 경로를 사용할까요?", initialValue: false });
+        if (forceOk === true) chosen = input;
+      }
+    }
+
+    result.set(t, chosen);
+    say(`  ✅ ${t} → ${chosen}`);
+  }
+
+  // ── 요약 + 같은 마커 파일 중복 경고 (.sh L1559~1587) ──
+  say("");
+  say("📂 타입별 버전 파일 경로 확정:");
+  const fileToTypes = new Map(); // 마커 파일 상대경로 → 그 파일을 쓰는 타입들
+  for (const [pt, pp] of result) {
+    const m = existingMarkerInDir(pt, pp === "." ? root : join(root, pp));
+    const file = pp === "." ? m : `${pp}/${m}`;
+    say(`   ${pt} → ${file}`);
+    if (!fileToTypes.has(file)) fileToTypes.set(file, []);
+    fileToTypes.get(file).push(pt);
+  }
+  for (const [file, ts] of fileToTypes) {
+    if (ts.length > 1) {
+      // 멱등 동작이라 막지는 않고 경고만 (.sh L1577~1586)
+      say(`  ⚠️ 같은 파일(${file})을 여러 타입(${ts.join(" ")})이 바라봅니다.`);
+      say("     → sync 때 모두 같은 버전이 기록됩니다. 동작에는 문제없지만 의도한 구성인지 확인하세요.");
+    }
+  }
+  say("");
+  return result;
+}

package/src/core/version-yml.js

@@ -12,7 +12,7 @@ const HEADER = `# ==============================================================
 # 사용법:
 # 1. version: "1.0.0" - 사용자에게 표시되는 버전
 # 2. version_code: 1 - Play Store/App Store 빌드 번호 (1부터 자동 증가)
-# 3. project_type: 프로젝트 타입 지정
+# 3. project_types: 프로젝트 타입 배열 — 첫 항목이 primary
 # 4. project_paths: 타입별 프로젝트 폴더 (레포 루트 기준 상대경로, 모노레포용)
 #
 # 자동 버전 업데이트:
@@ -35,11 +35,48 @@ const HEADER = `# ==============================================================
 # - .github/workflows/PROJECT-AUTO-CHANGELOG-CONTROL.yaml
 #
 # 주의사항:
-# - project_type은 최초 설정 후 변경하지 마세요
+# - project_types는 최초 설정 후 변경하지 마세요
 # - 버전은 항상 높은 버전으로 자동 동기화됩니다
 # ===================================================================
 `;
 
+// metadata.template.options 상태머신 파싱 (.sh read_template_options L2361~2416 등가).
+// 반환: { nexus: bool|null, secretBackup: bool|null } — null=미기재.
+// 구 synology 키 등 다른 키는 어느 분기에도 안 걸려 자연히 무시된다.
+// (options-ask.js가 이 함수를 import한다 — 순환 방지 위해 여기(version-yml)에 정의.)
+export function parseTemplateOptions(content) {
+  const out = { nexus: null, secretBackup: null };
+  // 값 정규화: 따옴표 제거 + 트림 (.sh tr -d '"' | tr -d "'" | xargs 등가)
+  const strip = (s) => String(s).replace(/["']/g, "").trim();
+  let inTemplate = false;
+  let inOptions = false;
+  for (const line of String(content || "").split("\n")) {
+    if (/^\s*template:/.test(line)) { inTemplate = true; continue; }
+    if (inTemplate && /^\s+options:/.test(line)) { inOptions = true; continue; }
+    if (inTemplate && inOptions) {
+      let m = line.match(/^\s+nexus:\s*(.+)/);
+      if (m) {
+        const v = strip(m[1]);
+        if (v === "true") out.nexus = true;
+        if (v === "false") out.nexus = false;
+        continue;
+      }
+      m = line.match(/^\s+secret_backup:\s*(.+)/);
+      if (m) {
+        const v = strip(m[1]);
+        if (v === "true") out.secretBackup = true;
+        if (v === "false") out.secretBackup = false;
+        continue;
+      }
+      // 들여쓰기 0~4칸의 다른 키 → options 섹션 종료 (.sh L2404~2408)
+      if (/^\s{0,4}[a-z_]+:/.test(line)) { inOptions = false; inTemplate = false; }
+    }
+    // 최상위 키 → template 섹션 종료 (.sh L2411~2415)
+    if (inTemplate && /^[a-z_]+:/.test(line)) { inTemplate = false; inOptions = false; }
+  }
+  return out;
+}
+
 // 기존 version.yml에서 값 추출 (.sh grep/sed 등가, 주석 라인 오탐 방지).
 export function parseExisting(content) {
   const text = String(content || "");
@@ -82,24 +119,25 @@ export function parseExisting(content) {
       if (/^\S/.test(l)) break;
     }
   }
-  return { version, versionCode, types, paths, templateVersion };
+  // 선택 워크플로우 옵션 (metadata.template.options — nexus/secret_backup)
+  const options = parseTemplateOptions(text);
+  return { version, versionCode, types, paths, templateVersion, options };
 }
 
 // version.yml 전체 생성 (.sh create_version_yml + save_template_options 신규 케이스 등가).
-// opts: { version, types:[], primaryType?, paths:Map, pathMarkers?:Map, branch, versionCode, now, today, templateOptions? }
+// opts: { version, types:[], paths:Map, pathMarkers?:Map, branch, versionCode, now, today, templateOptions? }
+// primary 타입은 별도 키 없이 project_types[0]이다 (v4.1.0 SSOT — 단수 project_type 키 제거).
 //   now   = "YYYY-MM-DD HH:MM:SS" (UTC) — 결정성 위해 주입
 //   today = "YYYY-MM-DD" (UTC)
 //   pathMarkers = Map<type, markerFilename> (project_paths 주석용)
 //   templateOptions = { templateVersion, includeNexus, includeSecretBackup, optionsDate } (template 블록)
-export function buildVersionYml({ version, types = [], primaryType, paths = new Map(), pathMarkers = new Map(), branch = "main", versionCode = 1, now, today, templateOptions = null, deployValues = new Map() }) {
+export function buildVersionYml({ version, types = [], paths = new Map(), pathMarkers = new Map(), branch = "main", versionCode = 1, now, today, templateOptions = null, deployValues = new Map() }) {
   const typesJson = types.length ? `[${types.map((t) => `"${t}"`).join(",")}]` : `["basic"]`;
-  const primary = primaryType || types[0] || "basic";
 
   let out = HEADER + "\n";
   out += `version: "${version}"\n`;
   out += `version_code: ${versionCode}  # app build number\n`;
   out += `project_types: ${typesJson}   # 멀티타입 배열 — 첫 항목이 primary, 직접 편집 가능\n`;
-  out += `project_type: "${primary}"  # project_types[0] 자동 미러 — 직접 수정 금지 (spring, flutter, next, react, react-native, react-native-expo, node, python, basic)\n`;
 
   // project_paths 블록. pathMarkers: Map<type, markerFilename> (있으면 "  type: "path"   # path/marker" 주석).
   if (paths.size) {

package/src/core/wizard-labels.js

@@ -0,0 +1,106 @@
+// 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 + 포맷 관용성 동일).
+import { join } from "node:path";
+import * as nodeFs from "node:fs";
+import { PATHS } from "./paths.js";
+
+// wizard-prompts.yml 위치 (레포 루트 기준 상대경로 — .sh LABELS_FILE 상수)
+export const LABELS_FILE = ".github/config/wizard-prompts.yml";
+
+// 따옴표 감싸진 값이면 벗기고 trim ("값" → 값). .sh sub(/^"/)/sub(/"$/) 등가.
+function unquote(s) {
+  const t = s.trim();
+  if (t.startsWith('"') && t.endsWith('"') && t.length >= 2) return t.slice(1, -1);
+  return t;
+}
+
+// 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만 의미)
+export function parseWizardPrompts(text) {
+  const fields = new Map();
+  const workflowNames = [];
+  let current = null;       // 현재 블록의 fields 엔트리 (들여쓰기 라인 소속처)
+  let inWfNames = false;    // _workflow_names 블록 내부 여부
+
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.replace(/\r$/, "");
+    if (!line.trim() || line.trim().startsWith("#")) continue; // 빈 줄·주석은 블록을 끊지 않음(.sh awk도 동일하게 무해)
+
+    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;
+      const key = m[1];
+      const rest = m[2].trim();
+      if (key === "_workflow_names") { inWfNames = true; continue; }
+      const entry = fields.get(key) || {};
+      if (rest) {
+        // 구형 1줄: KEY: "라벨" (.sh 형식1 — label로만 사용)
+        const q = rest.match(/^"([^"]*)"\s*$/);
+        if (q) entry.label = q[1];
+      }
+      fields.set(key, entry);
+      current = entry;
+      continue;
+    }
+
+    // 들여쓰기 라인 — 현재 블록 소속
+    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 등가)
+      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) → 다운로드 원본(tempDir) 폴백 → null.
+// WHY 폴백: 신규 통합에서는 copy_config_folder가 configure_workflow_env보다 늦게 실행되어
+//          대상에 아직 파일이 없다 — 폴백 없으면 label/help/example이 전부 빈값(KEY명만 출력)이 된다.
+// fs 주입 가능(테스트용) — 기본 node:fs.
+export function loadWizardPrompts(targetRoot = ".", tempDir = "", fs = nodeFs) {
+  const candidates = [join(targetRoot, LABELS_FILE)];
+  if (tempDir) candidates.push(join(tempDir, LABELS_FILE));
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return parseWizardPrompts(fs.readFileSync(p, "utf8"));
+  }
+  return null;
+}
+
+// 필드 조회 (.sh wf_field 등가). field: "label" | "help" | "example".
+// 우선순위: "{type}.KEY" 블록 → "KEY" 블록(구형 1줄 포함) → 폴백(label이면 KEY명, 아니면 "").
+export function wfField(prompts, type, key, field) {
+  if (prompts && prompts.fields) {
+    for (const q of [`${type}.${key}`, key]) {
+      const v = prompts.fields.get(q)?.[field];
+      if (v != null && v !== "") return v;
+    }
+  }
+  return field === "label" ? key : "";
+}
+
+// 워크플로우 파일명 → 사람이 읽는 짧은 이름 (.sh wf_workflow_name 등가).
+// _workflow_names에서 "키가 파일명에 포함되면" 그 값 사용 — 최장 키 우선(REACT-CI vs REACT-CICD 구분).
+// 미매칭이면 .yaml/.yml 확장자만 제거해 반환 (.sh `${_base%.y*ml}` 등가).
+export function workflowDisplayName(prompts, filename) {
+  const base = String(filename).split("/").pop().split("\\").pop(); // 경로 제거 (.sh `${_file##*/}`)
+  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; }
+  }
+  if (best != null) return best;
+  return base.replace(/\.ya?ml$/, "");
+}

package/src/index.js

@@ -2,14 +2,19 @@
 // 감지 → 다운로드 → 모드 라우팅 → 통합 실행 → 정리. 비대화형(--force) 우선.
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { parseArgs, parsePathsCsv, CliError } from "./cli/args.js";
 import { HELP_TEXT } from "./cli/help.js";
 import { createContext } from "./context.js";
 import { PATHS } from "./core/paths.js";
 import { remove } from "./core/fsutil.js";
 import { acquireTemplate, readTemplateVersion } from "./core/assets.js";
-import { detectTypes, detectVersion, detectDefaultBranch, detectRepoName } from "./core/detect-fs.js";
+import { detectTypes, detectVersion, detectDefaultBranch, detectRepoName, makeResolvers } from "./core/detect-fs.js";
+import { parseExisting } from "./core/version-yml.js";
+import { runBreakingCheck } from "./core/breaking-check.js";
+import { resolveProjectPaths } from "./core/paths-resolve.js";
+import { printBannerCompact } from "./ui/banner.js";
+import { printSummary } from "./ui/summary.js";
 import { runFull } from "./commands/full.js";
 import { runVersion } from "./commands/version.js";
 import { runWorkflows } from "./commands/workflows.js";
@@ -77,40 +82,55 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
     return 1;
   }
 
+  // 기존 version.yml 로드 — version/version_code/project_paths 보존의 단일 진실 (.sh L2208~2239 SSoT)
+  const vyPath = join(cwd, "version.yml");
+  const existing = existsSync(vyPath) ? parseExisting(readFileSync(vyPath, "utf8")) : null;
+
   // 감지 (CLI 인자 우선, 없으면 자동 감지 — version.yml 우선 규칙은 detectTypes/detectVersion 내부)
   const types = opts.types.length ? opts.types : detectTypes(cwd);
-  const version = opts.version || detectVersion(cwd);
+  // version: 기존 version.yml 최우선(SSoT — 재실행 시 덮어쓰기 방지) → CLI 지정 → 파일 감지
+  const version = (existing?.version) || opts.version || detectVersion(cwd);
+  const versionCode = existing?.versionCode ?? 1; // 기존 빌드번호 보존 (.sh L2208~2221)
   const branch = detectDefaultBranch(cwd);
   const repoName = detectRepoName(cwd);
-  const paths = parsePathsCsv(opts.pathsCsv);
-  // paths 미지정 타입은 루트(".") — basic 제외
-  for (const t of types) if (t !== "basic" && !paths.has(t)) paths.set(t, ".");
+  // 경로 확정 (.sh resolve_project_paths 비대화형 경로 — --paths 우선 → 저장값 → 후보 1개 자동 → 루트 폴백)
+  const paths = await resolveProjectPaths({
+    root: cwd, types, paths: parsePathsCsv(opts.pathsCsv),
+    existingPaths: existing?.paths ?? new Map(), force: true, tty: false, io: {},
+  });
 
   const { now, today } = clock || utcNow();
   const tempDir = join(cwd, PATHS.tempDir);
 
   const context = createContext({
-    mode: opts.mode, force: true, types, version, branch,
-    paths, includeNexus: opts.includeNexus === true, includeSecretBackup: opts.includeSecretBackup === true,
+    mode: opts.mode, force: true, types, version, versionCode, branch,
+    paths,
+    // 옵션 워크플로우: CLI 플래그 최우선 → version.yml 저장 옵션(.sh read_template_options 등가) → false
+    includeNexus: opts.includeNexus ?? existing?.options?.nexus ?? false,
+    includeSecretBackup: opts.includeSecretBackup ?? existing?.options?.secretBackup ?? false,
     repoName,
-    resolvers: {
-      repo: () => repoName,
-      "spring-app-yml-dir": () => "",
-      "spring-app-yml-path": () => "",
-      "flutter-root": () => paths.get("flutter") || ".",
-    },
+    // 실 resolver 4종 (.sh resolve_token 등가 — spring-app-yml 스텁 제거)
+    resolvers: makeResolvers(cwd, repoName, paths),
     now, today,
   });
 
+  let result = null;
   try {
     acquireTemplate({ tempDir, source });
     context.templateVersion = readTemplateVersion(tempDir);
 
+    // 비대화형 축약 배너 (#446 확정 — 1줄, 로그 오염 최소)
+    printBannerCompact({ version: context.templateVersion, mode: opts.mode });
+
+    // Breaking Changes 게이트 (.sh execute_integration L4415~4420 등가 — 비대화형은 경고 후 진행)
+    const proceed = await runBreakingCheck({ cwd, tempDir, templateVersion: context.templateVersion });
+    if (!proceed) return 0;
+
     switch (opts.mode) {
-      case "full": runFull(context, tempDir, cwd); break;
-      case "version": runVersion(context, tempDir, cwd); break;
-      case "workflows": runWorkflows(context, tempDir, cwd); break;
-      case "issues": runIssues(context, tempDir, cwd); break;
+      case "full": result = runFull(context, tempDir, cwd); break;
+      case "version": result = runVersion(context, tempDir, cwd); break;
+      case "workflows": result = runWorkflows(context, tempDir, cwd); break;
+      case "issues": result = runIssues(context, tempDir, cwd); break;
       default:
         // 알 수 없는 모드 → .sh와 동일하게 복사 0건, 에러 아님
         break;
@@ -118,5 +138,11 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
   } finally {
     remove(tempDir);
   }
+
+  // 완료 요약 (.sh print_summary — CLI 모드에서도 출력)
+  printSummary({
+    mode: opts.mode, types, version,
+    counters: { workflows: result?.workflows?.copied ?? 0, utilModules: 0 },
+  }, cwd);
   return 0;
 }