project-auto-wizard 0.12.2 → 0.13.1

package/src/cli/help.js

@@ -1,3 +1,16 @@
+import { TYPE_IDS } from "../core/types.js";
+
+// 지원 타입 목록 — 레지스트리 순서대로 한 줄 40자 안쪽에서 줄바꿈하고, 이어지는 줄은 "지원: " 뒤에 맞춘다.
+function typeListLines(width = 40) {
+  const lines = [];
+  for (const id of TYPE_IDS) {
+    const last = lines.length - 1;
+    if (last >= 0 && lines[last].length + 1 + id.length <= width) lines[last] += ` ${id}`;
+    else lines.push(id);
+  }
+  return lines.join(`\n${" ".repeat(33)}`);
+}
+
 // --help 텍스트.
 export const HELP_TEXT = `project-auto-wizard — One command DevOps: GitHub-native 릴리스 자동화 설치 마법사
 
@@ -10,8 +23,7 @@ export const HELP_TEXT = `project-auto-wizard — One command DevOps: GitHub-nat
                            uninstall = 완전 삭제(대화형 체크리스트, --force 시 --purge-*로 opt-in)
                            status = 설치 상태·드리프트 확인(읽기 전용). doctor = 환경 진단(읽기 전용)
   -t, --type CSV           프로젝트 타입 csv (예: spring,react,python)
-                           지원: spring flutter next react react-native
-                                 react-native-expo node python basic go
+                           지원: ${typeListLines()}
       --project-version V  통합 대상의 초기 버전 (예: 1.0.0). 미지정 시 자동 감지
       --paths "t=p,..."    타입별 프로젝트 경로 (모노레포). 예: flutter=app,react=client
       --main-branch B      릴리스 브랜치 (기본: 감지된 default branch)
@@ -23,7 +35,7 @@ export const HELP_TEXT = `project-auto-wizard — One command DevOps: GitHub-nat
       --ios-deploy-mode MODE         iOS 배포 모드: store_only | store_prepare | store_submit (기본: store_only)
       --semver-auto / --no-semver-auto  커밋 타입 기반 자동 major/minor/patch 승격 (기본: 사용함)
       --copilot / --no-copilot  Copilot으로 AI 요약 생성 (기본: 사용 안 함, GitHub Copilot AI Credits 소비)
-      --force              full 실행에 필수 (모든 확인 생략, 비대화형 기본값 사용)
+      --force              full 실행에 필수, uninstall은 비대화형 삭제 (모든 확인 생략, 기본값 사용)
       --dry-run            실제 파일 변경 없이 무엇이 바뀔지만 미리 보여줌 (full/uninstall 지원)
       --purge-readme        --mode uninstall --force 시 README.md 버전 섹션도 제거
       --purge-gitignore     --mode uninstall --force 시 .gitignore 자동 추가 항목도 제거
@@ -33,7 +45,7 @@ export const HELP_TEXT = `project-auto-wizard — One command DevOps: GitHub-nat
 
 예시:
   npx project-auto-wizard --mode full --force --type spring,react
-  npx project-auto-wizard --mode workflows --force --type flutter --paths "flutter=app"
+  npx project-auto-wizard --mode full --force --type flutter --paths "flutter=app"
   npx project-auto-wizard --mode status
   npx project-auto-wizard --mode doctor
   npx project-auto-wizard --mode full --force --type node --dry-run

package/src/commands/doctor.js

@@ -1,5 +1,4 @@
 // doctor 명령 — 로컬 환경 진단(읽기 전용, 규칙 기반). gh CLI에 위임해 원격 상태를 점검한다.
-// AI 진단은 포함하지 않는다(스펙 §4에서 검토 후 기각 — 복잡도 대비 이득 낮음).
 //
 // 출력 설계 — `flutter doctor` 패턴을 차용한다.
 //   ① 항목 라벨에 purpose("무엇을 위한 설정인지")를 병기한다. `WORKFLOW_PAT`만 보고는 그게
@@ -12,22 +11,21 @@
 //      않는다. 번역하면 설명은 읽히지만 정작 화면에서 그 항목을 찾지 못한다.
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { join, posix } from "node:path";
+import { join } from "node:path";
 import { A, paint, colorEnabled, visualWidth } from "../ui/ansi.js";
 import { PATHS } from "../core/paths.js";
 import { parseExisting } from "../core/version-yml.js";
-import { STORE_PLATFORMS, STORE_APP_FILES, parseStoreList, storeAppFilesFor } from "../core/flutter-options.js";
-import { inferInstalledStores } from "../core/installed-stores.js";
+import { hooksFor } from "../core/types.js";
 
 const defaultExec = (cmd, args) => spawnSync(cmd, args, { encoding: "utf8" });
 
-// 해결 가이드 링크 (스펙 2026-07-25-osscontest-scope-design.md §3.3② "각 실패 항목에 대한
-// 해결 가이드 링크(README 앵커)"). README에 심은 영문 HTML 앵커를 가리킨다 — 한글 헤딩
+// 해결 가이드 링크. 문서 사이트 페이지 안의 영문 HTML 앵커를 가리킨다 — 한글 헤딩
 // 자동 앵커는 URL 인코딩되어 터미널에서 알아볼 수 없게 깨진다.
-const REPO_URL = "https://github.com/Twin-Fang/project-auto-wizard";
+// 진단 출력이 한국어이므로 한국어 페이지(/ko/)로 연결한다.
+export const DOCS_SITE_URL = "https://twin-fang.github.io/project-auto-wizard";
 export const DOC = {
-  postInstall: `${REPO_URL}#post-install`,
-  flutterStore: `${REPO_URL}#flutter-store`,
+  postInstall: `${DOCS_SITE_URL}/ko/start/quickstart/#post-install`,
+  flutterStore: `${DOCS_SITE_URL}/ko/project-types/flutter/#flutter-store`,
 };
 
 export function runDoctor(cwd = process.cwd(), { exec = defaultExec } = {}) {
@@ -44,8 +42,13 @@ export function runDoctor(cwd = process.cwd(), { exec = defaultExec } = {}) {
       note: ["이 폴더엔 아직 설치되지 않았습니다 — 지금 설치하면 됩니다."],
     });
 
-  // Flutter 스토어 배포 파일 점검 — 로컬 파일만 보므로 gh 조회 결과와 무관하게 수행한다.
-  if (installed) for (const item of flutterStoreChecks(cwd)) add(item);
+  // 타입별 로컬 파일 점검(예: Flutter 스토어 배포 파일) — 로컬 파일만 보므로 gh 조회 결과와 무관하게 수행한다.
+  if (installed) {
+    const existing = parseExisting(readFileSync(join(cwd, PATHS.versionFile), "utf8"));
+    for (const { hook } of hooksFor(existing.types, "doctorChecks")) {
+      for (const item of hook(cwd, existing, { docs: DOC })) add(item);
+    }
+  }
 
   const ghVersion = exec("gh", ["--version"]);
   if (ghVersion.error || ghVersion.status !== 0) {
@@ -77,7 +80,8 @@ export function runDoctor(cwd = process.cwd(), { exec = defaultExec } = {}) {
 
   const remote = exec("git", ["-C", cwd, "remote", "get-url", "origin"]);
   const url = remote.status === 0 ? (remote.stdout || "").trim() : "";
-  const match = url.match(/github\.com[:/]([^/]+)\/([^/.]+?)(\.git)?$/);
+  // 레포 이름에는 점이 올 수 있다(user.github.io, next.js) — 끝의 .git만 떼어낸다.
+  const match = url.match(/github\.com[:/]([^/]+)\/([^/]+?)(\.git)?\/?$/);
   if (!match) {
     add({
       name: "GitHub 원격", purpose: "점검 대상 레포 식별", status: "WARN",
@@ -129,7 +133,7 @@ export function runDoctor(cwd = process.cwd(), { exec = defaultExec } = {}) {
       // 파이프라인을 끝까지 이어가므로, 없는 장애를 경고로 띄우지 않는다.
       name: "WORKFLOW_PAT secret", label: "WORKFLOW_PAT", purpose: "자동 태그·Release 발행", status: "INFO",
       note: [
-        "secret이 없어도 폴백이 자동으로 이어받아 태그·Release까지 진행됩니다 — 실제 병합 후 최대 ~20초 정도 더 걸릴 뿐입니다.",
+        "secret이 없어도 폴백이 자동으로 이어받아 태그·Release 발행과 main 배포 워크플로우 실행까지 진행됩니다 — 실제 병합 후 최대 ~20초 정도 더 걸릴 뿐입니다.",
         "속도를 더 원한다면 PAT을 등록할 수 있습니다 — 반드시 개인 계정이 아닌 조직 bot/machine 계정으로 발급하세요 (scopes: repo, workflow).",
         "등록: 레포 Settings → Secrets and variables → Actions → New repository secret · 이름은 WORKFLOW_PAT",
       ],
@@ -160,11 +164,18 @@ export function runDoctor(cwd = process.cwd(), { exec = defaultExec } = {}) {
     });
   }
 
+  // 실제 설정값을 보여준다 — 켜 둔 사용자에게 "꺼져 있다"고 안내하면 현재 상태를 오해하게 된다.
+  const copilotAi = installed ? parseExisting(readFileSync(join(cwd, "version.yml"), "utf8")).options.copilotAi : null;
+  const copilotState = copilotAi === true
+    ? "켜져 있습니다 (version.yml의 copilot_ai: true)."
+    : copilotAi === false
+      ? "꺼져 있습니다 (version.yml의 copilot_ai: false) — 켜려면 --copilot으로 다시 설치하거나 대화형 '수정하기 > Copilot AI 요약'을 쓰세요."
+      : "기본은 꺼져 있습니다 (version.yml의 copilot_ai: false).";
   add({
     name: "Copilot AI 요약", label: "Copilot AI 요약", purpose: "AI 릴리스 노트 생성(선택)", status: "INFO",
     note: [
-      "기본은 꺼져 있습니다 (version.yml의 copilot_ai: false).",
-      "켜면 GitHub Copilot AI Credits가 소비됩니다 — 조직은 'Allow use of Copilot CLI billed to the organization' 정책이 필요합니다.",
+      copilotState,
+      `${copilotAi === true ? "" : "켜면 "}GitHub Copilot AI Credits가 소비됩니다 — 조직은 'Allow use of Copilot CLI billed to the organization' 정책이 필요합니다.`,
       "꺼져 있거나 사용할 수 없으면 규칙 기반 요약으로 자동 전환되므로 그대로 두셔도 됩니다.",
     ],
   });
@@ -172,51 +183,6 @@ export function runDoctor(cwd = process.cwd(), { exec = defaultExec } = {}) {
   return results;
 }
 
-const PLATFORM_ROW_NAME = { android: "Flutter Android 배포 파일", ios: "Flutter iOS 배포 파일" };
-const PLACEHOLDER_RE = /__[A-Z][A-Z0-9_]*__/g; // 감지 규칙은 ExportOptions.plist 템플릿·IOS-TESTFLIGHT 검증과 동일
-const EXPORT_OPTIONS_REL = STORE_APP_FILES.ios.find((rel) => rel.endsWith("ExportOptions.plist"));
-
-// Flutter 스토어 배포 진단 — 선택한 플랫폼의 필수 파일과 ExportOptions.plist 플레이스홀더.
-// 스토어 시크릿 등록 여부는 이번 범위 밖이다. 반환: doctor 결과 행 배열.
-function flutterStoreChecks(cwd) {
-  const existing = parseExisting(readFileSync(join(cwd, PATHS.versionFile), "utf8"));
-  if (!existing.types.includes("flutter")) return [];
-  const saved = existing.options.flutterStore == null ? null : parseStoreList(existing.options.flutterStore);
-  // 저장값 없는 기존 설치는 설치된 스토어 워크플로우로 추론한다 (interactive와 같은 규칙).
-  const stores = saved ?? inferInstalledStores(join(cwd, PATHS.workflowsDir));
-  const flutterRoot = existing.paths.get("flutter") || ".";
-  const rows = [];
-
-  for (const platform of STORE_PLATFORMS.filter((p) => stores.includes(p))) {
-    const files = storeAppFilesFor([platform]).map((rel) => posix.join(flutterRoot, rel));
-    const missing = files.filter((file) => !existsSync(join(cwd, file)));
-    const head = { name: PLATFORM_ROW_NAME[platform], purpose: "fastlane 스토어 업로드에 필요한 파일" };
-    rows.push(missing.length
-      ? {
-        ...head, status: "WARN", value: `없는 파일: ${missing.join(", ")}`,
-        impact: ["이 파일이 없으면 스토어 배포 워크플로우가 fastlane 단계에서 실패합니다."],
-        actions: ["마법사를 다시 실행하면 없는 파일만 새로 만들어 줍니다 (이미 있는 파일은 덮어쓰지 않음)"],
-        doc: DOC.flutterStore,
-      }
-      : { ...head, status: "OK", value: `${files.length}개 있음` });
-  }
-
-  const plistPath = posix.join(flutterRoot, EXPORT_OPTIONS_REL);
-  if (stores.includes("ios") && existsSync(join(cwd, plistPath))) {
-    const head = { name: "ExportOptions.plist", purpose: "iOS 서명·내보내기 설정" };
-    const left = [...new Set(readFileSync(join(cwd, plistPath), "utf8").match(PLACEHOLDER_RE) ?? [])];
-    rows.push(left.length
-      ? {
-        ...head, status: "WARN", value: `채워지지 않은 값: ${left.join(", ")}`,
-        impact: ["채우지 않으면 IOS-TESTFLIGHT 워크플로우가 ExportOptions.plist 검증 단계에서 중단됩니다."],
-        actions: [`${plistPath} 의 플레이스홀더를 실제 값(Team ID · 번들 ID · 프로비저닝 프로파일 이름)으로 바꾸세요`],
-        doc: DOC.flutterStore,
-      }
-      : { ...head, status: "OK", value: "플레이스홀더 없음" });
-  }
-  return rows;
-}
-
 const asLines = (v) => (Array.isArray(v) ? v : v ? [String(v)] : []);
 const headOf = (r) => `${r.label || r.name}${r.purpose ? ` — ${r.purpose}` : ""}`;
 

package/src/commands/dry-run.js

@@ -4,11 +4,16 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { PATHS } from "../core/paths.js";
 import { planWorkflows } from "../core/copy/workflows.js";
-import { planFlutterAppFiles } from "../core/copy/flutter-app.js";
+import { planTypeAppFiles } from "../core/copy/app-files.js";
 import { planUninstall } from "./uninstall.js";
-import { renderVersionYml, parseExisting } from "../core/version-yml.js";
+import { renderVersionYml, parseExisting, sameIgnoringTimestamps } from "../core/version-yml.js";
 import { readVersionYmlTemplate } from "../core/assets.js";
 import { existingMarkerInDir } from "../core/paths-resolve.js";
+import { planScripts } from "../core/copy/simple.js";
+import { planVersionSection } from "../core/copy/readme.js";
+import { BASELINE_PATH, readBaseline } from "../core/baseline.js";
+import { cleanupWorkflows } from "./full.js";
+import { planGitignore } from "../core/copy/gitignore.js";
 
 function versionYmlPreview(context, payloadRoot, targetRoot) {
   const { paths = new Map() } = context;
@@ -23,7 +28,8 @@ function versionYmlPreview(context, payloadRoot, targetRoot) {
   const wouldBe = renderVersionYml(context, readVersionYmlTemplate(payloadRoot), {
     pathMarkers, extraTopLevel,
   });
-  return { existed: existingRaw !== null, changed: existingRaw !== wouldBe };
+  // 실제 설치와 같은 기준으로 비교한다 — 시각 줄만 다르면 설치도 파일을 다시 쓰지 않는다.
+  return { existed: existingRaw !== null, changed: existingRaw === null || !sameIgnoringTimestamps(existingRaw, wouldBe) };
 }
 
 // mode: "full" | "uninstall". 읽기 전용 — 아무 파일도 쓰지 않는다.
@@ -31,12 +37,25 @@ export function planDryRun(mode, context, payloadRoot, targetRoot = ".") {
   if (mode === "uninstall") {
     return { mode, uninstall: planUninstall(payloadRoot, targetRoot, context.uninstallSelection) };
   }
+  const workflows = planWorkflows(context, payloadRoot, targetRoot);
+  // 실제 실행과 같은 정리 판정을 파일을 건드리지 않고 돌린다 — 배포 방식 변경·스토어 해제로 지워지거나
+  // .bak으로 옮겨질 파일이 미리보기에서 빠지면 안 된다. 비대화형 실행이 새로 쓰는 파일은 신규·자동 갱신분이다.
+  const justWritten = [...workflows.newFiles, ...workflows.upstreamOnly].map((f) => f.filename);
+  const cleanup = cleanupWorkflows(context, payloadRoot, targetRoot, readBaseline(targetRoot), { justWritten, dryRun: true });
+  // .bak이 생기면 실제 실행은 .gitignore에 백업 파일 항목을 보장한다. 비대화형 충돌은 기존 유지라 .bak을 만들지 않는다.
+  const backedUp = Object.values(cleanup).some((r) => r.backedUp.length > 0);
   return {
     mode,
-    workflows: planWorkflows(context, payloadRoot, targetRoot),
+    workflows,
+    cleanup,
+    gitignore: backedUp ? planGitignore(targetRoot) : null,
     // Flutter 스토어 배포 파일(Fastfile·ExportOptions.plist) — 이미 있는 파일은 덮어쓰지 않고 유지한다.
-    flutterApp: planFlutterAppFiles(context, payloadRoot, targetRoot),
+    flutterApp: planTypeAppFiles(context, payloadRoot, targetRoot),
     versionYml: versionYmlPreview(context, payloadRoot, targetRoot),
+    // 실제 설치가 함께 바꾸는 파일 — 특히 기존 파일을 덮어쓰는 스크립트는 미리 보여줘야 한다.
+    scripts: planScripts(payloadRoot, targetRoot),
+    readme: planVersionSection(targetRoot),
+    baselineExists: existsSync(join(targetRoot, BASELINE_PATH)),
   };
 }
 
@@ -48,6 +67,7 @@ export function printDryRun(plan) {
     for (const f of u.workflows) lines.push(`  - ${f}`);
     lines.push(`제거될 스크립트 (${u.scripts.length}개):`);
     for (const f of u.scripts) lines.push(`  - ${f}`);
+    for (const f of u.appFiles || []) lines.push(`제거될 Flutter 앱 파일: ${f}`);
     if (u.readme) lines.push("제거될 항목: README.md 버전 섹션 (AUTO-VERSION-SECTION)");
     if (u.gitignore) lines.push("제거될 항목: .gitignore 자동 추가 항목");
     if (u.versionYml) lines.push("제거될 파일: version.yml");
@@ -60,6 +80,23 @@ export function printDryRun(plan) {
       for (const f of w.changed) lines.push(`  ~ ${f.filename} [${f.type}]`);
       lines.push(`동일한 파일 (${w.unchanged.length}개, 변경 없음)`);
     }
+    if (plan.cleanup) {
+      const reasons = { cleanup: "이전 배포 방식 정리", storeCleanup: "선택 해제된 스토어 워크플로우 정리", staleCleanup: "현재 버전에 없는 이전 워크플로우 정리" };
+      const removed = [];
+      const backedUp = [];
+      for (const [key, reason] of Object.entries(reasons)) {
+        for (const f of plan.cleanup[key]?.removed || []) removed.push(`  - ${f} (${reason})`);
+        for (const f of plan.cleanup[key]?.backedUp || []) backedUp.push(`  > ${f} → ${f}.bak (${reason}, 수정본이라 백업)`);
+      }
+      if (removed.length) lines.push(`삭제될 파일 (${removed.length}개):`, ...removed);
+      if (backedUp.length) lines.push(`.bak으로 옮겨질 파일 (${backedUp.length}개):`, ...backedUp);
+    }
+    if (plan.gitignore) {
+      const g = plan.gitignore;
+      lines.push(g.created
+        ? `.gitignore: 새로 생성될 예정 (${g.added.join(", ")})`
+        : g.added.length ? `.gitignore: ${g.added.join(", ")} 추가될 예정` : ".gitignore: 변경 없음 (이미 있는 항목)");
+    }
     if (plan.flutterApp && (plan.flutterApp.created.length || plan.flutterApp.kept.length)) {
       const { created, kept } = plan.flutterApp;
       lines.push(`Flutter 스토어 배포 파일 — 신규 (${created.length}개):`);
@@ -75,6 +112,23 @@ export function printDryRun(plan) {
       // spring 등 deploy 블록이 있는 타입은 실제 설치 결과와 미리보기가 다를 수 있음을 안내한다.
       lines.push("  (참고: 배포 설정 질문이 있는 타입(spring 등)은 deploy: 블록이 미리보기에 반영되지 않아 실제 설치와 다르게 보일 수 있습니다.)");
     }
+    if (plan.scripts) {
+      const mark = { create: "+", overwrite: "~", unchanged: "=" };
+      const note = { create: "새로 생성", overwrite: "기존 파일을 새 버전으로 덮어씀 — 직접 고친 내용은 사라집니다", unchanged: "변경 없음" };
+      lines.push(`스크립트 (${PATHS.scriptsDir}/, ${plan.scripts.length}개 — 항상 새 버전으로 교체):`);
+      for (const s of plan.scripts) lines.push(`  ${mark[s.action]} ${s.name} (${note[s.action]})`);
+    }
+    if (plan.readme) {
+      lines.push({
+        added: "README.md: 끝에 버전 섹션이 추가될 예정",
+        "skip-no-readme": "README.md: 파일이 없어 버전 섹션을 추가하지 않음",
+        "skip-marker": "README.md: 이미 버전 섹션이 있어 변경 없음",
+        "skip-version-line": "README.md: 이미 버전 줄이 있어 변경 없음",
+      }[plan.readme] || `README.md: ${plan.readme}`);
+    }
+    if (plan.baselineExists !== undefined) {
+      lines.push(`${BASELINE_PATH}: ${plan.baselineExists ? "갱신될 예정" : "새로 생성될 예정"} (다음 업데이트의 비교 기준)`);
+    }
   }
   lines.push("");
   console.log(lines.join("\n"));

package/src/commands/full.js

@@ -1,23 +1,24 @@
-// full 모드 오케스트레이터 (.sh execute_integration full case 등가).
+// full 모드 오케스트레이터 — 대화형·비대화형이 확정한 context로 실제 설치를 수행한다.
 // 복사 순서: workflows(+env 치환) → flutter 앱 파일 → version.yml → readme → scripts → gitignore(조건부)
 // gitignore는 충돌 백업 부산물(.bak/.template.yaml)이 이번 실행에서 실제로 생겼을 때만 갱신한다.
-// (원본의 util/issue/discussion/setup-guide/config 설치는 project-auto-wizard 스코프에서 제외 — DESIGN-SPEC §2)
 import { join } from "node:path";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { writeText } from "../core/fsutil.js";
+import { writeText, findUnwritable } from "../core/fsutil.js";
+import { CliError } from "../core/errors.js";
 import { PATHS } from "../core/paths.js";
-import { renderVersionYml, parseExisting } from "../core/version-yml.js";
+import { renderVersionYml, parseExisting, sameIgnoringTimestamps } from "../core/version-yml.js";
 import { readVersionYmlTemplate } from "../core/assets.js";
 import { existingMarkerInDir } from "../core/paths-resolve.js";
-import { addVersionSectionToReadme } from "../core/copy/readme.js";
+import { addVersionSectionToReadme, README_STATUS_LABEL } from "../core/copy/readme.js";
 import { copyWorkflows, computeBaselineEntries, makeSrcText } from "../core/copy/workflows.js";
-import { copyScripts } from "../core/copy/simple.js";
-import { copyFlutterAppFiles } from "../core/copy/flutter-app.js";
+import { copyScripts, removeScriptBytecode } from "../core/copy/simple.js";
+import { copyTypeAppFiles } from "../core/copy/app-files.js";
 import { ensureGitignore } from "../core/copy/gitignore.js";
-import { readBaseline, writeBaseline } from "../core/baseline.js";
-import { scanUnsubstituted, collectRequiredSecrets, narrowSecretsBySshAuth } from "../core/verify.js";
-import { cleanupOtherDeployWorkflows, DEFAULT_DEPLOY_STYLE } from "../core/deploy-style.js";
-import { cleanupDeselectedStoreWorkflows } from "../core/flutter-options.js";
+import { readBaseline, writeBaseline, appFileHash } from "../core/baseline.js";
+import { scanUnsubstituted, classifySecrets, narrowSecretsBySshAuth } from "../core/verify.js";
+import { cleanupOtherDeployWorkflows, payloadWorkflowNames, DEFAULT_DEPLOY_STYLE } from "../core/deploy-style.js";
+import { hooksFor } from "../core/types.js";
+import { findStaleWorkflows, cleanupStaleWorkflows } from "../core/removal-plan.js";
 import { log, maskValue } from "../core/logger.js";
 
 // context: { version, types, paths:Map, branch, versionCode,
@@ -28,17 +29,28 @@ export function runFull(context, payloadRoot, targetRoot = ".", hooks = {}) {
     force = true, now, today, templateVersion = "unknown",
     includeSemverAuto } = context;
 
-  // project_paths 마커 계산 (.sh existing_marker_in_dir 등가).
+  // 아무것도 쓰기 전에 권한부터 확인한다 — 도중에 멈추면 반쯤 설치된 상태가 남는다.
+  const blocked = findUnwritable(targetRoot,
+    [".", PATHS.workflowsDir, PATHS.scriptsDir, ".github/.wizard"],
+    [PATHS.versionFile, "README.md", ".gitignore", ".github/.wizard/baseline.json"]);
+  if (blocked.length) {
+    throw new CliError(`쓰기 권한이 없어 설치를 시작하지 않았습니다 (아무 파일도 바꾸지 않았습니다):\n${blocked.map((p) => `  - ${p}`).join("\n")}\n권한을 확인한 뒤 다시 실행하세요.`);
+  }
+
+  // project_paths 마커 계산.
   // 대표 마커명이 아니라 그 폴더에 실제로 있는 파일을 쓴다 — build.gradle.kts만 있는 레포의
   // version.yml에 "# build.gradle"이라고 적히면 감지 로그와 같은 종류의 거짓말이 된다.
   const pathMarkers = new Map();
   for (const [t, p] of paths) {
     const marker = existingMarkerInDir(t, join(targetRoot, p || "."));
     pathMarkers.set(t, marker);
-    log.info("detect", "type", `${t} (근거: ${marker || "직접 선택"})`);
+    // 파일이 실제로 없으면 사용자가 직접 고른 타입이다 — 대표 파일명을 근거로 적으면 감지된 것처럼 보인다.
+    const found = marker && existsSync(join(targetRoot, p || ".", marker));
+    log.info("detect", "type", `${t} (근거: ${found ? marker : "직접 선택"})`);
   }
   log.info("detect", "version", `${version}${context.versionSource ? ` (${context.versionSource})` : ""}`);
   log.info("detect", "branch", `${branch}${context.branches ? ` | main=${context.branches.main} develop=${context.branches.develop} mode=${context.branches.mode}` : ""}`);
+  logChoices(context, types);
   for (const a of context.envAnswers || []) {
     log.info("prompt", a.isDefault ? "default" : "answer", `${a.key}=${maskValue(a.key, a.value)}`);
   }
@@ -50,25 +62,36 @@ export function runFull(context, payloadRoot, targetRoot = ".", hooks = {}) {
 
   // 1-1. Flutter 앱 파일(fastlane·ExportOptions) — 사용자가 값을 채워 쓰는 파일이라 없을 때만 만든다.
   //      워크플로우 복사가 끝난 뒤에 실행한다(워크플로우가 이 파일들을 전제로 돈다).
-  const flutterApp = copyFlutterAppFiles(context, payloadRoot, targetRoot);
-  for (const f of flutterApp.created) log.info("flutter-app", "create", f);
-  for (const f of flutterApp.kept) log.info("flutter-app", "keep", `${f} (기존 파일 유지)`);
+  const flutterApp = copyTypeAppFiles(context, payloadRoot, targetRoot, (tag, action, f) => {
+    log.info(tag, action, action === "keep" ? `${f} (기존 파일 유지)` : f);
+  });
 
   // 기존 version.yml의 알려지지 않은 최상위 필드를 재생성 시 보존한다.
   const vyPath = join(targetRoot, PATHS.versionFile);
-  const extraTopLevel = existsSync(vyPath) ? parseExisting(readFileSync(vyPath, "utf8")).extraTopLevel : [];
+  const prevVy = existsSync(vyPath) ? readFileSync(vyPath, "utf8") : null;
+  const extraTopLevel = prevVy != null ? parseExisting(prevVy).extraTopLevel : [];
 
   // 2. version.yml 생성 (payload/version.yml.template 렌더링 — 전체 재생성)
-  writeText(join(targetRoot, PATHS.versionFile),
-    renderVersionYml(context, readVersionYmlTemplate(payloadRoot), { pathMarkers, deployValues, extraTopLevel }));
-
-  log.info("version", "write", `version.yml (v${version}, code=${versionCode})`);
+  //    날짜 줄만 달라지는 재실행은 다시 쓰지 않는다(멱등).
+  const vyText = renderVersionYml(context, readVersionYmlTemplate(payloadRoot), { pathMarkers, deployValues, extraTopLevel });
+  if (prevVy == null || !sameIgnoringTimestamps(prevVy, vyText)) {
+    writeText(vyPath, vyText);
+    log.info("version", "write", `version.yml (v${version}, code=${versionCode})`);
+  } else {
+    log.info("version", "skip", `version.yml (v${version}, code=${versionCode}, 변경 없음)`);
+  }
 
   // 3. README 버전 섹션
-  addVersionSectionToReadme(version, targetRoot);
+  const readme = addVersionSectionToReadme(version, targetRoot);
+  log.info("readme", readme === "added" ? "append" : "skip", README_STATUS_LABEL[readme] || readme);
 
-  // 4. scripts (payload/scripts/*.py → .github/scripts/)
-  copyScripts(payloadRoot, targetRoot);
+  // 4. scripts (payload/scripts/*.py → .github/scripts/) — 항상 덮어쓰므로 사용자 수정이 사라진 사실도 남긴다.
+  const scripts = copyScripts(payloadRoot, targetRoot);
+  for (const { name, action } of scripts) {
+    log.info("script", action, `${PATHS.scriptsDir}/${name}${action === "overwrite" ? " (기존 내용과 달라 새 버전으로 덮어씀)" : ""}`);
+  }
+  const bytecodeRemoved = removeScriptBytecode(targetRoot);
+  for (const rel of bytecodeRemoved) log.info("script", "remove", `${rel} (예전 버전이 커밋한 바이트코드 — 삭제를 함께 커밋하세요)`);
 
   // 5. gitignore — 워크플로우 충돌 처리가 .bak나 .template.yaml을 실제로 만든 경우에만 갱신한다.
   //    충돌 없는 설치(대부분의 최초 설치)는 .gitignore를 전혀 건드리지 않는다.
@@ -77,35 +100,28 @@ export function runFull(context, payloadRoot, targetRoot = ".", hooks = {}) {
   // 6. 이전 배포 방식 정리 — 방식을 바꿔 재설치하면 이전 CD가 남아 배포가 두 번 돈다.
   //    옛 baseline이 살아 있는 지금이 "사용자가 손댔는가"를 판정할 수 있는 유일한 시점이다.
   const previousBaseline = readBaseline(targetRoot);
-  const cleanup = cleanupOtherDeployWorkflows(
-    join(targetRoot, PATHS.workflowsDir),
-    existsSync(join(targetRoot, PATHS.workflowsDir)) ? readdirSync(join(targetRoot, PATHS.workflowsDir)) : [],
-    context.deployStyle || DEFAULT_DEPLOY_STYLE,
-    previousBaseline);
+  const { cleanup, storeCleanup, staleCleanup } = cleanupWorkflows(context, payloadRoot, targetRoot, previousBaseline,
+    { justWritten: wfCounters.copiedFiles || [] });
   // 지운 파일의 기준점은 baseline에서도 빼야 다음 실행에서 "사용자가 지웠다"로 오인하지 않는다.
-  for (const f of [...cleanup.removed, ...cleanup.backedUp]) delete previousBaseline?.files?.[f];
+  for (const r of [cleanup, storeCleanup, staleCleanup]) {
+    for (const f of [...r.removed, ...r.backedUp]) delete previousBaseline?.files?.[f];
+  }
 
   for (const f of cleanup.removed || []) log.info("cleanup", "remove", `${f} (이전 배포 방식 정리)`);
   for (const f of cleanup.backedUp || []) log.info("cleanup", "backup", `${f} → ${f}.bak`);
-
-  // 6-1. 선택 해제된 스토어 워크플로우 정리 — 스토어 대상을 줄여 재설치하면 이전 워크플로우가 남아
-  //      main push마다 계속 도는 것을 막는다. 규칙은 6과 같다(미수정 삭제, 수정본 .bak).
-  //      선택이 미결정(null)이거나 Flutter가 없으면 현행 동작 그대로 아무것도 지우지 않는다.
-  //      Fastfile·ExportOptions는 사용자 소유라 여기서 다루지 않는다.
-  const workflowsDir = join(targetRoot, PATHS.workflowsDir);
-  const storeCleanup = Array.isArray(context.flutterStore) && types.includes("flutter")
-    ? cleanupDeselectedStoreWorkflows(
-      workflowsDir,
-      existsSync(workflowsDir) ? readdirSync(workflowsDir) : [],
-      context.flutterStore,
-      previousBaseline)
-    : { removed: [], backedUp: [] };
-  for (const f of [...storeCleanup.removed, ...storeCleanup.backedUp]) delete previousBaseline?.files?.[f];
   for (const f of storeCleanup.removed) log.info("cleanup", "remove", `${f} (선택 해제된 스토어 워크플로우 정리)`);
   for (const f of storeCleanup.backedUp) log.info("cleanup", "backup", `${f} → ${f}.bak`);
-
-  const gitignoreUpdated = gitignoreUpdated0 || cleanup.backedUp.length > 0 || storeCleanup.backedUp.length > 0;
-  if (gitignoreUpdated) ensureGitignore(targetRoot);
+  for (const f of staleCleanup.removed) log.info("cleanup", "remove", `${f} (현재 버전에 없는 이전 워크플로우 정리)`);
+  for (const f of staleCleanup.backedUp) log.info("cleanup", "backup", `${f} → ${f}.bak`);
+  const cleanupCount = (key) => [cleanup, storeCleanup, staleCleanup].reduce((n, r) => n + r[key].length, 0);
+
+  const gitignoreUpdated = gitignoreUpdated0 || cleanup.backedUp.length > 0 || storeCleanup.backedUp.length > 0
+    || staleCleanup.backedUp.length > 0;
+  if (gitignoreUpdated) {
+    const gi = ensureGitignore(targetRoot);
+    log.info("gitignore", gi.created ? "create" : gi.added.length ? "append" : "skip",
+      gi.added.length ? `.gitignore += ${gi.added.join(", ")}` : ".gitignore (이미 있는 항목)");
+  }
 
   // 7. baseline 기록 — 다음 업데이트에서 "누가 바꿨는지"를 가를 기준점.
   //    env 치환까지 전부 끝난 뒤에 해시해야 디스크 내용이 최종형이다. 그래서 copyWorkflows 안이
@@ -117,8 +133,11 @@ export function runFull(context, payloadRoot, targetRoot = ".", hooks = {}) {
     entries: computeBaselineEntries(
       wfCounters.baselineTargets || new Map(),
       join(targetRoot, PATHS.workflowsDir),
-      makeSrcText(context.branches || null, context.deployStyle || "")),
+      makeSrcText(context.branches || null, context.deployStyle || ""),
+      deployValues),
     previous: previousBaseline,
+    // 새로 만든 Flutter 앱 파일만 기록한다 — 기존 사용자 파일(kept)은 완전 삭제 대상이 아니다.
+    appFiles: new Map(flutterApp.created.map((rel) => [rel, appFileHash(readFileSync(join(targetRoot, rel), "utf8"))])),
   });
 
   // 8. 설치 후 검증 — 디스크에 실제로 쓰인 내용을 다시 읽어 확인한다.
@@ -127,26 +146,87 @@ export function runFull(context, payloadRoot, targetRoot = ".", hooks = {}) {
   const wfDir = join(targetRoot, PATHS.workflowsDir);
   const managed = [...(wfCounters.baselineTargets || new Map()).keys()];
   const unresolved = scanUnsubstituted(wfDir, managed);
-  const secrets = narrowSecretsBySshAuth(
-    collectRequiredSecrets(wfDir, managed),
-    firstDeployValue(deployValues, "SSH_AUTH_METHOD"),
-  );
+  // 기본값이 있거나 둘 중 하나면 되는 secret은 필수와 나눠 안내한다.
+  const secretSets = classifySecrets(wfDir, managed);
+  const secrets = narrowSecretsBySshAuth(secretSets.required, firstDeployValue(deployValues, "SSH_AUTH_METHOD"));
+  const optionalSecrets = secretSets.optional;
 
   // 9. 요약 — 파일 끝에 결과 블록을 붙인다. tail만 봐도 결과가 보이도록.
   for (const u of unresolved) log.warn("verify", "unresolved", `${u.filename}:${u.line} ${u.token}`);
   for (const [name, users] of secrets) log.info("verify", "secret", `${name} ← ${users.join(", ")}`);
+  for (const [name, users] of optionalSecrets) log.info("verify", "secret-opt", `${name} (선택) ← ${users.join(", ")}`);
+  // copiedFiles에는 자동 갱신분도 들어 있다 — 빼지 않으면 같은 파일이 설치와 자동 갱신에 두 번 잡힌다.
+  const autoUpdated = new Set(wfCounters.autoUpdated || []);
   log.summary([
-    ["설치", `${(wfCounters.copiedFiles || []).length}개 파일`],
-    ["자동 갱신", `${(wfCounters.autoUpdated || []).length}개 (사용자 미수정)`],
+    ["설치", `${(wfCounters.copiedFiles || []).filter((f) => !autoUpdated.has(f)).length}개 파일`],
+    ["자동 갱신", `${autoUpdated.size}개 (사용자 미수정)`],
     ["유지", `${(wfCounters.keptLocal || []).length}개 (사용자 수정본)`],
     ["변경 없음", `${(wfCounters.unchangedFiles || []).length}개`],
     ["백업 교체", `${wfCounters.backupAdded || 0}개 (.bak 생성)`],
+    // 배포 방식 변경·스토어 해제·옛 워크플로우 정리도 파일을 지우거나 .bak으로 옮긴다 — 충돌 백업과 따로 센다.
+    ["정리", `삭제 ${cleanupCount("removed")}개, .bak 이동 ${cleanupCount("backedUp")}개`],
     ["미치환", `${unresolved.length}건${unresolved.length ? "  ← 조치 필요" : ""}`],
     ["필요 Secret", `${secrets.size}개`],
     ["결과", unresolved.length ? `주의 (미치환 ${unresolved.length}건)` : "OK"],
   ]);
 
-  return { workflows: wfCounters, gitignoreUpdated, unresolved, secrets, cleanup, storeCleanup, flutterApp };
+  return { workflows: wfCounters, gitignoreUpdated, unresolved, secrets, cleanup, storeCleanup, staleCleanup, flutterApp, readme, scripts, bytecodeRemoved, optionalSecrets };
+}
+
+// 워크플로우 정리 3종 — 실제 설치(runFull)와 --dry-run 미리보기가 같은 판정을 쓴다.
+//   6   배포 방식 정리 — 방식을 바꿔 재설치하면 이전 CD가 남아 배포가 두 번 돈다.
+//   6-1 선택 해제된 스토어 워크플로우 정리 — 스토어 대상을 줄여 재설치하면 이전 워크플로우가 main push마다
+//       계속 돈다. 선택이 미결정(null)이거나 Flutter가 없으면 아무것도 지우지 않는다.
+//       Fastfile·ExportOptions는 사용자 소유라 여기서 다루지 않는다.
+//   6-2 payload에서 이름이 바뀌거나 빠진 옛 워크플로우 정리.
+// 규칙은 모두 같다(미수정 삭제, 수정본 .bak). 세 대상은 파일명이 겹치지 않아 순서와 무관하게 판정이 같다.
+// baseline은 정리 전의 것을 넘겨야 한다 — "사용자가 손댔는가"를 판정할 수 있는 유일한 기준이다.
+// dryRun이면 판정만 하고 파일은 건드리지 않는다.
+export function cleanupWorkflows(context, payloadRoot, targetRoot, baseline, { justWritten = [], dryRun = false } = {}) {
+  const workflowsDir = join(targetRoot, PATHS.workflowsDir);
+  const listDir = () => (existsSync(workflowsDir) ? readdirSync(workflowsDir) : []);
+  const cleanup = cleanupOtherDeployWorkflows(workflowsDir, listDir(),
+    context.deployStyle || DEFAULT_DEPLOY_STYLE, baseline,
+    { available: payloadWorkflowNames(payloadRoot), justWritten, dryRun });
+  const storeCleanup = { removed: [], backedUp: [] };
+  for (const { hook } of hooksFor(context.types || [], "cleanupWorkflows")) {
+    const r = hook(workflowsDir, listDir(), context, baseline, { dryRun });
+    storeCleanup.removed.push(...r.removed);
+    storeCleanup.backedUp.push(...r.backedUp);
+  }
+  const staleCleanup = cleanupStaleWorkflows(targetRoot, findStaleWorkflows(payloadRoot, targetRoot, baseline), baseline, { dryRun });
+  return { cleanup, storeCleanup, staleCleanup };
+}
+
+// 설치 결과를 가른 선택(배포 방식·자동 승격·Copilot·Flutter 옵션)을 남긴다 — 대화형에서 고른 값도
+// 여기로 모이므로, 나중에 "왜 이렇게 설치됐나"를 로그만으로 따라갈 수 있다.
+function logChoices(context, types) {
+  if (context.deployStyle) log.info("option", "deploy", context.deployStyle);
+  if (context.includeSemverAuto != null) log.info("option", "semver", context.includeSemverAuto ? "on" : "off");
+  if (context.includeCopilotAi != null) log.info("option", "copilot", context.includeCopilotAi ? "on" : "off");
+  if (types.includes("flutter")) {
+    const stores = Array.isArray(context.flutterStore) ? (context.flutterStore.join(",") || "없음") : "미결정(둘 다)";
+    log.info("option", "flutter",
+      `env=${context.envMode || "-"} stores=${stores} android=${context.androidDeployMode || "-"} ios=${context.iosDeployMode || "-"}`);
+  }
+}
+
+// 완료 요약과 별도로 알려야 하는 사실 — 비대화형 실행이 조용히 넘어가면 사용자는 업데이트를 다 받았다고 믿는다.
+// interactive: 대화형은 충돌을 사용자가 직접 골랐으므로 충돌 안내를 빼고 정리 결과만 알린다.
+export function postInstallNotices(result, { interactive = false } = {}) {
+  const lines = [];
+  const stale = result?.staleCleanup || { removed: [], backedUp: [] };
+  if (stale.removed.length || stale.backedUp.length) {
+    lines.push("현재 버전에 없는 이전 워크플로우를 정리했습니다 (이름이 바뀌었거나 제거된 파일):");
+    for (const f of stale.removed) lines.push(`   • ${f} — 삭제 (손대지 않은 파일)`);
+    for (const f of stale.backedUp) lines.push(`   • ${f} → ${f}.bak — 수정하신 내용이 있어 백업`);
+  }
+  const kept = interactive ? [] : result?.workflows?.conflictKept || [];
+  if (kept.length) {
+    lines.push(`충돌 ${kept.length}개 — 기존 파일을 유지했습니다 (업스트림 변경 미반영): ${kept.join(", ")}`);
+    lines.push("   파일마다 고르려면 대화형(npx project-auto-wizard)으로 다시 실행하세요.");
+  }
+  return lines;
 }
 
 // deployValues는 Map<type, Map<key,value>> — 타입 구분 없이 첫 값만 필요할 때 쓴다.

package/src/commands/install-settings.js

@@ -0,0 +1,51 @@
+// 설치 설정 해석 단계 — 비대화형(index.js)과 대화형(interactive.js)이 공유한다.
+// 값을 채우는 방법(플래그·질문)은 경로마다 다르지만, 타입·버전·배포 방식·옵션을 확정하고
+// 설치 컨텍스트로 조립하는 규칙은 한 곳에 둬야 한쪽만 고쳐 두 모드의 결과가 갈라지지 않는다.
+import { detectVersion, detectBuildNumber } from "../core/detect-fs.js";
+import { createContext } from "../context.js";
+import { isDeployStyle, DEFAULT_DEPLOY_STYLE, hasServerDeployWorkflows, effectiveDeployStyle } from "../core/deploy-style.js";
+
+// version.yml에 저장된 배포 방식 — 없거나 알 수 없는 값이면 "".
+export const savedDeployStyle = (existing) =>
+  isDeployStyle(existing?.options?.deployStyle) ? existing.options.deployStyle : "";
+
+// 배포 방식 — 명시값(플래그·질문 답변) → 저장값 → 기본값.
+// 서버 배포 워크플로우가 없는 타입은 설치 결과에 영향이 없으므로 기록하지 않는다(null).
+export function resolveDeployStyle({ payload, types, explicit = "", existing }) {
+  if (!hasServerDeployWorkflows(payload, types)) return null;
+  return explicit || savedDeployStyle(existing) || DEFAULT_DEPLOY_STYLE;
+}
+
+// 버전 — 기존 version.yml 최우선(재실행 시 덮어쓰기 방지) → 명시값 → 파일 감지.
+// detectOpts는 감지 함수로 그대로 넘긴다(types·paths·warn·hint).
+export function resolveVersion({ cwd, existing, explicit = "", ...detectOpts }) {
+  return existing?.version || explicit || detectVersion(cwd, detectOpts);
+}
+
+// 빌드 번호 — 기존 값 보존, 신규 통합이면 프로젝트 파일에서 감지, 못 찾으면 1.
+export function resolveVersionCode({ cwd, existing, types, paths }) {
+  return existing?.versionCode ?? detectBuildNumber(cwd, { types, paths }) ?? 1;
+}
+
+// 확정된 값들을 설치 컨텍스트로 조립한다.
+//   deployStyle: resolveDeployStyle 결과(고른 값). 실제 설치되는 방식으로 바꿔 기록한다.
+//   flutterOptions: { envMode, stores, androidDeployMode, iosDeployMode } — 두 경로 모두 확정된 값.
+//   releaseOptions: { includeSemverAuto, includeCopilotAi } — resolveReleaseOptions 결과.
+//   extra: 경로별로만 쓰는 필드(envValues 등).
+export function buildInstallContext({
+  payload, existing, templateVersion, types, deployStyle, flutterOptions, releaseOptions, ...rest
+}) {
+  return createContext({
+    types,
+    ...releaseOptions,
+    // 안내는 고른 값으로 하되, 기록은 실제로 설치되는 방식으로 한다.
+    deployStyle: effectiveDeployStyle(payload, types, deployStyle),
+    envMode: flutterOptions.envMode,
+    flutterStore: flutterOptions.stores,
+    androidDeployMode: flutterOptions.androidDeployMode,
+    iosDeployMode: flutterOptions.iosDeployMode,
+    previousTemplateVersion: existing?.templateVersion || "",
+    templateVersion,
+    ...rest,
+  });
+}