project-auto-wizard 0.1.7 → 0.1.9

package/README.md

@@ -16,7 +16,7 @@ npx project-auto-wizard
 [![node](https://img.shields.io/badge/node-%3E%3D20.12-brightgreen)](package.json)
 
 <!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->
-## 최신 버전 : v0.1.6 (2026-07-27)
+## 최신 버전 : v0.1.9 (2026-08-02)
 
 [전체 버전 기록 보기](CHANGELOG.md)
 
@@ -73,6 +73,20 @@ flutter.APP_ARTIFACT_NAME:
 
 `npx project-auto-wizard --mode revert`는 payload가 설치한 파일명과 **정확히 일치하는 것만** 제거합니다. 사용자가 직접 만든 워크플로우, `version.yml`, `README.md`, `.gitignore`는 건드리지 않습니다. 설치 시 충돌 처리로 생성된 `.bak`/`.template.yaml` 파생 파일도 함께 정리됩니다.
 
+### 완전 삭제(`--mode uninstall`)
+
+`npx project-auto-wizard --mode uninstall`은 `revert`보다 넓게 제거합니다 — 워크플로우·스크립트·`.coderabbit.yaml`은 물론, README.md의 `AUTO-VERSION-SECTION` 버전 섹션과 `.gitignore`에 자동 추가된 항목, `version.yml`까지 선택적으로 제거할 수 있습니다.
+
+- **대화형(TTY)**: 실제로 설치된 항목만 체크리스트로 보여줍니다. 워크플로우/스크립트/`.coderabbit.yaml`은 기본 체크, README·`.gitignore`·`version.yml`은 opt-in입니다. 선택 후 최종 확인(기본 "아니오")을 거쳐야 실제로 삭제됩니다.
+- **비대화형(`--force`)**: 워크플로우·스크립트·`.coderabbit.yaml`만 기본 삭제합니다. README·`.gitignore`·`version.yml`까지 지우려면 `--purge-readme`/`--purge-gitignore`/`--purge-version`을 함께 지정하세요.
+- `--dry-run`과 함께 쓰면 무엇이 지워질지 미리 볼 수 있습니다.
+
+```bash
+npx project-auto-wizard --mode uninstall                 # 대화형 체크리스트
+npx project-auto-wizard --mode uninstall --force         # 워크플로우·스크립트·coderabbit만 안전 삭제
+npx project-auto-wizard --mode uninstall --force --purge-readme --purge-gitignore --purge-version  # 완전 삭제
+```
+
 ## API 키 0개 AI — 요약 엔진 체인
 
 릴리스 노트는 4단 엔진 체인으로 생성됩니다. **어떤 단계가 실패해도 릴리스는 절대 막히지 않습니다.**
@@ -111,7 +125,7 @@ flowchart LR
 ```
 npx project-auto-wizard [옵션]
 
-  -m, --mode MODE          full | version | workflows | revert | status | doctor  (기본: 대화형)
+  -m, --mode MODE          full | version | workflows | revert | uninstall | status | doctor  (기본: 대화형)
   -t, --type CSV           spring,react,... (미지정 시 자동 감지)
       --project-version V  초기 버전 (미지정 시 자동 감지)
       --paths "t=p,..."    모노레포 타입별 경로
@@ -122,6 +136,9 @@ npx project-auto-wizard [옵션]
       --coderabbit         CodeRabbit PR 요약을 릴리스 노트 1순위로
       --semver-auto        커밋 타입 기반 자동 major/minor/patch 승격 (기본: 사용함, --no-semver-auto로 끔)
       --dry-run            실제 파일 변경 없이 무엇이 바뀔지만 미리 보여줌
+      --purge-readme        --mode uninstall --force 시 README.md 버전 섹션도 제거
+      --purge-gitignore     --mode uninstall --force 시 .gitignore 자동 추가 항목도 제거
+      --purge-version       --mode uninstall --force 시 version.yml도 제거
       --force              전 질문 생략 (CI용)
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-auto-wizard",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "One command DevOps: npx wizard that installs GitHub-native AI Release Automation into any project",
   "license": "MIT",
   "type": "module",

package/src/cli/args.js

@@ -19,6 +19,19 @@ export function parseArgs(argv) {
     help: false,
     showVersion: false,      // -v/--version → 패키지 버전 출력 (npm 관례)
     dryRun: false,        // --dry-run: 실제 변경 없이 미리보기만 (full/version/workflows/revert 공통)
+    purgeReadme: false,       // --purge-readme: uninstall --force 시 README 버전 섹션도 제거
+    purgeGitignore: false,    // --purge-gitignore: uninstall --force 시 .gitignore 자동 추가 항목도 제거
+    purgeVersion: false,      // --purge-version: uninstall --force 시 version.yml도 제거
+    // purge 전용 플래그 (숨김 모드 — HELP_TEXT에는 노출하지 않는다).
+    yes: false,               // --yes: purge 실행 확인 (필수, --force로 대체 불가)
+    allowDirty: false,        // --allow-dirty: git 작업트리 dirty 상태에서도 강행
+    deleteDevelopBranch: false, // --delete-develop-branch: 로컬 develop 브랜치까지 삭제
+    keepVersionYml: false,
+    keepReadme: false,
+    keepChangelog: false,
+    keepWorkflows: false,
+    keepScripts: false,
+    keepCoderabbit: false,
   };
   const args = [...argv];
   while (args.length > 0) {
@@ -52,6 +65,18 @@ export function parseArgs(argv) {
       }
       case "--force": result.force = true; break;
       case "--dry-run": result.dryRun = true; break;
+      case "--purge-readme": result.purgeReadme = true; break;
+      case "--purge-gitignore": result.purgeGitignore = true; break;
+      case "--purge-version": result.purgeVersion = true; break;
+      case "--yes": result.yes = true; break;
+      case "--allow-dirty": result.allowDirty = true; break;
+      case "--delete-develop-branch": result.deleteDevelopBranch = true; break;
+      case "--keep-version-yml": result.keepVersionYml = true; break;
+      case "--keep-readme": result.keepReadme = true; break;
+      case "--keep-changelog": result.keepChangelog = true; break;
+      case "--keep-workflows": result.keepWorkflows = true; break;
+      case "--keep-scripts": result.keepScripts = true; break;
+      case "--keep-coderabbit": result.keepCoderabbit = true; break;
       case "--nexus": result.includeNexus = true; break;
       case "--no-nexus": result.includeNexus = false; break;
       case "--secret-backup": result.includeSecretBackup = true; break;

package/src/cli/help.js

@@ -5,8 +5,9 @@ export const HELP_TEXT = `project-auto-wizard — One command DevOps: GitHub-nat
   npx project-auto-wizard [옵션]
 
 옵션:
-  -m, --mode MODE          통합 모드 (full | version | workflows | revert | status | doctor)
+  -m, --mode MODE          통합 모드 (full | version | workflows | revert | uninstall | status | doctor)
                            기본: interactive (대화형). revert = 설치물 제거(되돌리기)
+                           uninstall = 완전 삭제(대화형 체크리스트, --force 시 --purge-*로 opt-in)
                            status = 설치 상태·드리프트 확인(읽기 전용). doctor = 환경 진단(읽기 전용)
   -t, --type CSV           프로젝트 타입 csv (예: spring,react,python)
                            지원: spring flutter next react react-native
@@ -20,7 +21,10 @@ export const HELP_TEXT = `project-auto-wizard — One command DevOps: GitHub-nat
       --coderabbit / --no-coderabbit  CodeRabbit PR 요약을 릴리스 노트 1순위로 사용 (기본: 사용 안 함)
       --semver-auto / --no-semver-auto  커밋 타입 기반 자동 major/minor/patch 승격 (기본: 사용함)
       --force              모든 확인 생략, 비대화형 기본값 사용
-      --dry-run            실제 파일 변경 없이 무엇이 바뀔지만 미리 보여줌 (full/version/workflows/revert 전체 지원)
+      --dry-run            실제 파일 변경 없이 무엇이 바뀔지만 미리 보여줌 (full/version/workflows/revert/uninstall 전체 지원)
+      --purge-readme        --mode uninstall --force 시 README.md 버전 섹션도 제거
+      --purge-gitignore     --mode uninstall --force 시 .gitignore 자동 추가 항목도 제거
+      --purge-version       --mode uninstall --force 시 version.yml도 제거
   -v, --version            project-auto-wizard 버전 출력
   -h, --help               이 도움말 표시
 
@@ -30,4 +34,5 @@ export const HELP_TEXT = `project-auto-wizard — One command DevOps: GitHub-nat
   npx project-auto-wizard --mode status
   npx project-auto-wizard --mode doctor
   npx project-auto-wizard --mode full --force --type node --dry-run
+  npx project-auto-wizard --mode uninstall --force --purge-readme --purge-gitignore --purge-version
 `;

package/src/commands/dry-run.js

@@ -1,10 +1,11 @@
 // --dry-run 미리보기 — 실제 파일을 쓰지 않고 무엇이 바뀔지 계산한다.
-// full/version/workflows/revert 4개 모드 전체 지원.
+// full/version/workflows/revert/uninstall 5개 모드 전체 지원.
 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 { planRevert } from "./revert.js";
+import { planUninstall } from "./uninstall.js";
 import { buildVersionYml } from "../core/version-yml.js";
 import { readVersionYmlTemplate } from "../core/assets.js";
 import { markerForType } from "../core/detect.js";
@@ -31,9 +32,12 @@ function versionYmlPreview(context, payloadRoot, targetRoot) {
   return { existed: existing !== null, changed: existing !== wouldBe };
 }
 
-// mode: "full" | "version" | "workflows" | "revert". 읽기 전용 — 아무 파일도 쓰지 않는다.
+// mode: "full" | "version" | "workflows" | "revert" | "uninstall". 읽기 전용 — 아무 파일도 쓰지 않는다.
 export function planDryRun(mode, context, payloadRoot, targetRoot = ".") {
   if (mode === "revert") return { mode, revert: planRevert(payloadRoot, targetRoot) };
+  if (mode === "uninstall") {
+    return { mode, uninstall: planUninstall(payloadRoot, targetRoot, context.uninstallSelection) };
+  }
 
   const result = { mode };
   if (mode === "full" || mode === "workflows") {
@@ -54,6 +58,16 @@ export function printDryRun(plan) {
     lines.push(`제거될 스크립트 (${r.scripts.length}개):`);
     for (const f of r.scripts) lines.push(`  - ${f}`);
     if (r.coderabbit) lines.push("제거될 파일: .coderabbit.yaml");
+  } else if (plan.mode === "uninstall") {
+    const u = plan.uninstall;
+    lines.push(`제거될 워크플로우 (${u.workflows.length}개):`);
+    for (const f of u.workflows) lines.push(`  - ${f}`);
+    lines.push(`제거될 스크립트 (${u.scripts.length}개):`);
+    for (const f of u.scripts) lines.push(`  - ${f}`);
+    if (u.coderabbit) lines.push("제거될 파일: .coderabbit.yaml");
+    if (u.readme) lines.push("제거될 항목: README.md 버전 섹션 (AUTO-VERSION-SECTION)");
+    if (u.gitignore) lines.push("제거될 항목: .gitignore 자동 추가 항목");
+    if (u.versionYml) lines.push("제거될 파일: version.yml");
   } else {
     if (plan.workflows) {
       const w = plan.workflows;

package/src/commands/interactive.js

@@ -18,6 +18,7 @@ import { runFull } from "./full.js";
 import { runVersion } from "./version.js";
 import { runWorkflows } from "./workflows.js";
 import { runRevert } from "./revert.js";
+import { runUninstallFlow } from "./uninstall.js";
 import * as prompts from "../ui/prompts.js";
 
 const CANCEL = prompts.CANCEL;
@@ -53,6 +54,14 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), payloadRoot
     return 0;
   }
 
+  // uninstall 모드 — 대화형 체크리스트로 항목별 opt-in 후 삭제. 감지·breaking 게이트 불필요.
+  // runUninstallFlow는 취소/항목없음 시 null을 반환한다 — 그때는 완료 outro를 찍지 않는다.
+  if (mode === "uninstall") {
+    const result = await runUninstallFlow(payload, cwd, io);
+    if (result) io.outro?.("완전 삭제를 마쳤습니다.");
+    return 0;
+  }
+
   // Breaking Changes 게이트 (.sh execute_integration L4415~4420 — 모든 모드 공통, 대화형은 확인 질문)
   const proceed = await runBreakingCheck({
     cwd, payloadRoot: payload, templateVersion,

package/src/commands/purge.js

@@ -0,0 +1,86 @@
+// purge 모드 — revert가 지우는 전부(워크플로우·스크립트·coderabbit) + version.yml·README
+// AUTO-VERSION-SECTION 블록·CHANGELOG를 추가로 제거해 설치 이전 상태로 완전히 되돌린다.
+// 개발·테스트 전용 숨김 모드 — DESIGN-SPEC purge #6.
+// develop 브랜치 삭제는 파일 삭제와 성격이 달라(실행 시점 git 상태 판단 필요) 여기 plan에는
+// 포함하지 않고 index.js의 purge 분기에서 직접 처리한다.
+import { join } from "node:path";
+import { existsSync, renameSync } from "node:fs";
+import { PATHS } from "../core/paths.js";
+import { remove } from "../core/fsutil.js";
+import { planRevert } from "./revert.js";
+import { removeVersionSectionFromReadme, hasVersionSection } from "../core/copy/readme.js";
+
+const CHANGELOG_FILES = ["CHANGELOG.json", "CHANGELOG.md"];
+
+// keepFlags: { versionYml, readme, changelog, workflows, scripts, coderabbit } — true인 카테고리는 후보에서 제외.
+// 반환: { workflows, scripts, coderabbit, versionYml, readmeSection, changelog } — 아무것도 지우지 않는 순수 함수.
+export function planPurge(payloadRoot, targetRoot = ".", keepFlags = {}) {
+  const revertPlan = planRevert(payloadRoot, targetRoot);
+  return {
+    workflows: keepFlags.workflows ? [] : revertPlan.workflows,
+    scripts: keepFlags.scripts ? [] : revertPlan.scripts,
+    coderabbit: keepFlags.coderabbit ? false : revertPlan.coderabbit,
+    versionYml: !keepFlags.versionYml && existsSync(join(targetRoot, PATHS.versionFile)),
+    readmeSection: !keepFlags.readme && hasVersionSection(targetRoot),
+    changelog: keepFlags.changelog ? [] : CHANGELOG_FILES.filter((f) => existsSync(join(targetRoot, f))),
+  };
+}
+
+// 삭제 전 요약 출력 — dry-run 미리보기와 실제 실행 전 요약 양쪽에서 재사용한다.
+export function printPurgePlan(plan, { dryRun = false } = {}) {
+  const lines = ["",
+    dryRun
+      ? "project-auto-wizard --mode purge --dry-run — 미리보기, 실제 파일은 바뀌지 않았습니다"
+      : "project-auto-wizard --mode purge — 아래 항목을 제거합니다",
+    ""];
+  lines.push(`워크플로우 (${plan.workflows.length}개):`);
+  for (const f of plan.workflows) lines.push(`  - ${f}`);
+  lines.push(`스크립트 (${plan.scripts.length}개):`);
+  for (const f of plan.scripts) lines.push(`  - ${f}`);
+  if (plan.coderabbit) lines.push("파일: .coderabbit.yaml");
+  if (plan.versionYml) lines.push("파일: version.yml");
+  if (plan.readmeSection) lines.push("README.md: AUTO-VERSION-SECTION 블록");
+  for (const f of plan.changelog) lines.push(`파일: ${f}`);
+  lines.push("");
+  console.log(lines.join("\n"));
+}
+
+// 실제 삭제 수행 — planPurge()와 동일 shape을 반환하되 실제로 제거된 항목을 반영한다.
+// runRevert()를 통째로 호출하지 않는 이유: runRevert는 항상 전체를 지우므로
+// --keep-* 로 선택적 카테고리만 보존하는 요구사항과 맞지 않는다.
+// H3 (Fable 검토): readmeSection은 plan의 판정을 그대로 되돌려주지 않고
+// removeVersionSectionFromReadme()의 실제 반환값("removed"인지)을 반영한다 — 스펙 §6이
+// "반환값은 실제 삭제 결과를 반영"하라고 명시하기 때문에, plan과 실제 제거 조건이
+// 이론상 어긋나는 경우에도 printPurgeResult가 거짓으로 "제거됨"을 보고하지 않는다.
+export function executePurge(payloadRoot, targetRoot = ".", keepFlags = {}) {
+  const plan = planPurge(payloadRoot, targetRoot, keepFlags);
+  const wfDir = join(targetRoot, PATHS.workflowsDir);
+  for (const name of plan.workflows) remove(join(wfDir, name));
+  for (const name of plan.scripts) remove(join(targetRoot, PATHS.scriptsDir, name));
+  if (plan.coderabbit) {
+    const cr = join(targetRoot, ".coderabbit.yaml");
+    remove(cr);
+    if (existsSync(cr + ".bak")) renameSync(cr + ".bak", cr);
+  }
+  if (plan.versionYml) remove(join(targetRoot, PATHS.versionFile));
+  const readmeSection = plan.readmeSection && removeVersionSectionFromReadme(targetRoot) === "removed";
+  for (const f of plan.changelog) remove(join(targetRoot, f));
+  return { ...plan, readmeSection };
+}
+
+// 삭제 후 실제 제거된 목록 출력 — printPurgePlan과 완전히 동일한 형태(파일명 나열)로
+// 맞춘다 (M3, Fable 검토: 개수만 출력하면 스펙 §5-6의 "제거된 목록 재출력" 요구를 충족하지 못함).
+export function printPurgeResult(result) {
+  const lines = ["", "제거됨:", ""];
+  lines.push(`워크플로우 (${result.workflows.length}개):`);
+  for (const f of result.workflows) lines.push(`  - ${f}`);
+  lines.push(`스크립트 (${result.scripts.length}개):`);
+  for (const f of result.scripts) lines.push(`  - ${f}`);
+  if (result.coderabbit) lines.push("파일: .coderabbit.yaml");
+  if (result.versionYml) lines.push("파일: version.yml");
+  if (result.readmeSection) lines.push("README.md: AUTO-VERSION-SECTION 블록");
+  for (const f of result.changelog) lines.push(`파일: ${f}`);
+  lines.push("(.gitignore 자동 추가 블록은 보존됩니다 — 별도 이슈에서 다룸)");
+  lines.push("");
+  console.log(lines.join("\n"));
+}

package/src/commands/uninstall.js

@@ -0,0 +1,129 @@
+// uninstall 모드 — revert(payload 파일명 일치분)보다 넓게, README/.gitignore/version.yml까지 선택적으로 제거.
+// 대화형 체크리스트 또는 --force + --purge-* 로 항목별 opt-in. revert.js는 건드리지 않고 읽기 전용으로만 재사용한다.
+import { join } from "node:path";
+import { existsSync, renameSync } from "node:fs";
+import { PATHS } from "../core/paths.js";
+import { remove } from "../core/fsutil.js";
+import { planRevert } from "./revert.js";
+import { removeVersionSectionFromReadme, hasVersionSection } from "../core/copy/readme.js";
+import { removeAutoAddedEntriesFromGitignore, hasAutoAddedEntries } from "../core/copy/gitignore.js";
+import { CANCEL } from "../ui/prompts.js";
+
+// selection: { workflows, scripts, coderabbit, readme, gitignore, versionYml } (모두 boolean).
+// 반환: 위와 동일한 키의 boolean/배열 — 실제로 제거 "대상"인지 여부(순수 함수, 아무것도 지우지 않음).
+export function planUninstall(payloadRoot, targetRoot, selection) {
+  const revertPlan = planRevert(payloadRoot, targetRoot);
+  return {
+    workflows: selection.workflows ? revertPlan.workflows : [],
+    scripts: selection.scripts ? revertPlan.scripts : [],
+    coderabbit: selection.coderabbit ? revertPlan.coderabbit : false,
+    readme: selection.readme ? hasVersionSection(targetRoot) : false,
+    gitignore: selection.gitignore ? hasAutoAddedEntries(targetRoot) : false,
+    versionYml: selection.versionYml ? existsSync(join(targetRoot, PATHS.versionFile)) : false,
+  };
+}
+
+// 반환: planUninstall과 동일한 형태 — 실제로 제거된 항목.
+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));
+  for (const name of plan.scripts) remove(join(targetRoot, PATHS.scriptsDir, name));
+  if (plan.coderabbit) {
+    const cr = join(targetRoot, ".coderabbit.yaml");
+    remove(cr);
+    if (existsSync(cr + ".bak")) renameSync(cr + ".bak", cr);
+  }
+  // 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));
+  return { ...plan, readme: readmeRemoved, gitignore: gitignoreRemoved };
+}
+
+// ── 대화형 체크리스트 흐름 ────────────────────────────────────────────
+const ITEM_DEFS = [
+  { key: "workflows", label: "워크플로우 (.github/workflows/PROJECT-*.yaml)" },
+  { key: "scripts", label: "스크립트 (.github/scripts/*.py)" },
+  { key: "coderabbit", label: ".coderabbit.yaml" },
+  { key: "readme", label: "README.md 버전 섹션 (AUTO-VERSION-SECTION)" },
+  { key: "gitignore", label: ".gitignore 자동 추가 항목" },
+  { key: "versionYml", label: "version.yml (버전/브랜치 설정 전체)" },
+];
+
+// 기본 체크 상태 — 설치 시 옵션(nexus/secret-backup/coderabbit)이 opt-in인 것과 대칭으로,
+// 여기서는 "안전 삭제" 3종만 기본 체크하고 나머지(readme/gitignore/versionYml)는 opt-in.
+export const SAFE_ITEMS = ["workflows", "scripts", "coderabbit"];
+
+function detectAvailableItems(payloadRoot, targetRoot) {
+  const revertPlan = planRevert(payloadRoot, targetRoot);
+  const presence = {
+    workflows: revertPlan.workflows.length > 0,
+    scripts: revertPlan.scripts.length > 0,
+    coderabbit: revertPlan.coderabbit,
+    readme: hasVersionSection(targetRoot),
+    gitignore: hasAutoAddedEntries(targetRoot),
+    versionYml: existsSync(join(targetRoot, PATHS.versionFile)),
+  };
+  return ITEM_DEFS.filter((d) => presence[d.key]).map((d) => ({ value: d.key, label: d.label }));
+}
+
+function toSelection(checkedKeys) {
+  const set = new Set(checkedKeys);
+  return {
+    workflows: set.has("workflows"), scripts: set.has("scripts"), coderabbit: set.has("coderabbit"),
+    readme: set.has("readme"), gitignore: set.has("gitignore"), versionYml: set.has("versionYml"),
+  };
+}
+
+function summarizeSelection(selection) {
+  const labelOf = Object.fromEntries(ITEM_DEFS.map((d) => [d.key, d.label]));
+  const chosen = Object.keys(selection).filter((k) => selection[k]).map((k) => `- ${labelOf[k]}`);
+  return chosen.length ? chosen.join("\n") : "(선택된 항목 없음)";
+}
+
+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.coderabbit) lines.push(".coderabbit.yaml 제거");
+  if (result.readme) lines.push("README.md 버전 섹션 제거");
+  if (result.gitignore) lines.push(".gitignore 자동 추가 항목 제거");
+  if (result.versionYml) lines.push("version.yml 제거");
+  return lines.length ? lines.join("\n") : "제거된 항목이 없습니다.";
+}
+
+// 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) {
+  const available = detectAvailableItems(payloadRoot, targetRoot);
+  if (available.length === 0) {
+    io.note?.("제거할 항목이 없습니다.", "완전 삭제");
+    return null;
+  }
+
+  const checked = await io.engineIo.multiselect({
+    message: "삭제할 항목을 선택하세요 (Space 토글, Enter 확정)",
+    options: available,
+    initialValues: available.map((o) => o.value).filter((v) => SAFE_ITEMS.includes(v)),
+  });
+  if (checked === CANCEL || !Array.isArray(checked) || checked.length === 0) {
+    io.cancelMessage?.("완전 삭제를 취소했습니다.");
+    return null;
+  }
+
+  const selection = toSelection(checked);
+  io.note?.(summarizeSelection(selection), "삭제 예정 항목");
+  const ok = await io.askYesNo("정말 삭제할까요? 되돌릴 수 없습니다.", false);
+  if (ok !== true) {
+    io.cancelMessage?.("완전 삭제를 취소했습니다.");
+    return null;
+  }
+
+  const result = runUninstall({}, payloadRoot, targetRoot, selection);
+  io.note?.(summarizeResult(result), "완전 삭제 완료");
+  return result;
+}

package/src/core/branches.js

@@ -5,7 +5,7 @@
 import { execFile } from "node:child_process";
 
 // 기본 exec — git 명령 실행. 반환 {code, stdout, stderr}. 테스트는 mock 주입.
-function defaultExec(cmd, args, { cwd } = {}) {
+export 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) });

package/src/core/copy/gitignore.js

@@ -1,6 +1,6 @@
 // .gitignore 보장 (.sh ensure_gitignore + normalize/check 등가) — template_integrator.sh 3996~4111.
 import { join } from "node:path";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
 
 const REQUIRED_ENTRIES = ["/.idea", "/.claude/settings.local.json"];
 
@@ -53,3 +53,55 @@ export function ensureGitignore(targetRoot = ".") {
   writeFileSync(p, content);
   return { created: false, added: toAdd };
 }
+
+// ensureGitignore가 기존 파일에 배너 블록을 추가할 때 항상 이 정확한 시퀀스로 시작한다
+// (빈 줄 하나 + 3줄 배너). 배너 직후, REQUIRED_ENTRIES와 일치하는 라인이 연속되는 동안만
+// "마법사가 추가한 항목"이다 — 그 뒤에 사용자가 나중에 추가한 항목은 절대 건드리지 않는다.
+const BANNER =
+  "\n" +
+  "# ====================================================================\n" +
+  "# project-auto-wizard: Auto-added entries\n" +
+  "# ====================================================================\n";
+
+// .gitignore에 마법사가 추가한 항목이 있는지 확인 (체크리스트 노출 판단용).
+// 두 케이스: (1) 원래 없던 파일을 통째로(또는 그 뒤에 사용자가 이어 쓴 형태로) 새로 만든 경우
+// (2) 기존 파일에 배너 블록을 붙인 경우.
+export function hasAutoAddedEntries(targetRoot = ".") {
+  const p = join(targetRoot, ".gitignore");
+  if (!existsSync(p)) return false;
+  const content = readFileSync(p, "utf8");
+  return content.startsWith(NEW_FILE_CONTENT) || content.includes(BANNER);
+}
+
+// 반환: 'removed' | 'file-deleted' | 'skip-no-gitignore' | 'skip-not-found'
+export function removeAutoAddedEntriesFromGitignore(targetRoot = ".") {
+  const p = join(targetRoot, ".gitignore");
+  if (!existsSync(p)) return "skip-no-gitignore";
+  const content = readFileSync(p, "utf8");
+
+  // 원래 파일이 없었는데 마법사가 통째로 만든 경우 — 그 뒤에 사용자가 이어서 추가한 내용만 보존.
+  if (content.startsWith(NEW_FILE_CONTENT)) {
+    const remainder = content.slice(NEW_FILE_CONTENT.length);
+    if (remainder === "") {
+      rmSync(p);
+      return "file-deleted";
+    }
+    writeFileSync(p, remainder);
+    return "removed";
+  }
+
+  // 기존 파일에 배너 블록이 붙은 경우 — 배너 직후 REQUIRED_ENTRIES와 일치하는 라인이 연속되는
+  // 동안만 제거하고, 그 뒤(사용자가 나중에 추가한 항목)는 그대로 둔다.
+  const idx = content.indexOf(BANNER);
+  if (idx === -1) return "skip-not-found";
+  const afterBanner = idx + BANNER.length;
+  const lines = content.slice(afterBanner).split("\n");
+  let consumed = 0;
+  for (const line of lines) {
+    const isKnownEntry = REQUIRED_ENTRIES.some((e) => normalizeGitignoreEntry(line) === normalizeGitignoreEntry(e));
+    if (!isKnownEntry) break;
+    consumed += line.length + 1; // +1: split이 삼킨 "\n"
+  }
+  writeFileSync(p, content.slice(0, idx) + content.slice(afterBanner + consumed));
+  return "removed";
+}

package/src/core/copy/readme.js

@@ -1,8 +1,8 @@
 // README 버전 섹션 추가 (.sh add_version_section_to_readme 등가) — template_integrator.sh 2145~2181.
 import { join } from "node:path";
-import { existsSync, readFileSync, appendFileSync } from "node:fs";
+import { existsSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
 
-const MARKER = "<!-- AUTO-VERSION-SECTION";
+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;
 
@@ -28,3 +28,54 @@ export function addVersionSectionToReadme(version, targetRoot = ".") {
   appendFileSync(p, section);
   return "added";
 }
+
+// addVersionSectionToReadme가 항상 파일 맨 끝에 붙이는 접두/접미 시퀀스.
+// 접두(SECTION_PREFIX)가 있으면 마법사가 append한 "블록"이다 — 이 블록은 항상 SECTION_TAIL
+// 라인으로 끝나므로, 그 지점까지만 잘라내야 그 뒤에 사용자가 나중에 덧붙인 내용(라이선스 절 등)을
+// 지우지 않는다("파일 끝까지" 자르면 사용자 콘텐츠가 소실된다).
+const SECTION_PREFIX = "\n---\n\n" + MARKER;
+const SECTION_TAIL = "[전체 버전 기록 보기](CHANGELOG.md)\n";
+// PROJECT-COMMON-README-VERSION-UPDATE.yaml(설치되는 CI)은 설치 시점에 이미 사용자가 자기 버전
+// 라인을 갖고 있던 README(addVersionSectionToReadme가 'skip-version-line'으로 건너뛴 경우)에는
+// '---' 구분자 없이 마커 주석 한 줄만 그 버전 라인 위에 끼워넣는다. 이 경우 버전 라인 자체는
+// 사용자 소유이므로 지우지 않고 마커 주석 한 줄만 제거한다.
+const MARKER_LINE = "<!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->\n";
+
+// README.md에 마법사(또는 설치된 CI)가 추가한 흔적이 있는지 확인 (체크리스트 노출 판단용).
+export function hasVersionSection(targetRoot = ".") {
+  const p = join(targetRoot, "README.md");
+  if (!existsSync(p)) return false;
+  const content = readFileSync(p, "utf8");
+  return content.includes(SECTION_PREFIX) || content.includes(MARKER_LINE);
+}
+
+// 반환: 'removed' | 'skip-no-readme' | 'skip-no-marker' | 'skip-unexpected-format'
+export function removeVersionSectionFromReadme(targetRoot = ".") {
+  const p = join(targetRoot, "README.md");
+  if (!existsSync(p)) return "skip-no-readme";
+  const content = readFileSync(p, "utf8");
+
+  const idx = content.indexOf(SECTION_PREFIX);
+  if (idx !== -1) {
+    // 마법사가 append한 전체 블록 케이스 — SECTION_TAIL 라인까지만 잘라내고 그 이후는 보존한다.
+    // tail을 못 찾거나(사용자가 그 줄을 지웠다면), 위저드 블록치고 너무 먼 곳에서 발견되면
+    // (사용자가 같은 문구를 자기 문서 어딘가로 옮겨 적은 경우) 그 사이 사용자 콘텐츠까지
+    // 지워버릴 수 있으므로 어디까지가 "마법사 구간"인지 확신할 수 없어 안전하게 포기한다.
+    // 위저드 블록은 버전 문자열이 길어져도 수백 바이트를 넘지 않는다.
+    const MAX_SECTION_LENGTH = 300;
+    const tailIdx = content.indexOf(SECTION_TAIL, idx);
+    if (tailIdx === -1 || tailIdx > idx + MAX_SECTION_LENGTH) return "skip-unexpected-format";
+    const cutEnd = tailIdx + SECTION_TAIL.length;
+    writeFileSync(p, content.slice(0, idx) + content.slice(cutEnd));
+    return "removed";
+  }
+
+  const markerIdx = content.indexOf(MARKER_LINE);
+  if (markerIdx !== -1) {
+    // CI가 사용자의 기존 버전 라인 위에 마커만 끼워넣은 케이스 — 버전 라인은 건드리지 않는다.
+    writeFileSync(p, content.slice(0, markerIdx) + content.slice(markerIdx + MARKER_LINE.length));
+    return "removed";
+  }
+
+  return "skip-no-marker";
+}

package/src/index.js

@@ -4,6 +4,7 @@
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync, existsSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
 import { parseArgs, parsePathsCsv, CliError } from "./cli/args.js";
 import { HELP_TEXT } from "./cli/help.js";
 import { createContext } from "./context.js";
@@ -12,17 +13,20 @@ import { detectTypes, detectVersion, detectDefaultBranch, detectRepoName, makeRe
 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 { resolveBranchConfig, detectRemoteBranches, ensureDevelopBranch, defaultExec } from "./core/branches.js";
 import { printBannerCompact } from "./ui/banner.js";
 import { printSummary } from "./ui/summary.js";
 import { runFull } from "./commands/full.js";
 import { runVersion } from "./commands/version.js";
 import { runWorkflows } from "./commands/workflows.js";
 import { runRevert } from "./commands/revert.js";
+import { runUninstall, runUninstallFlow } from "./commands/uninstall.js";
+import * as prompts from "./ui/prompts.js";
 import { runInteractive } from "./commands/interactive.js";
 import { runStatus, printStatus } from "./commands/status.js";
 import { runDoctor, printDoctorReport } from "./commands/doctor.js";
 import { planDryRun, printDryRun } from "./commands/dry-run.js";
+import { planPurge, executePurge, printPurgePlan, printPurgeResult } from "./commands/purge.js";
 
 // 패키지 버전 읽기 (-v/--version 출력용). src/../package.json.
 function readPkgVersion() {
@@ -43,10 +47,24 @@ function utcNow(date = new Date()) {
   return { now: `${d} ${t}`, today: d };
 }
 
-// run(argv, opts) → exitCode. opts: { cwd, payloadRoot?, clock? }
+// purge TTY 확인 — 실제 stdin에서 한 줄 입력을 받는다 (테스트는 promptRepoName 주입으로 대체).
+async function defaultPromptRepoName(repoName) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(`purge를 실행하려면 정확히 이 레포명을 입력하세요: ${repoName}\n> `);
+  } finally {
+    rl.close();
+  }
+}
+
+// run(argv, opts) → exitCode. opts: { cwd, payloadRoot?, clock?, exec?, promptRepoName? }
 //   payloadRoot: 테스트 픽스처 주입점 (기본: 패키지 동봉 payload/)
 //   clock: {now, today} 주입 (기본 현재 UTC).
-export async function run(argv, { cwd = process.cwd(), payloadRoot, clock } = {}) {
+//   exec/promptRepoName: purge 모드 안전장치 게이트용 주입점 (기본 실제 구현, 테스트는 mock 주입).
+export async function run(argv, {
+  cwd = process.cwd(), payloadRoot, clock,
+  exec = defaultExec, promptRepoName = defaultPromptRepoName,
+} = {}) {
   let opts;
   try {
     opts = parseArgs(argv);
@@ -63,11 +81,11 @@ export async function run(argv, { cwd = process.cwd(), payloadRoot, clock } = {}
   if (opts.mode === "interactive") {
     // --dry-run은 대화형 모드에서 조용히 무시되면 안 됨(실제 설치가 진행돼버림) — 명시 에러로 차단.
     if (opts.dryRun) {
-      console.error("--dry-run은 --mode <full|version|workflows|revert>와 함께 사용하세요 (대화형 모드에서는 지원하지 않습니다).");
+      console.error("--dry-run은 --mode <full|version|workflows|revert|uninstall>와 함께 사용하세요 (대화형 모드에서는 지원하지 않습니다).");
       return 1;
     }
     if (!process.stdout.isTTY) {
-      console.error("대화형 입력이 불가능한 환경입니다. --mode <full|version|workflows|revert> 와 --force 를 지정하세요.");
+      console.error("대화형 입력이 불가능한 환경입니다. --mode <full|version|workflows|revert|uninstall> 와 --force 를 지정하세요.");
       return 1;
     }
     return await runInteractive({}, { cwd, payloadRoot: payload, clock });
@@ -89,6 +107,109 @@ export async function run(argv, { cwd = process.cwd(), payloadRoot, clock } = {}
     console.error("version.yml·README·.gitignore는 보존됩니다 (사용자 데이터).");
     return 0;
   }
+  // purge 모드 — 마법사가 만든 모든 산출물을 지워 설치 이전 상태로 완전히 되돌린다.
+  // 개발·테스트 전용 숨김 모드 — --help/대화형 메뉴에 노출하지 않는다 (issue #6).
+  if (opts.mode === "purge") {
+    if (!existsSync(join(cwd, ".git"))) {
+      console.error("git 레포가 아닙니다(.git 없음) — purge는 git 레포 안에서만 실행할 수 있습니다.");
+      return 1;
+    }
+    const keepFlags = {
+      versionYml: opts.keepVersionYml, readme: opts.keepReadme, changelog: opts.keepChangelog,
+      workflows: opts.keepWorkflows, scripts: opts.keepScripts, coderabbit: opts.keepCoderabbit,
+    };
+    // version.yml은 여기서 미리 읽어둔다 — (a) executePurge()가 version.yml 자체를 지울 수 있어
+    // 실행 이후에는 읽을 수 없고, (b) 아래 dry-run 예고 문구도 trunk-based 여부(develop === main)를
+    // 알아야 실제 실행 시 삭제를 건너뛸지 미리 알릴 수 있기 때문에, 두 지점보다 앞서 읽어야 한다.
+    const vyPath = join(cwd, "version.yml");
+    const existing = existsSync(vyPath) ? parseExisting(readFileSync(vyPath, "utf8")) : null;
+    if (opts.dryRun) {
+      printPurgePlan(planPurge(payload, cwd, keepFlags), { dryRun: true });
+      // M4 (Fable 검토): develop 브랜치 삭제는 plan에 포함되지 않으므로(§6 — git 상태는 실행 시점에만
+      // 판단 가능) 별도로 예고하지 않으면 dry-run 미리보기가 유일한 파괴적 동작을 사용자에게 숨기게 된다.
+      if (opts.deleteDevelopBranch) {
+        const developBranch = existing?.branches?.develop || "develop";
+        if (existing?.branches?.main && developBranch === existing.branches.main) {
+          console.log("(--delete-develop-branch 지정됨: trunk-based 구성(develop === main)이라 실제 실행 시에도 삭제를 건너뜁니다)");
+        } else {
+          console.log("(--delete-develop-branch 지정됨: 실제 실행 시 로컬 develop 브랜치도 삭제를 시도합니다)");
+        }
+      }
+      return 0;
+    }
+    if (!opts.yes) {
+      console.error("--yes 없이는 purge를 실행할 수 없습니다 (--force로 대체할 수 없습니다).");
+      return 1;
+    }
+    const st = await exec("git", ["status", "--porcelain"], { cwd });
+    if (st.code !== 0) {
+      console.error("git 상태를 확인할 수 없습니다 — 안전을 위해 purge를 중단합니다.");
+      return 1;
+    }
+    if (!opts.allowDirty && st.stdout.trim() !== "") {
+      console.error("작업트리에 커밋되지 않은 변경 사항이 있습니다 — purge 후 복구할 수 없습니다. 커밋하거나 --allow-dirty를 사용하세요.");
+      return 1;
+    }
+    if (!opts.force) {
+      if (!process.stdout.isTTY) {
+        console.error("비대화형 환경에서는 --force 옵션이 필요합니다.");
+        return 1;
+      }
+      const repoName = detectRepoName(cwd);
+      const typed = await promptRepoName(repoName);
+      if (typed !== repoName) {
+        console.error("입력한 레포명이 일치하지 않습니다 — purge를 중단합니다.");
+        return 1;
+      }
+    }
+    const plan = planPurge(payload, cwd, keepFlags);
+    printPurgePlan(plan, { dryRun: false });
+    const result = executePurge(payload, cwd, keepFlags);
+    printPurgeResult(result);
+    if (opts.deleteDevelopBranch) {
+      const developBranch = existing?.branches?.develop || "develop";
+      if (existing?.branches?.main && developBranch === existing.branches.main) {
+        console.error("trunk-based 구성(develop === main)입니다 — 릴리스 브랜치 삭제는 건너뜁니다.");
+      } else {
+        const br = await exec("git", ["branch", "-d", developBranch], { cwd });
+        if (br.code !== 0) {
+          console.error(`⚠️  로컬 '${developBranch}' 브랜치 삭제 실패 (${(br.stderr || "").trim() || "이유 확인 불가"}) — 수동으로 확인하세요.`);
+        } else {
+          console.error(`로컬 '${developBranch}' 브랜치를 삭제했습니다.`);
+        }
+      }
+    }
+    return 0;
+  }
+
+  // uninstall 모드 — revert보다 넓게 README·gitignore·version.yml까지 선택적으로 제거.
+  if (opts.mode === "uninstall") {
+    const safeSelection = {
+      workflows: true, scripts: true, coderabbit: true,
+      readme: opts.purgeReadme, gitignore: opts.purgeGitignore, versionYml: opts.purgeVersion,
+    };
+    if (opts.dryRun) {
+      printDryRun(planDryRun("uninstall", { uninstallSelection: safeSelection }, payload, cwd));
+      return 0;
+    }
+    if (opts.force) {
+      const r = runUninstall({}, payload, cwd, safeSelection);
+      const removed = [
+        `워크플로우 ${r.workflows.length}개`, `스크립트 ${r.scripts.length}개`,
+        r.coderabbit && ".coderabbit.yaml", r.readme && "README 버전 섹션",
+        r.gitignore && ".gitignore 자동 추가 항목", r.versionYml && "version.yml",
+      ].filter(Boolean).join(", ");
+      console.error(`제거됨 — ${removed}`);
+      return 0;
+    }
+    if (!process.stdout.isTTY) {
+      console.error("비대화형 환경에서는 --force 옵션이 필요합니다.");
+      return 1;
+    }
+    await runUninstallFlow(payload, cwd, prompts);
+    return 0;
+  }
+
   // status 모드 — 읽기 전용, TTY/--force 무관하게 항상 동작
   if (opts.mode === "status") {
     printStatus(runStatus(payload, cwd));

package/src/ui/prompts.js

@@ -14,6 +14,7 @@ export async function selectMode() {
       { value: "version", label: "버전 관리만 — 버전 자동 증가·동기화 시스템만 설치" },
       { value: "workflows", label: "워크플로우만 — 빌드·배포 GitHub Actions만 설치" },
       { value: "revert", label: "되돌리기 — 마법사가 설치한 워크플로우·스크립트 제거" },
+      { value: "uninstall", label: "완전 삭제 — 마법사가 설치·수정한 모든 항목 제거(확인 후, README·gitignore·version.yml 포함)" },
     ],
   });
 }