project-auto-wizard 0.12.2 → 0.13.0

package/src/commands/uninstall.js

@@ -1,15 +1,46 @@
 // uninstall 모드 — 마법사가 설치한 파일(planRemoval 판별분)에 더해 README/.gitignore/version.yml까지
 // 선택적으로 제거한다. 대화형 체크리스트 또는 --force + --purge-* 로 항목별 opt-in.
 // core/removal-plan.js는 읽기 전용으로만 재사용한다(아무것도 지우지 않는 순수 함수).
-import { join } from "node:path";
-import { existsSync } from "node:fs";
+import { join, posix } from "node:path";
+import { existsSync, readdirSync, rmdirSync } from "node:fs";
 import { PATHS } from "../core/paths.js";
 import { remove } from "../core/fsutil.js";
-import { planRemoval } from "../core/removal-plan.js";
+import { planRemoval, backupArtifacts } from "../core/removal-plan.js";
 import { removeVersionSectionFromReadme, hasVersionSection } from "../core/copy/readme.js";
 import { removeAutoAddedEntriesFromGitignore, hasAutoAddedEntries } from "../core/copy/gitignore.js";
 import { CANCEL } from "../ui/prompts.js";
-import { log } from "../core/logger.js";
+import { logRemovals } from "../core/logger.js";
+
+// 파일을 지운 뒤 비게 된 상위 폴더를 레포 루트 직전까지 정리한다(마법사가 만든 fastlane/ 등).
+// 비어 있지 않은 폴더를 만나면 멈추므로 사용자 파일이 남은 폴더는 건드리지 않는다.
+export function pruneEmptyDirs(targetRoot, relDir) {
+  let rel = relDir;
+  while (rel && rel !== "." && rel !== "/") {
+    const abs = join(targetRoot, rel);
+    try {
+      if (readdirSync(abs).length) break;
+      rmdirSync(abs);
+    } catch { break; }
+    rel = posix.dirname(rel);
+  }
+}
+
+// Flutter 앱 파일 제거 — 미수정분만 plan에 들어오므로 그대로 지우고 빈 폴더를 정리한다.
+// 로그는 삭제가 끝난 뒤 한꺼번에 남기므로 기록할 항목을 done에 모은다.
+export function removeAppFiles(targetRoot, appFiles, done = []) {
+  for (const rel of appFiles) {
+    remove(join(targetRoot, rel));
+    pruneEmptyDirs(targetRoot, posix.dirname(rel));
+    done.push(["remove", "flutter-app", rel]);
+  }
+}
+
+// 설치물을 지운 뒤 비게 된 .github/workflows·.github/scripts(와 .github)를 정리한다.
+// 이번에 그 폴더에서 무언가를 지웠을 때만 — 원래 비어 있던 폴더까지 손대지 않는다.
+export function pruneInstallDirs(targetRoot, plan) {
+  if (plan.workflows.length || plan.baseline?.length) pruneEmptyDirs(targetRoot, PATHS.workflowsDir);
+  if (plan.scripts.length) pruneEmptyDirs(targetRoot, PATHS.scriptsDir);
+}
 
 // selection: { workflows, scripts, readme, gitignore, versionYml } (모두 boolean).
 // 반환: 위와 동일한 키의 boolean/배열 — 실제로 제거 "대상"인지 여부(순수 함수, 아무것도 지우지 않음).
@@ -17,11 +48,16 @@ export function planUninstall(payloadRoot, targetRoot, selection) {
   const removalPlan = planRemoval(payloadRoot, targetRoot);
   return {
     workflows: selection.workflows ? removalPlan.workflows : [],
-    // baseline은 워크플로우 해시 기록 — 워크플로우를 지우면 함께 사라져야 한다
+    // baseline은 워크플로우 해시 기록 — 워크플로우를 지우면 함께 사라져야 한다.
+    // Flutter 앱 파일의 생성 기록도 baseline에만 있으므로 같은 항목으로 묶는다.
+    appFiles: selection.workflows ? removalPlan.appFiles : [],
     baseline: selection.workflows ? removalPlan.baseline : [],
     scripts: selection.scripts ? removalPlan.scripts : [],
     readme: selection.readme ? hasVersionSection(targetRoot) : false,
-    gitignore: selection.gitignore ? hasAutoAddedEntries(targetRoot) : false,
+    // 워크플로우를 남기면 그 백업 파일(.bak 등)도 남는다 — .gitignore 항목을 지우면 git 상태에 드러나므로 유지한다.
+    gitignore: selection.gitignore
+      ? hasAutoAddedEntries(targetRoot) && (selection.workflows || backupArtifacts(removalPlan.workflows).length === 0)
+      : false,
     versionYml: selection.versionYml ? existsSync(join(targetRoot, PATHS.versionFile)) : false,
   };
 }
@@ -30,16 +66,22 @@ export function planUninstall(payloadRoot, targetRoot, selection) {
 export function runUninstall(context, payloadRoot, targetRoot, selection) {
   const plan = planUninstall(payloadRoot, targetRoot, selection);
   const wfDir = join(targetRoot, PATHS.workflowsDir);
-  for (const name of plan.workflows) { remove(join(wfDir, name)); log.info("remove", "workflow", name); }
-  for (const name of plan.scripts) { remove(join(targetRoot, PATHS.scriptsDir, name)); log.info("remove", "script", name); }
-  for (const p of plan.baseline || []) { remove(join(targetRoot, p)); log.info("remove", "metadata", p); }
+  const done = [];
+  for (const name of plan.workflows) { remove(join(wfDir, name)); done.push(["remove", "workflow", name]); }
+  for (const name of plan.scripts) { remove(join(targetRoot, PATHS.scriptsDir, name)); done.push(["remove", "script", name]); }
+  removeAppFiles(targetRoot, plan.appFiles, done);
+  for (const p of plan.baseline || []) { remove(join(targetRoot, p)); done.push(["remove", "metadata", p]); }
+  pruneInstallDirs(targetRoot, plan);
   // removeVersionSectionFromReadme/removeAutoAddedEntriesFromGitignore는 plan이 "제거 대상"으로
   // 판단했더라도 실제로는 안전하게 포기(skip-*)할 수 있다 — 반환 상태를 그대로 신뢰하지 않고
   // 실제 결과로 plan을 덮어써서 호출부(CLI/대화형 요약)가 거짓 성공을 보고하지 않게 한다.
   const readmeRemoved = plan.readme && removeVersionSectionFromReadme(targetRoot) === "removed";
   const gitignoreStatus = plan.gitignore ? removeAutoAddedEntriesFromGitignore(targetRoot) : null;
   const gitignoreRemoved = gitignoreStatus === "removed" || gitignoreStatus === "file-deleted";
-  if (plan.versionYml) { remove(join(targetRoot, PATHS.versionFile)); log.info("remove", "version", PATHS.versionFile); }
+  if (readmeRemoved) done.push(["remove", "readme", "README.md 버전 섹션"]);
+  if (gitignoreStatus) done.push(["remove", "gitignore", `.gitignore 자동 추가 항목 (${gitignoreStatus})`]);
+  if (plan.versionYml) { remove(join(targetRoot, PATHS.versionFile)); done.push(["remove", "version", PATHS.versionFile]); }
+  logRemovals(targetRoot, done);
   return { ...plan, readme: readmeRemoved, gitignore: gitignoreRemoved };
 }
 
@@ -47,7 +89,8 @@ export function runUninstall(context, payloadRoot, targetRoot, selection) {
 const ITEM_DEFS = [
   // .github/.wizard 에는 baseline.json과 설치 로그(.wizard/logs)가 함께 들어 있다 —
   // 워크플로우를 지우면 함께 사라지므로 라벨에 명시한다.
-  { key: "workflows", label: "워크플로우 (.github/workflows/PROJECT-*.yaml) + 설치 기록 (.github/.wizard)" },
+  // Flutter 앱 파일은 마법사가 만들고 사용자가 수정하지 않은 것만 함께 지운다.
+  { key: "workflows", label: "워크플로우 (.github/workflows/PROJECT-*.yaml) + 설치 기록 (.github/.wizard) + 수정하지 않은 Flutter 앱 파일" },
   { key: "scripts", label: "스크립트 (.github/scripts/*.py)" },
   { key: "readme", label: "README.md 버전 섹션 (AUTO-VERSION-SECTION)" },
   { key: "gitignore", label: ".gitignore 자동 추가 항목" },
@@ -87,6 +130,7 @@ function summarizeResult(result) {
   const lines = [];
   if (result.workflows.length) lines.push(`워크플로우 ${result.workflows.length}개 제거`);
   if (result.scripts.length) lines.push(`스크립트 ${result.scripts.length}개 제거`);
+  if (result.appFiles?.length) lines.push(`Flutter 앱 파일 ${result.appFiles.length}개 제거`);
   if (result.readme) lines.push("README.md 버전 섹션 제거");
   if (result.gitignore) lines.push(".gitignore 자동 추가 항목 제거");
   if (result.versionYml) lines.push("version.yml 제거");
@@ -95,7 +139,8 @@ function summarizeResult(result) {
 
 // io 계약: engineIo.multiselect({message,options,initialValues}), askYesNo(msg,def),
 // note(text,title)?, cancelMessage(text)? — src/ui/prompts.js가 실물, 테스트는 스텁 주입.
-export async function runUninstallFlow(payloadRoot, targetRoot, io) {
+// preset: CLI의 --purge-* 플래그 { readme, gitignore, versionYml } — 체크리스트 초기 선택에 반영한다.
+export async function runUninstallFlow(payloadRoot, targetRoot, io, preset = {}) {
   const available = detectAvailableItems(payloadRoot, targetRoot);
   if (available.length === 0) {
     io.note?.("제거할 항목이 없습니다.", "완전 삭제");
@@ -105,7 +150,7 @@ export async function runUninstallFlow(payloadRoot, targetRoot, io) {
   const checked = await io.engineIo.multiselect({
     message: "삭제할 항목을 선택하세요 (Space 토글, Enter 확정)",
     options: available,
-    initialValues: available.map((o) => o.value).filter((v) => SAFE_ITEMS.includes(v)),
+    initialValues: available.map((o) => o.value).filter((v) => SAFE_ITEMS.includes(v) || preset[v] === true),
   });
   if (checked === CANCEL || !Array.isArray(checked) || checked.length === 0) {
     io.cancelMessage?.("완전 삭제를 취소했습니다.");

package/src/context.js

@@ -1,8 +1,8 @@
-// 마법사 전역 상태를 하나의 객체로 명시화 (bash 전역 변수군 대체)
-export const VALID_TYPES = [
-  "spring", "flutter", "next", "react",
-  "react-native", "react-native-expo", "node", "python", "basic", "go",
-];
+// 마법사 전역 상태를 하나의 객체로 명시화
+import { TYPE_IDS } from "./core/types.js";
+
+// --type 화이트리스트 — 타입 레지스트리(core/types.js)의 표시 순서 그대로.
+export const VALID_TYPES = TYPE_IDS;
 
 // --mode 화이트리스트 — 알 수 없는 값은 부수효과(브랜치 조회 등) 이전에 즉시 거부해야 한다.
 // purge는 --help/대화형 메뉴에 노출하지 않는 숨김 모드이지만 검증 대상에는 포함한다.

package/src/core/baseline.js

@@ -7,7 +7,7 @@
 //
 // 파일 사본이 아니라 해시만 남긴다 — 분류가 목적이지 자동 병합이 목적이 아니다.
 //
-// 해시를 두 개 두는 이유(이슈 원안은 하나였다): env 치환으로 사용자 값이 들어간 파일은
+// 해시를 두 개 두는 이유: env 치환으로 사용자 값이 들어간 파일은
 // 디스크 내용과 "기본값으로 렌더한 결과"가 애초에 다르다. 하나로는 두 질문에 동시에 답할 수 없다.
 //   - installed : 설치 시점 우리가 디스크에 쓴 내용     → "사용자가 그 뒤에 손댔는가"
 //   - rendered  : 그 시점 payload를 기본값 치환한 결과  → "업스트림이 그 뒤에 바뀌었는가"
@@ -26,6 +26,12 @@ export function sha256(text) {
   return "sha256:" + createHash("sha256").update(String(text), "utf8").digest("hex");
 }
 
+// Flutter 앱 파일(Fastfile·ExportOptions.plist) 해시 — 체크아웃 줄바꿈(autocrlf)만 달라진 파일을
+// "사용자가 수정했다"로 보지 않도록 LF로 맞춘 뒤 해시한다.
+export function appFileHash(text) {
+  return sha256(String(text).replace(/\r\n/g, "\n"));
+}
+
 // 없거나 깨졌으면 null — 호출부는 "base 미상"으로 폴백한다(조용히 빈 baseline을 쓰지 않는다.
 // 빈 baseline은 "기록이 없다"가 아니라 "전부 삭제됐다"로 오해될 수 있다).
 export function readBaseline(targetRoot = ".") {
@@ -40,22 +46,31 @@ export function readBaseline(targetRoot = ".") {
   }
 }
 
-// entries: Map<filename, {installed?:string|null, rendered:string}>
+// entries: Map<filename, {installed?:string|null, rendered?:string|null}>
+// appFiles: Map<레포 기준 상대경로, appFileHash> — 이번에 새로 만든 Flutter 앱 파일. 완전 삭제가
+//   "마법사가 만들었고 사용자가 손대지 않은 파일"만 지우는 근거다. files는 워크플로우 파일명 키라 섞지 않는다.
 // 기존 baseline은 병합 대상이다 — 이번 실행에서 건드리지 않은 파일의 기준점을 잃지 않는다.
-export function writeBaseline(targetRoot, { templateVersion, installedAt, entries, previous = null }) {
+export function writeBaseline(targetRoot, { templateVersion, installedAt, entries, previous = null, appFiles = new Map() }) {
   const files = { ...(previous?.files || {}) };
   for (const [filename, entry] of entries) {
     const prev = files[filename] || {};
     files[filename] = {
       // installed는 이번에 실제로 쓴 경우에만 갱신. 유지(skip)한 파일은 예전 기준점을 지킨다.
       installed: entry.installed ?? prev.installed ?? null,
-      rendered: entry.rendered,
+      // rendered가 없으면(충돌로 업스트림 변경을 받지 않은 파일) 예전 기준점을 지킨다.
+      rendered: entry.rendered ?? prev.rendered ?? null,
     };
   }
+  const apps = { ...(previous?.appFiles || {}), ...Object.fromEntries(appFiles) };
+  // 기준점이 하나도 바뀌지 않은 재실행은 설치 시각도 그대로 둔다 — 매 실행마다 파일이 바뀌면 멱등이 아니다.
+  const unchanged = previous && previous.templateVersion === (templateVersion || "unknown")
+    && JSON.stringify(previous.files) === JSON.stringify(files)
+    && JSON.stringify(previous.appFiles || {}) === JSON.stringify(apps);
   const out = {
     templateVersion: templateVersion || "unknown",
-    installedAt: installedAt || "",
+    installedAt: unchanged ? (previous.installedAt || "") : (installedAt || ""),
     files,
+    ...(Object.keys(apps).length ? { appFiles: apps } : {}),
   };
   writeText(join(targetRoot, BASELINE_PATH), JSON.stringify(out, null, 2) + "\n");
   return out;

package/src/core/branches.js

@@ -1,4 +1,4 @@
-// 브랜치 구성 (DESIGN-SPEC §4 신규 질문 ①).
+// 브랜치 구성 — main/develop 브랜치와 pr-flow·trunk-based 모드.
 // on: push: branches: 는 YAML 정적 값 — 마법사가 릴리스/개발 브랜치를 물어(또는 플래그로 받아)
 // {{MAIN_BRANCH}}/{{DEVELOP_BRANCH}} 플레이스홀더를 치환한다 (치환 자체는 branding.js).
 // main === develop 이면 trunk-based 모드 → RELEASE-PUBLISH 단독 설치.
@@ -26,6 +26,24 @@ export async function detectRemoteBranches(cwd, exec = defaultExec) {
     .filter((s, i, a) => a.indexOf(s) === i);
 }
 
+// 브랜치 이름 검증 — git check-ref-format --branch 규칙에 더해, 워크플로우 YAML·셸 명령에 그대로
+// 치환되는 값이라 공백·괄호·따옴표 같은 셸 특수문자도 거부한다. 빈 원격이 돌려주는 "(unknown)" 같은
+// 감지 실패 값이나 공백만 입력한 값이 트리거에 기록되면 워크플로우가 영영 돌지 않는다.
+export function isValidBranchName(name) {
+  if (typeof name !== "string" || name === "") return false;
+  if (/[\s~^:?*[\\\x00-\x1f\x7f()"'`$;&|<>!{}]/.test(name)) return false;
+  if (name.startsWith("-") || name.startsWith("/") || name.endsWith("/")) return false;
+  if (name.endsWith(".") || name.endsWith(".lock") || name === "@") return false;
+  if (name.includes("..") || name.includes("//") || name.includes("@{")) return false;
+  return !name.split("/").some((part) => part.startsWith("."));
+}
+
+// 원격에 브랜치가 하나도 없거나(빈 원격·origin 없음) develop 생성을 건너뛴 경우의 안내.
+// develop이 없으면 pr-flow 워크플로우가 트리거되지 않으므로 조용히 넘어가면 안 된다.
+export function developMissingNotice({ main, develop }) {
+  return `원격에 '${develop}' 브랜치가 없습니다 — 설치 파일을 커밋해 '${main}'을 push한 뒤 만들어 주세요: git push origin ${main}:${develop}`;
+}
+
 // 결정 (순수 함수): 플래그/답변 → 최종 구성.
 // 우선순위: 명시값(mainBranch/developBranch) → 감지 default → 하드 폴백(main/develop).
 export function resolveBranchConfig({ mainBranch = "", developBranch = "", defaultBranch = "" } = {}) {

package/src/core/branding.js

@@ -1,4 +1,4 @@
-// 브랜치 플레이스홀더 치환 파이프라인 (DESIGN-SPEC §4).
+// 브랜치 플레이스홀더 치환 파이프라인.
 // payload 워크플로우의 {{MAIN_BRANCH}}/{{DEVELOP_BRANCH}}를 설치 시 실제 브랜치명으로 바꾼다.
 // ⚠️ GitHub Actions 표현식 `${{ ... }}`은 우리 토큰이 아니다 — `$` 선행 시 제외(lookbehind).
 // 치환 후 알 수 없는 {{TOKEN}}이 남으면 throw — 복사 무결성 가드 (오타·누락 조기 검출).

package/src/core/breaking-check.js

@@ -1,45 +1,40 @@
-// breaking-changes 확인 흐름 배선 (.sh check_breaking_changes L2506~2616 등가).
-// collectBreaking(순수 비교)은 breaking.js — 이 모듈은 로드(원격→clone본 폴백)·표시·확인 게이트.
+// breaking-changes 확인 흐름 배선.
+// collectBreaking(순수 비교)은 breaking.js — 이 모듈은 로드(패키지 번들본)·표시·확인 게이트.
 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 { /* 원격 실패 — 폴백 */ }
+// 패키지에 동봉된 payload/config 번들본만 읽는다. 원격(main)을 읽으면 같은 패키지 버전이라도
+// 실행 시점마다 결과가 달라지고 설치 중 네트워크 요청이 생긴다. 읽기 실패 시 null(조용히 스킵).
+export function loadBreakingJson(payloadRoot) {
   try {
     const p = join(payloadRoot, "config", "breaking-changes.json");
     if (existsSync(p)) return JSON.parse(readFileSync(p, "utf8"));
-  } catch { /* 폴백 실패 — 스킵 */ }
+  } catch { /* 번들 읽기 실패 — 스킵 */ }
   return null;
 }
 
 // 반환: true=진행, false=사용자 취소.
 // opts:
 //   cwd             - 통합 대상 루트 (기존 version.yml에서 현재 템플릿 버전 읽음)
-//   payloadRoot     - 패키지 payload/ 루트 (번들 폴백용)
-//   templateVersion - 설치하려는 템플릿 버전 (.sh의 DEFAULT_VERSION 고정 버그를 실버전으로 교정)
+//   payloadRoot     - 패키지 payload/ 루트 (번들 breaking-changes.json 위치)
+//   templateVersion - 설치하려는 템플릿 버전 (고정값이 아니라 실제 패키지 버전)
 //   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 { templateVersion: current, types } = parseExisting(readFileSync(vy, "utf8"));
+  if (!current) return true; // 템플릿 메타 없음(unknown) — 비교 기준이 없어 스킵
 
   const json = await loader(payloadRoot);
   if (!json) return true;
 
-  const { critical, warnings } = collectBreaking(json, current, templateVersion);
+  const { critical, warnings } = collectBreaking(json, current, templateVersion, types);
   if (critical.length === 0 && warnings.length === 0) return true;
 
-  // 박스 표시 (.sh L2580~2603)
+  // 박스 표시
   const e = (s = "") => process.stderr.write(s + "\n");
   e("");
   e("╔══════════════════════════════════════════════════════════════════╗");
@@ -53,11 +48,11 @@ export async function runBreakingCheck({ cwd, payloadRoot, templateVersion, askY
 
   if (critical.length > 0) {
     if (askYesNo) {
-      // 대화형: 명시 확인 없으면 중단 (기본 N — .sh 등가)
+      // 대화형: 명시 확인 없으면 중단 (기본 N)
       const ok = await askYesNo("위 호환성 변경을 확인했고 계속 진행할까요?", false);
       if (ok !== true) return false;
     } else {
-      // 비대화형(--force): 게이트로 CI를 죽이지 않고 경고 후 진행 (.sh와 의도적 차이 — CI 친화)
+      // 비대화형(--force): 게이트로 CI를 죽이지 않고 경고 후 진행 (CI 친화)
       e("⚠️  CRITICAL 호환성 변경이 있습니다 — 비대화형 실행이라 계속 진행합니다. 위 내용을 꼭 확인하세요.");
     }
   }

package/src/core/breaking.js

@@ -1,4 +1,4 @@
-// .sh compare_versions 등가: v 접두 제거, 3자리 숫자 비교, 누락 자리=0
+// 버전 비교: v 접두 제거, 3자리 숫자 비교, 누락 자리=0
 export function compareVersions(a, b) {
   const parse = (v) => String(v).replace(/^v/, "").split(".").map((n) => parseInt(n, 10) || 0);
   const pa = parse(a), pb = parse(b);
@@ -11,16 +11,20 @@ export function compareVersions(a, b) {
 }
 
 // breaking-changes.json에서 current < ver <= target 범위 항목 수집.
-// ⚠️ .sh 버그 수정: target은 하드코딩 1.3.14가 아니라 실제 templateVersion을 넘긴다.
+// target은 고정값이 아니라 실제 templateVersion을 넘긴다 — 그래야 설치하려는 버전까지의 고지가 모두 잡힌다.
 // _ 로 시작하는 키(메타) 제외. severity critical / 그 외(warning).
 // 버전 키의 값은 항목 객체 또는 항목 객체의 배열(같은 릴리스에 고지가 여러 건일 때).
-export function collectBreaking(json, current, target) {
+// types: 설치된 프로젝트 타입. 항목에 types가 있으면 겹치는 타입이 있을 때만 보여준다 — spring 레포에
+// Flutter 전용 경고가 뜨면 진짜 알려야 할 고지가 묻힌다. types를 모르면(빈 배열) 전부 보여준다.
+export function collectBreaking(json, current, target, types = []) {
   const critical = [], warnings = [];
+  const relevant = (entry) => !Array.isArray(entry?.types) || !types.length || entry.types.some((t) => types.includes(t));
   for (const [ver, value] of Object.entries(json || {})) {
     if (ver.startsWith("_")) continue;
     if (compareVersions(current, ver) < 0 && compareVersions(ver, target) <= 0) {
       // 한 릴리스에 고지가 여러 건이면 배열로 등록한다 — JSON 키(버전)는 유일해서 객체로는 한 건만 담긴다.
       for (const entry of Array.isArray(value) ? value : [value]) {
+        if (!relevant(entry)) continue;
         const rec = { version: ver, ...entry };
         (entry?.severity === "critical" ? critical : warnings).push(rec);
       }

package/src/core/copy/gitignore.js

@@ -14,7 +14,7 @@ import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
 // 실제로 만들어내는 부산물만 gitignore 대상으로 삼는다.
 const REQUIRED_ENTRIES = ["*.bak", "*.template.yaml"];
 
-// .sh normalize_gitignore_entry: 주석 제거·트림·앞 / 제거·앞 ./ 제거·뒤 / 제거. 빈값이면 원본.
+// 항목 정규화: 주석 제거·트림·앞 / 제거·앞 ./ 제거·뒤 / 제거. 빈값이면 원본.
 export function normalizeGitignoreEntry(entry) {
   let e = String(entry);
   e = e.replace(/#.*$/, "");        // 주석 제거
@@ -40,23 +40,31 @@ const NEW_FILE_CONTENT =
   "*.bak\n" +
   "*.template.yaml\n";
 
+// 쓰지 않고 판정만 한다 — 실제 갱신과 --dry-run 미리보기가 같은 판정을 쓰게 한다.
+// 반환: {created, added:[...]}
+export function planGitignore(targetRoot = ".") {
+  const p = join(targetRoot, ".gitignore");
+  if (!existsSync(p)) return { created: true, added: REQUIRED_ENTRIES.slice() };
+  const content = readFileSync(p, "utf8");
+  return { created: false, added: REQUIRED_ENTRIES.filter((e) => !entryExists(e, content)) };
+}
+
 // 반환: {created, added:[...]}
 export function ensureGitignore(targetRoot = ".") {
   const p = join(targetRoot, ".gitignore");
-  if (!existsSync(p)) {
+  const plan = planGitignore(targetRoot);
+  if (plan.created) {
     writeFileSync(p, NEW_FILE_CONTENT);
-    return { created: true, added: REQUIRED_ENTRIES.slice() };
+    return plan;
   }
+  const toAdd = plan.added;
+  if (toAdd.length === 0) return plan;
   let content = readFileSync(p, "utf8");
-  const toAdd = REQUIRED_ENTRIES.filter((e) => !entryExists(e, content));
-  if (toAdd.length === 0) return { created: false, added: [] };
 
-  // 파일 끝에 개행 없으면 추가 (.sh: tail -c 1 이 non-empty면 echo "")
-  if (content.length > 0 && !content.endsWith("\n")) content += "\n";
-  content += "\n";
-  content += "# ====================================================================\n";
-  content += "# project-auto-wizard: Auto-added entries\n";
-  content += "# ====================================================================\n";
+  // BANNER는 "\n"으로 시작한다. 파일 끝에 개행이 없으면 그 "\n"이 마지막 줄을 끝내는 역할을 하고,
+  // 개행이 있으면 빈 줄 하나가 된다. 어느 쪽이든 제거 시 BANNER 앞까지 자르면 원문 그대로 돌아온다.
+  // (개행을 따로 보충하면 제거 후에도 원래 없던 끝 개행이 남는다.)
+  content += BANNER;
   for (const e of toAdd) content += e + "\n";
   content += BANNER_END;
   writeFileSync(p, content);
@@ -64,7 +72,7 @@ export function ensureGitignore(targetRoot = ".") {
 }
 
 // ensureGitignore가 기존 파일에 배너 블록을 추가할 때 항상 이 정확한 시퀀스로 시작한다
-// (빈 줄 하나 + 3줄 배너), 그리고 REQUIRED_ENTRIES 뒤에 BANNER_END로 끝난다. 배너~BANNER_END
+// ("\n" + 3줄 배너), 그리고 REQUIRED_ENTRIES 뒤에 BANNER_END로 끝난다. 배너~BANNER_END
 // 범위 안에서 REQUIRED_ENTRIES와 일치하는 줄만 개별 제거하고, 사용자가 그 사이/뒤에 추가한
 // 줄은 절대 건드리지 않는다.
 const BANNER =

package/src/core/copy/readme.js

@@ -1,4 +1,4 @@
-// README 버전 섹션 추가 (.sh add_version_section_to_readme 등가) — template_integrator.sh 2145~2181.
+// README 버전 섹션 추가.
 import { join } from "node:path";
 import { existsSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
 
@@ -6,17 +6,33 @@ export const MARKER = "<!-- AUTO-VERSION-SECTION";
 // ## (최신 버전|최신버전|Version|버전) : vX.Y.Z (대소문자 무시)
 const VERSION_LINE_RE = /##\s*(최신\s*버전|최신버전|Version|버전)\s*:\s*v[0-9]+\.[0-9]+\.[0-9]+/i;
 
+// 실행 로그용 설명 — 상태 코드만 남기면 나중에 로그를 읽는 사람이 의미를 다시 찾아봐야 한다.
+export const README_STATUS_LABEL = {
+  added: "README.md 끝에 버전 섹션 추가",
+  "skip-no-readme": "README.md가 없어 버전 섹션을 추가하지 않음",
+  "skip-marker": "이미 버전 섹션이 있어 그대로 둠",
+  "skip-version-line": "이미 버전 줄이 있어 그대로 둠",
+};
+
 // README.md 없으면 스킵. 마커 또는 버전 라인 있으면 스킵. 없으면 파일 끝에 append.
 // 반환: 'skip-no-readme' | 'skip-marker' | 'skip-version-line' | 'added'
-export function addVersionSectionToReadme(version, targetRoot = ".") {
+// 쓰지 않고 판정만 한다 — 실제 추가와 --dry-run 미리보기가 같은 판정을 쓰게 한다.
+export function planVersionSection(targetRoot = ".") {
   const p = join(targetRoot, "README.md");
   if (!existsSync(p)) return "skip-no-readme";
   const content = readFileSync(p, "utf8");
   if (content.includes(MARKER)) return "skip-marker";
   if (VERSION_LINE_RE.test(content)) return "skip-version-line";
+  return "added";
+}
+
+export function addVersionSectionToReadme(version, targetRoot = ".") {
+  const status = planVersionSection(targetRoot);
+  if (status !== "added") return status;
+  const p = join(targetRoot, "README.md");
+  const content = readFileSync(p, "utf8");
 
-  // .sh: cat >> README.md << EOF — EOF 다음 첫 줄이 빈 줄이므로 append 본문은 "\n---\n..."로 시작.
-  // (원본 파일이 개행으로 끝난다는 전제는 .sh와 동일 — heredoc은 원본 끝에 그대로 붙는다.)
+  // 기존 본문과 구분선 사이에 빈 줄을 두도록 append 본문은 "\n---\n..."로 시작.
   const section =
     "\n" +
     "---\n" +
@@ -25,7 +41,10 @@ export function addVersionSectionToReadme(version, targetRoot = ".") {
     `## 최신 버전 : v${version}\n` +
     "\n" +
     "[전체 버전 기록 보기](CHANGELOG.md)\n";
-  appendFileSync(p, section);
+  // 끝 개행이 없는 README에 그대로 붙이면 마지막 줄 바로 다음 줄에 "---"가 와서
+  // 마크다운이 그 줄을 제목(Setext h2)으로 바꿔 버린다 — 줄을 먼저 끝낸다.
+  const lead = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+  appendFileSync(p, lead + section);
   return "added";
 }
 

package/src/core/copy/simple.js

@@ -2,22 +2,61 @@
 // payload 단일 진실: 스크립트는 payload/scripts/*.py → 사용자 레포 .github/scripts/ 로 설치된다.
 // 워크플로우 전부가 이 경로(python3 .github/scripts/*.py)를 호출하므로 누락 시 설치물이 런타임에 죽는다.
 import { join } from "node:path";
-import { chmodSync } from "node:fs";
+import { chmodSync, readFileSync, readdirSync, rmSync, rmdirSync } from "node:fs";
 import { PATHS, PAYLOAD } from "../paths.js";
 import { exists, copyFileSync } from "../fsutil.js";
 
-// version_manager.py, changelog_manager.py, truncate_release_notes.py 무조건 덮어쓰기 (+chmod — Windows에선 무의미하나 무해).
+export const SCRIPT_NAMES = ["version_manager.py", "changelog_manager.py", "truncate_release_notes.py", "issue_helper.py"];
+
+// 파일별로 무엇이 일어날지 계산한다(아무것도 쓰지 않음) — 실제 복사와 --dry-run이 같은 판정을 쓴다.
+// 반환: [{ name, action: "create" | "overwrite" | "unchanged" }]
+export function planScripts(payloadRoot, targetRoot = ".") {
+  const out = [];
+  for (const name of SCRIPT_NAMES) {
+    const src = join(payloadRoot, PAYLOAD.scriptsDir, name);
+    if (!exists(src)) continue;
+    const dst = join(targetRoot, PATHS.scriptsDir, name);
+    const action = !exists(dst) ? "create"
+      : readFileSync(dst).equals(readFileSync(src)) ? "unchanged" : "overwrite";
+    out.push({ name, action });
+  }
+  return out;
+}
+
+// 스크립트는 항상 payload 버전으로 덮어쓴다 (+chmod — Windows에선 무의미하나 무해).
+// 사용자가 고친 스크립트도 덮이므로, 호출부가 로그에 남길 수 있게 파일별 결과를 돌려준다.
 export function copyScripts(payloadRoot, targetRoot = ".") {
-  const scripts = ["version_manager.py", "changelog_manager.py", "truncate_release_notes.py", "issue_helper.py"];
-  let copied = 0;
-  for (const s of scripts) {
-    const src = join(payloadRoot, PAYLOAD.scriptsDir, s);
-    if (exists(src)) {
-      const dst = join(targetRoot, PATHS.scriptsDir, s);
-      copyFileSync(src, dst);
-      try { chmodSync(dst, 0o755); } catch { /* Windows 등 chmod 무의미 */ }
-      copied++;
-    }
+  const results = planScripts(payloadRoot, targetRoot);
+  for (const { name } of results) {
+    const dst = join(targetRoot, PATHS.scriptsDir, name);
+    copyFileSync(join(payloadRoot, PAYLOAD.scriptsDir, name), dst);
+    try { chmodSync(dst, 0o755); } catch { /* Windows 등 chmod 무의미 */ }
+  }
+  return results;
+}
+
+// 예전 버전의 워크플로우는 스크립트 import가 남긴 바이트코드를 봇 커밋에 섞어 올렸다.
+// 지금은 생성 자체를 막지만 이미 커밋된 pyc는 업데이트로 사라지지 않으므로 여기서 지운다.
+// 범위는 마법사 스크립트 폴더의 pyc와 그 __pycache__뿐이다 — 다른 경로는 건드리지 않는다.
+// 반환: 지울(지운) 파일의 targetRoot 기준 상대 경로 목록 — 삭제는 사용자가 설치 파일과 함께 커밋한다
+export function planScriptBytecode(targetRoot = ".") {
+  const base = join(targetRoot, PATHS.scriptsDir);
+  const list = (rel) => {
+    try {
+      return readdirSync(join(base, rel), { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith(".pyc"))
+        .map((e) => [PATHS.scriptsDir, rel, e.name].filter(Boolean).join("/"));
+    } catch { return []; }
+  };
+  return [...list(""), ...list("__pycache__")];
+}
+
+export function removeScriptBytecode(targetRoot = ".") {
+  const removed = planScriptBytecode(targetRoot);
+  for (const rel of removed) rmSync(join(targetRoot, rel), { force: true });
+  if (removed.some((rel) => rel.includes("/__pycache__/"))) {
+    // 비었을 때만 지운다 — 다른 파일이 있으면 그대로 둔다
+    try { rmdirSync(join(targetRoot, PATHS.scriptsDir, "__pycache__")); } catch { /* 비어 있지 않음 */ }
   }
-  return copied;
+  return removed;
 }