project-auto-wizard 0.1.5

package/src/commands/interactive.js

@@ -0,0 +1,276 @@
+// 대화형 마법사 (.sh interactive_mode 등가) + #446 UI 층.
+// io 주입으로 테스트 가능. 실제 실행은 src/ui/prompts.js 함수를 io로 넘긴다.
+// 새 시각 층(banner/detectionLog/analysisCard/installKind/summary)과 저수준 엔진(engineIo)은
+// io의 "옵셔널 멤버" — 스텁이 생략하면 해당 층만 건너뛰고 실행 계약은 동일하다.
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { resolvePayloadRoot, assertPayload, readTemplateVersion } from "../core/assets.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 { resolveBranchConfig, detectRemoteBranches, ensureDevelopBranch } from "../core/branches.js";
+import { askAllOptionalWorkflows } from "../core/options-ask.js";
+import { promptEnvPlan } from "../ui/env-plan.js";
+import { listWorkflowConflicts } from "../core/copy/workflows.js";
+import { createContext, VALID_TYPES } from "../context.js";
+import { runFull } from "./full.js";
+import { runVersion } from "./version.js";
+import { runWorkflows } from "./workflows.js";
+import { runRevert } from "./revert.js";
+import * as prompts from "../ui/prompts.js";
+
+const CANCEL = prompts.CANCEL;
+const isCancel = (v) => v === CANCEL || typeof v === "symbol";
+
+// io 기본값 = 실제 prompts. 테스트는 스텁 io 주입.
+export async function runInteractive(baseCtx, { cwd = process.cwd(), payloadRoot, clock, io = prompts } = {}) {
+  const payload = assertPayload(payloadRoot ?? resolvePayloadRoot());
+  const templateVersion = readTemplateVersion();
+
+  // 층1 — 시작 배너 (#446 확정 시안 A). 스텁엔 banner 없음 → intro 폴백.
+  if (io.banner) io.banner({ version: templateVersion, modeLabel: "대화형 통합 마법사" });
+  else io.intro?.("project-auto-wizard — 대화형 통합 마법사");
+
+  // 기존 version.yml — version/version_code/paths/옵션 보존의 단일 진실 (.sh SSoT L2208~2239)
+  const vyPath = join(cwd, "version.yml");
+  const existing = existsSync(vyPath) ? parseExisting(readFileSync(vyPath, "utf8")) : null;
+
+  // 층5 — 신규/업데이트 판별 (#446)
+  io.installKind?.({ currentTemplateVersion: existing?.templateVersion || "", templateVersion });
+
+  // 1) 모드 선택
+  const mode = await io.selectMode();
+  if (mode === CANCEL || mode == null) { io.cancelMessage?.("설치를 취소했습니다."); return 0; }
+
+  // revert 모드 — 확인 질문(기본 아니오) 후 payload 유래 파일 제거. 감지·breaking 게이트 불필요.
+  if (mode === "revert") {
+    const ok = await io.askYesNo("마법사가 설치한 워크플로우·스크립트를 제거할까요? (version.yml·README는 보존)", false);
+    if (ok !== true) { io.cancelMessage?.("되돌리기를 취소했습니다."); return 0; }
+    const r = runRevert({}, payload, cwd);
+    io.note?.(`워크플로우 ${r.workflows.length}개, 스크립트 ${r.scripts.length}개 제거${r.coderabbit ? " + .coderabbit.yaml" : ""}`, "되돌리기 완료");
+    io.outro?.("되돌리기를 마쳤습니다.");
+    return 0;
+  }
+
+  // Breaking Changes 게이트 (.sh execute_integration L4415~4420 — 모든 모드 공통, 대화형은 확인 질문)
+  const proceed = await runBreakingCheck({
+    cwd, payloadRoot: payload, templateVersion,
+    askYesNo: (msg, def) => io.askYesNo(msg, def),
+  });
+  if (!proceed) { io.cancelMessage?.("통합을 안전하게 취소했습니다."); return 0; }
+
+  // full/version/workflows — 감지 (version은 기존 version.yml 최우선)
+  let types = detectTypes(cwd);
+  let version = (existing?.version) || detectVersion(cwd);
+  let branch = detectDefaultBranch(cwd);
+  const repoName = detectRepoName(cwd);
+  const versionCode = existing?.versionCode ?? 1; // 기존 빌드번호 보존
+  // 선택 워크플로우 초기값: version.yml 저장 옵션 (.sh read_template_options L2361 등가)
+  let includeNexus = existing?.options?.nexus ?? false;
+  let includeSecretBackup = existing?.options?.secretBackup ?? false;
+  let includeCodeRabbit = existing?.options?.coderabbit ?? null;
+  const showOptional = mode === "full" || mode === "workflows";
+  const realTty = process.stdout.isTTY === true;
+
+  // 층2 — 감지 로그 (#446)
+  io.detectionLog?.({ types, version, branch });
+
+  // 선택 워크플로우(Nexus/Secret) 질문 (.sh ask_all_optional_workflows L2707 — full/workflows만)
+  if (showOptional) {
+    const r = await askAllOptionalWorkflows({
+      payloadRoot: payload, types, targetRoot: cwd,
+      current: { nexus: existing?.options?.nexus ?? null, secretBackup: existing?.options?.secretBackup ?? null },
+      force: false, tty: realTty,
+      io: { confirm: ({ message, initialValue }) => io.askYesNo(message, initialValue) },
+    });
+    includeNexus = r.nexus;
+    includeSecretBackup = r.secretBackup;
+
+    // 신규 질문 ② — CodeRabbit opt-in (DESIGN-SPEC §4, 기본 아니오). 저장값 있으면 재질문 생략.
+    if (includeCodeRabbit === null) {
+      const y = await io.askYesNo("CodeRabbit을 사용합니까? (PR AI 리뷰·요약을 릴리스 노트 1순위로 사용)", false);
+      includeCodeRabbit = y === true;
+    }
+  }
+  includeCodeRabbit = includeCodeRabbit === true;
+
+  // 확인/수정 루프 — ESC는 '머무르기' (.sh L1877~1881: 명시적 '아니오'만 종료)
+  let paths = new Map();
+  let confirmed = false;
+  while (!confirmed) {
+    // 층3 — 프로젝트 분석 개요 카드 (#446). 스텁엔 없음 → note 폴백.
+    if (io.analysisCard) {
+      io.analysisCard({ mode, modeLabel: modeLabel(mode), types, version, branch, includeNexus, includeSecretBackup, showOptional, paths });
+    } else {
+      io.note?.(summarize({ mode, types, version, branch, includeNexus, includeSecretBackup, showOptional }), "프로젝트 분석 결과");
+    }
+    const choice = await io.confirmProjectMenu();
+    if (choice === "cancel") { io.cancelMessage?.("설치를 취소했습니다."); return 0; }
+    if (isCancel(choice) || choice == null) continue; // ESC = 머무르기 (루프 재출력)
+    if (choice === "continue") { confirmed = true; break; }
+    // edit 루프
+    let editing = true;
+    while (editing) {
+      const what = await io.editMenu({ showOptional });
+      if (isCancel(what) || what === "done") { editing = false; break; }
+      if (what === "type") {
+        const t = await io.selectTypes(types);
+        if (!isCancel(t) && Array.isArray(t) && t.length) {
+          // 타입 집합이 실제로 바뀌면 경로 재해석 대상으로 초기화 (.sh L1984~1992 — 정렬 집합 비교)
+          const oldSorted = [...types].sort().join(",");
+          types = t.filter((x) => VALID_TYPES.includes(x));
+          if ([...types].sort().join(",") !== oldSorted) paths = new Map();
+        }
+      } else if (what === "version") {
+        const v = await io.askText("새 버전 (예: 1.0.0)", version);
+        if (!isCancel(v) && v !== version) {
+          // semver 형식 검증 (.sh L2010~2015)
+          if (/^\d+\.\d+\.\d+$/.test(v)) version = v;
+          else io.note?.("버전 형식이 올바르지 않습니다 (x.y.z 형태) — 기존 값을 유지합니다.", "⚠ 버전");
+        }
+      } else if (what === "branch") {
+        const b = await io.askText("기본 브랜치", branch);
+        if (!isCancel(b) && b) branch = b;
+      } else if (what === "nexus") {
+        const y = await io.askYesNo("Nexus publish 워크플로우를 포함할까요?", includeNexus);
+        if (!isCancel(y)) includeNexus = y === true;
+      } else if (what === "secret") {
+        const y = await io.askYesNo("Secret 백업 워크플로우를 포함할까요?", includeSecretBackup);
+        if (!isCancel(y)) includeSecretBackup = y === true;
+      }
+    }
+  }
+
+  // 신규 질문 ① — 브랜치 설정 (DESIGN-SPEC §4). full/workflows만 질문, version은 기본값 기록.
+  // 저장값(version.yml metadata.template.branches)이 있으면 재질문 없이 재사용 (업데이트 모드).
+  let branches = existing?.branches
+    ? resolveBranchConfig({ mainBranch: existing.branches.main, developBranch: existing.branches.develop, defaultBranch: branch })
+    : resolveBranchConfig({ defaultBranch: branch });
+  if (showOptional && !existing?.branches) {
+    const remoteBranches = await detectRemoteBranches(cwd);
+    const mainB = await pickBranch(io, `릴리스 브랜치를 선택하세요 (기본: ${branch})`, branch, remoteBranches, isCancel);
+    const devB = await pickBranch(io, "개발 브랜치를 선택하세요 (기본: develop)", "develop", remoteBranches, isCancel);
+    branches = resolveBranchConfig({ mainBranch: mainB, developBranch: devB, defaultBranch: branch });
+    if (branches.mode === "trunk-based") {
+      io.note?.("릴리스 브랜치 = 개발 브랜치 → trunk-based 모드로 설치합니다 (RELEASE-PUBLISH 단독).", "브랜치 모드");
+    } else if (remoteBranches.length && !remoteBranches.includes(branches.develop)) {
+      await ensureDevelopBranch({
+        develop: branches.develop, remoteBranches, cwd,
+        confirm: (msg) => io.askYesNo(msg, true),
+        log: (m) => io.note?.(m, "브랜치"),
+      });
+    }
+  }
+
+  // 경로 확정 (.sh resolve_project_paths L1362~1589 — full/version만. 저장값·후보 스캔·질문)
+  if (mode === "full" || mode === "version") {
+    paths = await resolveProjectPaths({
+      root: cwd, types, paths, existingPaths: existing?.paths ?? new Map(),
+      force: false, tty: realTty, io: io.engineIo ?? {},
+    });
+  } else {
+    for (const t of types) if (t !== "basic" && !paths.has(t)) paths.set(t, existing?.paths.get(t) || ".");
+  }
+
+  // @wizard env 계획 질문 (.sh wf_prompt_env_plan L3220 — full/workflows만)
+  const resolvers = makeResolvers(cwd, repoName, paths);
+  let envValues = new Map(), envUseDefaults = true;
+  if (showOptional) {
+    const plan = await promptEnvPlan({
+      payloadRoot: payload, types, io: io.engineIo ?? null, force: false,
+      resolvers, includeNexus, targetRoot: cwd, repoName,
+    });
+    envValues = plan.values;
+    envUseDefaults = plan.useDefaults;
+  }
+
+  const { now, today } = clock || utcNow();
+  const ctx = createContext({
+    mode, force: true, types, version, versionCode, branch, branches, paths,
+    includeNexus, includeSecretBackup, includeCodeRabbit,
+    repoName, templateVersion, resolvers, envValues, envUseDefaults, now, today,
+  });
+  ctx.templateVersion = templateVersion;
+
+  // 기존 워크플로우 충돌 3지선 — 타입당 1회 결정을 파일에 캐시 적용 (.sh L3440~3508 UX 등가)
+  let hooks = {};
+  if (showOptional && io.engineIo?.select) {
+    const conflicts = listWorkflowConflicts(ctx, payload, cwd);
+    if (conflicts.length) {
+      const perType = new Map();
+      const decisions = new Map();
+      for (const { filename, type } of conflicts) {
+        if (!perType.has(type)) {
+          const sel = await io.engineIo.select({
+            message: `기존 워크플로우와 내용이 다른 파일이 있습니다 (${type}) — 어떻게 할까요?`,
+            options: [
+              { value: "skip", label: "건너뛰기 — 기존 파일 유지 (기본)" },
+              { value: "backup", label: ".bak 백업 후 새 버전으로 교체" },
+              { value: "template", label: "기존 유지 + 새 버전을 .template.yaml로 참고 추가" },
+            ],
+          });
+          perType.set(type, isCancel(sel) || sel == null ? "skip" : sel); // ESC = 건너뛰기 (.sh L3463)
+        }
+        decisions.set(filename, perType.get(type));
+      }
+      hooks = { decisions };
+    }
+  }
+
+  let result = null;
+  if (mode === "full") result = runFull(ctx, payload, cwd, hooks);
+  else if (mode === "version") result = runVersion(ctx, payload, cwd);
+  else if (mode === "workflows") result = runWorkflows(ctx, payload, cwd, hooks);
+
+  // 완료 요약 (.sh print_summary L5438)
+  io.summary?.({
+    mode, types, version, branches, includeCodeRabbit,
+    counters: { workflows: result?.workflows?.copied ?? 0 },
+  }, cwd);
+  io.outro?.(`통합 완료 — ${mode} 모드로 설치했습니다.`);
+  return 0;
+}
+
+// 브랜치 선택 — 원격 목록이 있으면 select(+직접 입력), 없으면 텍스트 입력. ESC/빈값 = 기본값.
+async function pickBranch(io, message, def, remoteBranches, isCancel) {
+  if (io.engineIo?.select && remoteBranches.length) {
+    const options = [];
+    if (!remoteBranches.includes(def)) options.push({ value: def, label: `${def} (기본값 — 없으면 새로 생성)` });
+    for (const b of remoteBranches) options.push({ value: b, label: b === def ? `${b} (기본값)` : b });
+    options.push({ value: "__custom__", label: "직접 입력..." });
+    const sel = await io.engineIo.select({ message, options });
+    if (sel === "__custom__") {
+      const v = await io.askText("브랜치 이름", def);
+      return isCancel(v) || !v ? def : v;
+    }
+    return isCancel(sel) || sel == null ? def : sel;
+  }
+  const v = await io.askText(message, def);
+  return isCancel(v) || !v ? def : v;
+}
+
+function summarize({ mode, types, version, branch, includeNexus, includeSecretBackup, showOptional }) {
+  const lines = [
+    `통합 모드 : ${modeLabel(mode)}`,
+    `프로젝트 타입 : ${types.join(", ")}${types.length > 1 ? " (멀티)" : ""}`,
+    `버전 : ${version}`,
+    `기본 브랜치 : ${branch}`,
+  ];
+  if (showOptional) {
+    lines.push(`Nexus publish : ${includeNexus ? "포함" : "제외"}`);
+    lines.push(`Secret 백업 : ${includeSecretBackup ? "포함" : "제외"}`);
+  }
+  return lines.join("\n");
+}
+
+function modeLabel(m) {
+  return { full: "전체 설치", version: "버전 관리만", workflows: "워크플로우만" }[m] || m;
+}
+
+function utcNow(date = new Date()) {
+  const p = (n) => String(n).padStart(2, "0");
+  const d = `${date.getUTCFullYear()}-${p(date.getUTCMonth() + 1)}-${p(date.getUTCDate())}`;
+  const t = `${p(date.getUTCHours())}:${p(date.getUTCMinutes())}:${p(date.getUTCSeconds())}`;
+  return { now: `${d} ${t}`, today: d };
+}

package/src/commands/revert.js

@@ -0,0 +1,60 @@
+// revert 모드 — payload 유래 파일만 제거 (DESIGN-SPEC §4 되돌리기).
+// 원칙: payload에 존재하는 파일명과 정확히 일치하는 것만 지운다.
+// 사용자가 직접 만든 워크플로우·version.yml·README·.gitignore는 건드리지 않는다
+// (version.yml은 사용자 버전 데이터 — 제거 대상이 아니라 산출물이다).
+import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync, renameSync } from "node:fs";
+import { PATHS, PAYLOAD } from "../core/paths.js";
+import { remove } from "../core/fsutil.js";
+
+// payload/workflows/** 전체(하위 폴더 포함)의 yaml 파일명 집합.
+function payloadWorkflowNames(payloadRoot) {
+  const names = new Set();
+  const root = join(payloadRoot, PAYLOAD.workflowsDir);
+  if (!existsSync(root)) return names;
+  for (const e of readdirSync(root, { recursive: true, withFileTypes: true })) {
+    if (e.isFile() && /\.(ya?ml)$/.test(e.name)) names.add(e.name);
+  }
+  return names;
+}
+
+// 반환: { workflows: [...제거된 파일명], scripts: [...], coderabbit: bool }
+export function runRevert(context, payloadRoot, targetRoot = ".") {
+  const removedWf = [];
+  const removedScripts = [];
+
+  // 1. 워크플로우 — payload 파일명 일치분 + 마법사가 만든 .template.yaml/.bak 파생본
+  const wfDir = join(targetRoot, PATHS.workflowsDir);
+  const names = payloadWorkflowNames(payloadRoot);
+  if (existsSync(wfDir)) {
+    for (const name of names) {
+      const p = join(wfDir, name);
+      if (existsSync(p)) { remove(p); removedWf.push(name); }
+      const templateName = (name.endsWith(".yaml") ? name.slice(0, -".yaml".length) : name) + ".template.yaml";
+      const tp = join(wfDir, templateName);
+      if (existsSync(tp)) { remove(tp); removedWf.push(templateName); }
+      const bp = p + ".bak";
+      if (existsSync(bp)) { remove(bp); removedWf.push(name + ".bak"); }
+    }
+  }
+
+  // 2. 스크립트 — payload가 설치한 2종만
+  for (const s of ["version_manager.py", "changelog_manager.py"]) {
+    const p = join(targetRoot, PATHS.scriptsDir, s);
+    if (existsSync(p)) { remove(p); removedScripts.push(s); }
+  }
+
+  // 3. .coderabbit.yaml — payload 원본과 바이트 일치할 때만 제거 (사용자 자체 파일 보호).
+  //    설치 시 백업(.bak)이 있으면 복원한다.
+  let coderabbit = false;
+  const cr = join(targetRoot, ".coderabbit.yaml");
+  const crSrc = join(payloadRoot, "coderabbit.yaml");
+  if (existsSync(cr) && existsSync(crSrc)
+    && readFileSync(cr, "utf8") === readFileSync(crSrc, "utf8")) {
+    remove(cr);
+    coderabbit = true;
+    if (existsSync(cr + ".bak")) renameSync(cr + ".bak", cr);
+  }
+
+  return { workflows: removedWf, scripts: removedScripts, coderabbit };
+}

package/src/commands/version.js

@@ -0,0 +1,31 @@
+// version 모드 (.sh execute_integration version case 등가).
+// 순서: version.yml → readme → scripts → gitignore.
+// (워크플로우 미복사 → deploy 블록 없음. util·issue·coderabbit·setup-guide는 스코프 제외.)
+import { join } from "node:path";
+import { writeText } from "../core/fsutil.js";
+import { PATHS } from "../core/paths.js";
+import { buildVersionYml } from "../core/version-yml.js";
+import { readVersionYmlTemplate } from "../core/assets.js";
+import { markerForType } from "../core/detect.js";
+import { addVersionSectionToReadme } from "../core/copy/readme.js";
+import { copyScripts } from "../core/copy/simple.js";
+import { ensureGitignore } from "../core/copy/gitignore.js";
+
+export function runVersion(context, payloadRoot, targetRoot = ".") {
+  const { version, types = [], paths = new Map(), branch = "main", versionCode = 1,
+    now, today, templateVersion = "unknown",
+    includeNexus = false, includeSecretBackup = false, includeCodeRabbit = false } = context;
+
+  const pathMarkers = new Map();
+  for (const [t] of paths) pathMarkers.set(t, markerForType(t));
+
+  writeText(join(targetRoot, PATHS.versionFile),
+    buildVersionYml({
+      templateText: readVersionYmlTemplate(payloadRoot),
+      version, types, paths, pathMarkers, branch, branches: context.branches, versionCode, now, today,
+      templateOptions: { templateVersion, includeNexus, includeSecretBackup, includeCodeRabbit: includeCodeRabbit === true, optionsDate: today },
+    }));
+  addVersionSectionToReadme(version, targetRoot);
+  copyScripts(payloadRoot, targetRoot);
+  ensureGitignore(targetRoot);
+}

package/src/commands/workflows.js

@@ -0,0 +1,49 @@
+// workflows 모드 (.sh execute_integration workflows case 등가).
+// 순서: copy_workflows → update_version_yml_deploy(version.yml 있을 때만) → scripts.
+// (version.yml 생성 안 함 — 기존 version.yml이 있을 때만 deploy 블록 추가.
+//  util/config/setup-guide 설치는 project-auto-wizard 스코프에서 제외 — DESIGN-SPEC §2)
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { PATHS } from "../core/paths.js";
+import { copyWorkflows } from "../core/copy/workflows.js";
+import { copyScripts } from "../core/copy/simple.js";
+
+export function runWorkflows(context, payloadRoot, targetRoot = ".", hooks = {}) {
+  const wf = copyWorkflows(context, payloadRoot, targetRoot, hooks);
+
+  // update_version_yml_deploy: 기존 version.yml이 있고 ask 값이 있을 때만 deploy 블록 갱신
+  const vy = join(targetRoot, PATHS.versionFile);
+  if (existsSync(vy) && wf.deployValues && wf.deployValues.size) {
+    writeFileSync(vy, upsertDeployBlock(readFileSync(vy, "utf8"), wf.deployValues));
+  }
+
+  copyScripts(payloadRoot, targetRoot);
+  return { workflows: wf };
+}
+
+// 기존 version.yml에서 deploy: 블록을 제거하고 새로 append (.sh update_version_yml_deploy 멱등).
+export function upsertDeployBlock(content, deployValues) {
+  // 기존 deploy: 블록 제거 (deploy: 라인 ~ 다음 최상위 키 전까지)
+  const lines = content.split(/\r?\n/);
+  const out = [];
+  let inDeploy = false;
+  for (const line of lines) {
+    if (/^deploy:/.test(line)) { inDeploy = true; continue; }
+    if (inDeploy) {
+      if (/^\s/.test(line) || line === "") continue; // 들여쓰기/빈줄 = deploy 내부
+      inDeploy = false;
+    }
+    out.push(line);
+  }
+  let text = out.join("\n").replace(/\n+$/, "\n");
+  // 새 deploy 블록 append
+  const deployTypes = [...deployValues.keys()].filter((t) => deployValues.get(t)?.size);
+  if (deployTypes.length) {
+    text += `\ndeploy:                          # 마법사가 기억하는 배포 설정 (비민감 / 직접 수정 가능)\n`;
+    for (const t of deployTypes) {
+      text += `  ${t}:\n`;
+      for (const [k, v] of deployValues.get(t)) text += `    ${k}: "${v}"\n`;
+    }
+  }
+  return text;
+}

package/src/context.js

@@ -0,0 +1,26 @@
+// 마법사 전역 상태를 하나의 객체로 명시화 (bash 전역 변수군 대체)
+export const VALID_TYPES = [
+  "spring", "flutter", "next", "react",
+  "react-native", "react-native-expo", "node", "python", "basic",
+];
+
+export const DEFAULT_VERSION = "0.0.0"; // 패키지 버전 읽기 실패 시 폴백 (배너용 — breaking 비교엔 안 씀)
+
+export function createContext(overrides = {}) {
+  return {
+    mode: "interactive",
+    force: false,
+    types: [],
+    version: "",
+    branch: "",
+    branches: null,          // { main, develop, mode: "pr-flow"|"trunk-based" } — resolveBranchConfig 결과
+    paths: new Map(),        // type -> path
+    includeNexus: null,      // null=미설정, true/false=명시
+    includeSecretBackup: null,
+    includeCodeRabbit: null, // CodeRabbit opt-in (기본 false — version.yml options.coderabbit에 기록)
+    templateVersion: "",
+    deployValues: new Map(), // "type.KEY" -> value
+    counters: {},
+    ...overrides,
+  };
+}

package/src/core/assets.js

@@ -0,0 +1,47 @@
+// payload 자산 해석 — 네트워크 접근 0 (구 acquireTemplate/git clone 대체).
+// 마법사가 설치하는 모든 자산은 npm 패키지에 동봉된 payload/ 가 단일 진실이다.
+// npx 글로벌 캐시에서 실행돼도 import.meta.url 기준으로 패키지 내 payload를 정확히 가리킨다.
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { exists, readText, listYamlFiles } from "./fsutil.js";
+import { DEFAULT_VERSION } from "../context.js";
+
+// 패키지 내 payload/ 절대경로. 테스트·픽스처는 인자 주입으로 대체 가능.
+export function resolvePayloadRoot() {
+  return fileURLToPath(new URL("../../payload/", import.meta.url));
+}
+
+// 마법사(=템플릿) 버전 — 패키지 package.json의 version.
+// 구 readTemplateVersion(tempDir/version.yml)과 동일한 소비처(배너·breaking 비교·version.yml 기록)를 채운다.
+export function readTemplateVersion() {
+  try {
+    const pkgPath = fileURLToPath(new URL("../../package.json", import.meta.url));
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return pkg.version || DEFAULT_VERSION;
+  } catch {
+    return DEFAULT_VERSION;
+  }
+}
+
+// payload/workflows/common 직하위 yaml 목록 (secret-backup 하위 폴더 제외 — 복사 엔진과 동일 규약).
+export function listCommonWorkflows(payloadRoot = resolvePayloadRoot()) {
+  return listYamlFiles(join(payloadRoot, "workflows", "common"));
+}
+
+// payload 구조 자가 점검 — 필수 폴더 누락 시 명확히 실패 (배포 패키징 오류 조기 발견).
+export function assertPayload(payloadRoot = resolvePayloadRoot()) {
+  if (!exists(join(payloadRoot, "workflows"))) {
+    throw new Error("패키지 구조 오류 — payload/workflows 폴더를 찾지 못했습니다.");
+  }
+  if (!exists(join(payloadRoot, "scripts"))) {
+    throw new Error("패키지 구조 오류 — payload/scripts 폴더를 찾지 못했습니다.");
+  }
+  return payloadRoot;
+}
+
+// payload/version.yml.template 원문 (Task 14 치환 파이프라인 소비).
+export function readVersionYmlTemplate(payloadRoot = resolvePayloadRoot()) {
+  const p = join(payloadRoot, "version.yml.template");
+  return exists(p) ? readText(p) : null;
+}

package/src/core/branches.js

@@ -0,0 +1,60 @@
+// 브랜치 구성 (DESIGN-SPEC §4 신규 질문 ①).
+// on: push: branches: 는 YAML 정적 값 — 마법사가 릴리스/개발 브랜치를 물어(또는 플래그로 받아)
+// {{MAIN_BRANCH}}/{{DEVELOP_BRANCH}} 플레이스홀더를 치환한다 (치환 자체는 branding.js — Task 14).
+// main === develop 이면 trunk-based 모드 → RELEASE-PUBLISH 단독 설치 (설치 매트릭스는 Task 16).
+import { execFile } from "node:child_process";
+
+// 기본 exec — git 명령 실행. 반환 {code, stdout, stderr}. 테스트는 mock 주입.
+function defaultExec(cmd, args, { cwd } = {}) {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { cwd, windowsHide: true }, (err, stdout, stderr) => {
+      resolve({ code: err ? (err.code ?? 1) : 0, stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}
+
+// 감지: 로컬 git에서 원격 브랜치 목록 (네트워크 없이 — 로컬이 아는 origin/* 기준).
+// git이 없거나 레포가 아니면 빈 목록 (질문 기본값 경로로 폴백).
+export async function detectRemoteBranches(cwd, exec = defaultExec) {
+  const r = await exec("git", ["branch", "-r", "--format=%(refname:short)"], { cwd });
+  if (r.code !== 0) return [];
+  return r.stdout
+    .split(/\r?\n/)
+    .map((s) => s.trim())
+    .filter((s) => s && !s.includes("->")) // "origin/HEAD -> origin/main" 제외
+    .map((s) => s.replace(/^origin\//, ""))
+    .filter((s, i, a) => a.indexOf(s) === i);
+}
+
+// 결정 (순수 함수): 플래그/답변 → 최종 구성.
+// 우선순위: 명시값(mainBranch/developBranch) → 감지 default → 하드 폴백(main/develop).
+export function resolveBranchConfig({ mainBranch = "", developBranch = "", defaultBranch = "" } = {}) {
+  const main = mainBranch || defaultBranch || "main";
+  const develop = developBranch || "develop";
+  return { main, develop, mode: main === develop ? "trunk-based" : "pr-flow" };
+}
+
+// 생성: develop이 원격에 없으면 현 HEAD 기준으로 생성 + push.
+// confirm: async(message)→bool — 대화형 확인 질문. null이면(--force) 질문 없이 자동 생성.
+// exec 주입 가능 (테스트 mock). 반환 { created, pushed?, skipped? }.
+export async function ensureDevelopBranch({ develop, remoteBranches = [], confirm = null, cwd, exec = defaultExec, log = null }) {
+  if (remoteBranches.includes(develop)) return { created: false };
+
+  if (confirm) {
+    const ok = await confirm(`원격에 '${develop}' 브랜치가 없습니다. 현재 HEAD 기준으로 생성하고 push할까요?`);
+    if (ok !== true) return { created: false, skipped: true };
+  }
+
+  const br = await exec("git", ["branch", develop], { cwd });
+  if (br.code !== 0) {
+    // 이미 로컬에 존재하는 경우 등 — push만 시도
+    log?.(`'${develop}' 로컬 브랜치 생성 생략 (${(br.stderr || "").trim() || "이미 존재"})`);
+  }
+  const push = await exec("git", ["push", "-u", "origin", develop], { cwd });
+  if (push.code !== 0) {
+    log?.(`⚠️  '${develop}' 브랜치 push 실패 — 원격 설정을 확인한 뒤 수동으로 push하세요 (git push -u origin ${develop})`);
+    return { created: true, pushed: false };
+  }
+  log?.(`'${develop}' 브랜치를 생성하고 push했습니다.`);
+  return { created: true, pushed: true };
+}

package/src/core/branding.js

@@ -0,0 +1,15 @@
+// 브랜치 플레이스홀더 치환 파이프라인 (DESIGN-SPEC §4).
+// payload 워크플로우의 {{MAIN_BRANCH}}/{{DEVELOP_BRANCH}}를 설치 시 실제 브랜치명으로 바꾼다.
+// ⚠️ GitHub Actions 표현식 `${{ ... }}`은 우리 토큰이 아니다 — `$` 선행 시 제외(lookbehind).
+// 치환 후 알 수 없는 {{TOKEN}}이 남으면 throw — 복사 무결성 가드 (오타·누락 조기 검출).
+
+const TOKEN_RE = /(?<!\$)\{\{([A-Z][A-Z0-9_]*)\}\}/g;
+
+// substitute(text, {main, develop}) — 브랜치 토큰 치환. 미지 토큰 발견 시 throw.
+export function substitute(text, { main, develop }) {
+  const map = { MAIN_BRANCH: main, DEVELOP_BRANCH: develop };
+  return String(text).replace(TOKEN_RE, (_, name) => {
+    if (name in map) return map[name];
+    throw new Error(`알 수 없는 플레이스홀더가 남았습니다: {{${name}}}`);
+  });
+}

package/src/core/breaking-check.js

@@ -0,0 +1,65 @@
+// breaking-changes 확인 흐름 배선 (.sh check_breaking_changes L2506~2616 등가).
+// collectBreaking(순수 비교)은 breaking.js — 이 모듈은 로드(원격→clone본 폴백)·표시·확인 게이트.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { collectBreaking } from "./breaking.js";
+import { parseExisting } from "./version-yml.js";
+
+const BC_URL = "https://raw.githubusercontent.com/Twin-Fang/project-auto-wizard/main/payload/config/breaking-changes.json";
+
+// 원격 우선(3초 타임아웃) → 패키지 payload/config 번들본 폴백 → 둘 다 실패 시 null(조용히 스킵 — .sh 등가)
+export async function loadBreakingJson(payloadRoot) {
+  try {
+    const res = await fetch(BC_URL, { signal: AbortSignal.timeout(3000) });
+    if (res.ok) return await res.json();
+  } catch { /* 원격 실패 — 폴백 */ }
+  try {
+    const p = join(payloadRoot, "config", "breaking-changes.json");
+    if (existsSync(p)) return JSON.parse(readFileSync(p, "utf8"));
+  } catch { /* 폴백 실패 — 스킵 */ }
+  return null;
+}
+
+// 반환: true=진행, false=사용자 취소.
+// opts:
+//   cwd             - 통합 대상 루트 (기존 version.yml에서 현재 템플릿 버전 읽음)
+//   payloadRoot     - 패키지 payload/ 루트 (번들 폴백용)
+//   templateVersion - 설치하려는 템플릿 버전 (.sh의 DEFAULT_VERSION 고정 버그를 실버전으로 교정 — 설계 D2)
+//   askYesNo        - async(message, defaultYes)→bool. null이면 비대화형: 경고만 출력 후 진행
+//   loader          - 테스트 주입용 (기본 loadBreakingJson)
+export async function runBreakingCheck({ cwd, payloadRoot, templateVersion, askYesNo = null, loader = loadBreakingJson }) {
+  const vy = join(cwd, "version.yml");
+  if (!existsSync(vy)) return true; // 신규 통합 — 비교 기준 없음
+  const { templateVersion: current } = parseExisting(readFileSync(vy, "utf8"));
+  if (!current) return true; // 템플릿 메타 없음(unknown) — .sh 동일하게 스킵
+
+  const json = await loader(payloadRoot);
+  if (!json) return true;
+
+  const { critical, warnings } = collectBreaking(json, current, templateVersion);
+  if (critical.length === 0 && warnings.length === 0) return true;
+
+  // 박스 표시 (.sh L2580~2603)
+  const e = (s = "") => process.stderr.write(s + "\n");
+  e("");
+  e("╔══════════════════════════════════════════════════════════════════╗");
+  e(`║  ⚠️  BREAKING CHANGES (v${current} → v${templateVersion})`);
+  e("╠══════════════════════════════════════════════════════════════════╣");
+  for (const c of critical) { e("║"); e(`║  [CRITICAL] ${c.version} - ${c.title || ""}`); e(`║  → ${c.message || ""}`); }
+  for (const w of warnings) { e("║"); e(`║  [WARNING] ${w.version} - ${w.title || ""}`); e(`║  → ${w.message || ""}`); }
+  e("║");
+  e("╚══════════════════════════════════════════════════════════════════╝");
+  e("");
+
+  if (critical.length > 0) {
+    if (askYesNo) {
+      // 대화형: 명시 확인 없으면 중단 (기본 N — .sh 등가)
+      const ok = await askYesNo("위 호환성 변경을 확인했고 계속 진행할까요?", false);
+      if (ok !== true) return false;
+    } else {
+      // 비대화형(--force): 게이트로 CI를 죽이지 않고 경고 후 진행 (.sh와 의도적 차이 — CI 친화)
+      e("⚠️  CRITICAL 호환성 변경이 있습니다 — 비대화형 실행이라 계속 진행합니다. 위 내용을 꼭 확인하세요.");
+    }
+  }
+  return true;
+}