project-auto-wizard 0.1.5

package/src/core/options-ask.js

@@ -0,0 +1,99 @@
+// 선택(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, PAYLOAD } 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 등가).
+// payloadRoot: 패키지 payload/ 루트 — 타입 폴더는 {payloadRoot}/workflows/<type>
+//              (copyWorkflows와 동일 규약)
+// current: { nexus: bool|null, secretBackup: bool|null } — CLI(--nexus 등) 명시값
+// 반환: { nexus: bool, secretBackup: bool } (미결정 null은 false로 확정)
+export async function askAllOptionalWorkflows({
+  payloadRoot, 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}) 유지 — 재질문 생략`);
+      }
+    }
+  }
+
+  // 타입 폴더 루트 — payload/workflows (copyWorkflows와 동일 규약)
+  const ptDir = join(payloadRoot, PAYLOAD.workflowsDir);
+
+  // ② 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", "next", "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"], next: ["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/paths.js

@@ -0,0 +1,16 @@
+// 경로 상수 — 설치 대상(사용자 레포) 경로 + payload 내부 레이아웃.
+export const PATHS = {
+  versionFile: "version.yml",
+  workflowsDir: ".github/workflows",
+  scriptsDir: ".github/scripts",
+};
+
+// payload/ 내부 레이아웃 (payload 단일 진실 — DESIGN-SPEC §3)
+export const PAYLOAD = {
+  workflowsDir: "workflows",   // payload/workflows/{common,spring,flutter,...}
+  scriptsDir: "scripts",       // payload/scripts/*.py
+  configDir: "config",         // payload/config/wizard-prompts.yml 등 (마법사 런타임용)
+};
+
+export const WORKFLOW_PREFIX = "PROJECT";
+export const WORKFLOW_COMMON_PREFIX = "PROJECT-COMMON";

package/src/core/version-yml.js

@@ -0,0 +1,190 @@
+// version.yml 파싱·생성 (.sh create_version_yml 등가, 전체 재생성 전략 D4).
+// ⚠️ YAML 재직렬화 금지 — 주석이 데이터.
+// 레이아웃 단일 진실 = payload/version.yml.template (호출부가 templateText로 주입).
+
+// 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, coderabbit: 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;
+      }
+      m = line.match(/^\s+coderabbit:\s*(.+)/);
+      if (m) {
+        const v = strip(m[1]);
+        if (v === "true") out.coderabbit = true;
+        if (v === "false") out.coderabbit = 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 || "");
+  const line = (re) => {
+    for (const l of text.split("\n")) {
+      if (l.startsWith("#")) continue; // 주석 제외
+      const m = l.match(re);
+      if (m) return m[1];
+    }
+    return null;
+  };
+  // version: "x.y.z" (숫자.숫자.숫자 형태만)
+  const version = line(/^version:\s*["']?([0-9][0-9.]*)["']?/) || "";
+  // version_code: N (양의 정수, 아니면 1)
+  let versionCode = parseInt(line(/^version_code:\s*([0-9]+)/) || "", 10);
+  if (!Number.isInteger(versionCode) || versionCode <= 0) versionCode = 1;
+  // project_types: ["a","b"]
+  const typesRaw = line(/^project_types:\s*(\[[^\]]*\])/);
+  let types = [];
+  if (typesRaw) types = [...typesRaw.matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+  // project_paths 블록: "  type: "path""
+  const paths = new Map();
+  let inPaths = false;
+  for (const l of text.split("\n")) {
+    if (/^project_paths:/.test(l)) { inPaths = true; continue; }
+    if (inPaths) {
+      const m = l.match(/^\s+([a-z-]+):\s*"([^"]*)"/);
+      if (m) paths.set(m[1], m[2]);
+      else if (/^\S/.test(l)) inPaths = false; // 들여쓰기 끝 → 블록 종료
+    }
+  }
+  // template: 블록 내 version
+  let templateVersion = "";
+  let inTemplate = false;
+  for (const l of text.split("\n")) {
+    if (/^\s*template:/.test(l)) { inTemplate = true; continue; }
+    if (inTemplate) {
+      const m = l.match(/^\s*version:\s*"([0-9][0-9.]*)"/);
+      if (m) { templateVersion = m[1]; break; }
+      if (/^\S/.test(l)) break;
+    }
+  }
+  // 선택 워크플로우 옵션 (metadata.template.options — nexus/secret_backup)
+  const options = parseTemplateOptions(text);
+  // metadata.template.branches — main/develop/mode (업데이트 모드 재질문 생략용)
+  const branches = parseTemplateBranches(text);
+  return { version, versionCode, types, paths, templateVersion, options, branches };
+}
+
+// metadata.template.branches 블록 파싱. 셋 다 있어야 유효 — 아니면 null.
+export function parseTemplateBranches(content) {
+  const strip = (s) => String(s).replace(/["']/g, "").trim();
+  let inTemplate = false;
+  let inBranches = false;
+  const out = { main: "", develop: "", mode: "" };
+  for (const line of String(content || "").split("\n")) {
+    if (/^\s*template:/.test(line)) { inTemplate = true; continue; }
+    if (inTemplate && /^\s+branches:/.test(line)) { inBranches = true; continue; }
+    if (inTemplate && inBranches) {
+      let m = line.match(/^\s+main:\s*(.+)/);
+      if (m) { out.main = strip(m[1]); continue; }
+      m = line.match(/^\s+develop:\s*(.+)/);
+      if (m) { out.develop = strip(m[1]); continue; }
+      m = line.match(/^\s+mode:\s*(.+)/);
+      if (m) { out.mode = strip(m[1].split("#")[0]); continue; }
+      if (/^\s{0,4}[a-z_]+:/.test(line)) { inBranches = false; }
+    }
+    if (inTemplate && /^[a-z_]+:/.test(line)) { inTemplate = false; inBranches = false; }
+  }
+  return out.main && out.develop && out.mode ? out : null;
+}
+
+// version.yml 전체 생성 — payload/version.yml.template 렌더링.
+// opts: { templateText, version, types:[], primaryType?, paths:Map, pathMarkers?:Map,
+//         branch, branches?, versionCode, now, today, templateOptions?, deployValues? }
+//   templateText = payload/version.yml.template 원문 (readVersionYmlTemplate — 필수)
+//   now   = "YYYY-MM-DD HH:MM:SS" (UTC) — 결정성 위해 주입 / today = "YYYY-MM-DD"
+//   branches = { main, develop, mode } (resolveBranchConfig 결과. 없으면 branch 기반 기본값)
+//   pathMarkers = Map<type, markerFilename> (project_paths 주석용)
+//   templateOptions = { templateVersion, includeNexus, includeSecretBackup, includeCodeRabbit?, optionsDate }
+export function buildVersionYml({
+  templateText, version, types = [], primaryType, paths = new Map(), pathMarkers = new Map(),
+  branch = "main", branches = null, versionCode = 1, now, today,
+  templateOptions = null, deployValues = new Map(),
+}) {
+  if (!templateText) throw new Error("version.yml.template 원문이 필요합니다 (payload/version.yml.template 누락?)");
+  const typesJson = types.length ? `[${types.map((t) => `"${t}"`).join(", ")}]` : `["basic"]`;
+  const primary = primaryType || types[0] || "basic";
+  const b = branches || { main: branch || "main", develop: "develop", mode: "pr-flow" };
+  const {
+    templateVersion = "unknown", includeNexus = false, includeSecretBackup = false,
+    includeCodeRabbit = false, optionsDate = today,
+  } = templateOptions || {};
+
+  // project_paths 블록 (full-line 토큰 {{PROJECT_PATHS}} — 없으면 라인 제거)
+  let pathsBlock = "";
+  if (paths.size) {
+    const rows = [`project_paths: # 타입별 프로젝트 폴더 (레포 루트 기준 상대경로)`];
+    for (const [t, p] of paths) {
+      const marker = pathMarkers.get(t) || "";
+      const pf = p === "." ? marker : (marker ? `${p}/${marker}` : p);
+      rows.push(marker ? `  ${t}: "${p}" # ${pf}` : `  ${t}: "${p}"`);
+    }
+    pathsBlock = rows.join("\n");
+  }
+
+  // deploy 블록 (full-line 토큰 {{DEPLOY}} — WF ask 값이 있는 타입만, 앞에 빈 줄 1개)
+  let deployBlock = "";
+  const deployTypes = [...deployValues.keys()].filter((t) => deployValues.get(t) && deployValues.get(t).size > 0);
+  if (deployTypes.length) {
+    const rows = ["", "deploy: # 마법사가 기억하는 배포 설정 (비민감 / 직접 수정 가능)"];
+    for (const t of deployTypes) {
+      rows.push(`  ${t}:`);
+      for (const [k, v] of deployValues.get(t)) rows.push(`    ${k}: "${v}"`);
+    }
+    deployBlock = rows.join("\n");
+  }
+
+  const scalars = {
+    VERSION: version, VERSION_CODE: String(versionCode),
+    PROJECT_TYPES: typesJson, PROJECT_TYPE: primary,
+    NOW: now, TODAY: today || optionsDate, DEFAULT_BRANCH: branch,
+    TEMPLATE_VERSION: templateVersion,
+    MAIN_BRANCH: b.main, DEVELOP_BRANCH: b.develop, BRANCH_MODE: b.mode,
+    OPT_NEXUS: String(includeNexus), OPT_SECRET_BACKUP: String(includeSecretBackup),
+    OPT_CODERABBIT: String(includeCodeRabbit),
+  };
+
+  const out = [];
+  for (const line of String(templateText).split("\n")) {
+    const t = line.trim();
+    if (t === "{{PROJECT_PATHS}}") { if (pathsBlock) out.push(pathsBlock); continue; }
+    if (t === "{{DEPLOY}}") { if (deployBlock) out.push(deployBlock); 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}}}`);
+    }));
+  }
+  let text = out.join("\n");
+  if (!text.endsWith("\n")) text += "\n";
+  return text.replace(/\n{3,}$/, "\n"); // 말미 과잉 빈 줄 정리
+}

package/src/core/wizard-env.js

@@ -0,0 +1,101 @@
+// @wizard env 토큰 엔진 (.sh configure_workflow_env / _wf_set_env / _wf_is_unchanged 등가).
+// ⚠️ YAML 파싱/재직렬화 금지 — 라인 단위 문자열 처리 (포맷·주석 보존이 unchanged 판정 전제).
+// 실측 기준: template_integrator.sh 3282~3360, 3003~3012.
+
+// KEY 정규식: .sh는 [A-Z_]+ (대문자+언더스코어만). ask/auto 마커가 있는 라인만 대상.
+const MARKER_RE = /#\s*@wizard\s+(ask|auto):(.*)$/;
+const KEY_RE = /^(\s*)([A-Z_]+):/;
+const PATHS_ANCHOR_RE = /#\s*@wizard\s+paths-anchor/;
+
+// 한 라인을 파싱해 {indent,key,action,arg} 반환. ask/auto 마커 없으면 null.
+export function parseWizardLine(line) {
+  const marker = line.match(MARKER_RE);
+  if (!marker) return null;
+  const km = line.match(KEY_RE);
+  if (!km) return null; // KEY: 형식 아니면 (예: paths-anchor 주석) 무시
+  return { indent: km[1], key: km[2], action: marker[1], arg: marker[2].trim() };
+}
+
+// .sh _wf_set_env 등가: `KEY: "..."` 따옴표 안 값 치환 + 그 줄 끝 `# @wizard ...` 주석 제거.
+// 라인 하나에 대해 수행. value가 빈문자면 (.sh는 [ -n "$_val" ] 가드) 치환 스킵.
+export function setEnvLine(line, key, value) {
+  if (value === "" || value == null) return line;
+  // CRLF 안전: 라인 끝 \r을 분리해 처리 후 복원 (autocrlf 프로젝트 대응)
+  const cr = line.endsWith("\r") ? "\r" : "";
+  const body = cr ? line.slice(0, -1) : line;
+  // 값 치환: KEY: "기존값" → KEY: "value"
+  let out = body.replace(
+    new RegExp(`^(\\s*${key}:\\s*")[^"]*(")`),
+    (_m, p1, p2) => `${p1}${value}${p2}`,
+  );
+  // 그 줄 끝 # @wizard ... 주석 제거 (앞 공백째)
+  out = out.replace(/(\S)[^\S\r\n]*#[^\S\r\n]*@wizard[^\S\r\n].*$/, "$1");
+  return out + cr;
+}
+
+// resolver — .sh resolve_token 등가. 값 계산은 주입된 resolvers로 위임(순수성 유지).
+// resolvers: { repo, "spring-app-yml-dir"(type), "spring-app-yml-path"(type), "flutter-root" }
+export function resolveToken(name, type, resolvers = {}) {
+  const fn = resolvers[name];
+  return typeof fn === "function" ? (fn(type) ?? "") : "";
+}
+
+// 파일 전체 치환 (configure_workflow_env 등가).
+// content: 원본 워크플로우 텍스트. 반환: 치환된 텍스트.
+// opts:
+//   type          - 프로젝트 타입 (resolver·값 조회용)
+//   values        - Map<key,value>: ask 키의 사용자 선택값 (없으면 기본값=arg 또는 resolver)
+//   useDefaults   - true면 ask도 기본값 사용 (WF_USE_DEFAULTS=true, unchanged 비교의 전제)
+//   resolvers     - resolveToken용
+//   repoName      - __PROJECT_NAME__/__APP_ARTIFACT_NAME__ 치환값
+//   projectPath   - paths-anchor 치환용 ('.'이면 anchor 미변경)
+export function substituteEnv(content, opts = {}) {
+  const { type = "", values = new Map(), useDefaults = true, resolvers = {}, repoName = "", projectPath = ".", collectAsks = null } = opts;
+  if (!content.includes("@wizard")) return content;
+
+  // CRLF 안전: EOL을 분리해 LF 기준으로 파싱·치환하고, 원래 EOL 스타일을 복원한다.
+  // (JS 정규식의 `.`은 \r을 매칭하지 않아 `(.*)$` 마커 파싱이 CRLF에서 실패하기 때문.)
+  const usesCRLF = content.includes("\r\n");
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const p = parseWizardLine(lines[i]); // 이미 \r 제거된 라인
+    if (!p) continue;
+    let val = "";
+    if (p.action === "auto") {
+      val = resolveToken(p.arg, type, resolvers);
+    } else { // ask
+      let def = p.arg.startsWith("@") ? resolveToken(p.arg.slice(1), type, resolvers) : p.arg;
+      const chosen = values.get(p.key);
+      if (chosen != null && chosen !== "" && !useDefaults) val = chosen;
+      else val = def;
+      // ask 키만 수집 (.sh wf_deploy_set — auto는 저장 안 함). deploy 블록용.
+      if (collectAsks) collectAsks.set(p.key, val);
+    }
+    lines[i] = setEnvLine(lines[i], p.key, val);
+  }
+  let out = lines.join(usesCRLF ? "\r\n" : "\n");
+
+  // 잔여 전역 토큰 (.sh 3347~3351)
+  if (out.includes("__PROJECT_NAME__") || out.includes("__APP_ARTIFACT_NAME__")) {
+    out = out.replaceAll("__PROJECT_NAME__", repoName).replaceAll("__APP_ARTIFACT_NAME__", repoName);
+  }
+
+  // paths-anchor (.sh 3353~3360): 경로가 '.'이 아니면 주석 라인 전체를 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) => {
+      if (PATHS_ANCHOR_RE.test(line)) {
+        const indent = (line.match(/^(\s*)/) || ["", ""])[1];
+        return `${indent}paths: ['${projectPath}/**']`;
+      }
+      return line;
+    }).join(eol);
+  }
+  return out;
+}
+
+// .sh _wf_is_unchanged 등가: 원본을 "기본값으로 가상 치환한 최종형"과 설치본을 바이트 비교.
+export function isUnchanged(templateContent, installedContent, opts = {}) {
+  const virtual = substituteEnv(templateContent, { ...opts, useDefaults: true });
+  return virtual === installedContent;
+}