project-auto-wizard 0.1.18 → 0.1.20

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.18 (2026-08-05)
+## 최신 버전 : v0.1.18 (2026-08-06)
 
 [전체 버전 기록 보기](CHANGELOG.md)
 
@@ -154,6 +154,30 @@ npx project-auto-wizard --mode doctor   # 환경 진단 (읽기 전용, 규칙
 | `--mode status` | 설치된 버전·타입·브랜치 모드·옵션값과, 설치 시점 대비 사용자가 직접 수정한 워크플로우 파일 목록을 보여줍니다. 네트워크 접근 없음(로컬 파일 비교만) |
 | `--mode doctor` | `version.yml` 설치 여부, `gh` CLI 설치/인증 상태, GitHub Actions workflow permissions, `WORKFLOW_PAT` secret 등록 여부, merge commit 허용 설정을 점검합니다. `gh api` 호출을 사용하므로 네트워크 접근이 발생합니다(규칙 기반 점검 — AI 진단 아님) |
 
+`doctor`는 항목마다 **그 설정이 무엇을 담당하는지**를 라벨에 함께 표시하고, 문제가 있는 항목만 `현상 → 그대로 두면 무엇이 안 되는지 → 어디를 눌러 고치는지 → 문서 링크` 순으로 펼쳐 보여줍니다. 정상 항목은 한 줄로 압축됩니다. GitHub 설정 화면에 실제로 표시되는 문자열(`Read and write permissions` 등)은 화면에서 찾을 수 있도록 원문 그대로 출력합니다.
+
+```
+◆  환경 진단 — project-auto-wizard doctor
+
+  [✓] gh CLI — 레포 설정 조회용                    gh version 2.96.0
+  [✓] GitHub 로그인 — 레포 설정 조회 권한          인증됨
+  [✓] merge commit 허용 — 릴리스 PR 자동 머지 조건  허용됨
+
+  [!] Workflow permissions — 버전 커밋 자동 push
+      ✗ 현재 read 입니다.
+        워크플로가 버전 올림 커밋을 push하지 못해 릴리스가 중단됩니다.
+      → 레포 Settings → Actions → General → Workflow permissions
+      → "Read and write permissions" 선택 후 Save
+      → 자세히: https://github.com/Twin-Fang/project-auto-wizard#post-install
+
+  [i] GitHub Models — AI 릴리스 노트 생성
+      조직 정책으로 차단됐는지는 자동으로 확인할 수 없습니다 (Settings → Models).
+      차단돼 있어도 규칙 기반 요약으로 자동 전환되므로 그대로 두셔도 됩니다.
+
+  ! 1개 항목에서 문제를 찾았습니다.
+    설치 자체는 지금 진행할 수 있고, 위 1개는 나중에 설정해도 됩니다.
+```
+
 > **드리프트 판정 기준**: `--mode status`는 설치된 워크플로우 파일이 "설치 시점 기본값 템플릿"과 바이트 단위로 일치하는지만 비교합니다 — 파일을 직접 편집했는지는 추적하지 않습니다. 대화형 설치에서 `@wizard ask` 질문(예: 배포 포트)에 기본값이 아닌 값으로 응답했다면, 파일을 전혀 수정하지 않았더라도 설치 직후부터 항상 "사용자가 수정한 워크플로우 파일"로 표시됩니다. 정상 동작이며, 파일을 직접 편집했는지 구분하려면 해당 값이 예상한 응답과 일치하는지 직접 확인하세요.
 
 `--dry-run`을 어떤 모드와도 함께 쓰면 실제로 파일을 바꾸지 않고 무엇이 바뀔지만 미리 보여줍니다(`full`/`version`/`workflows`/`revert` 전체 지원):
@@ -177,6 +201,8 @@ npx project-auto-wizard --no-semver-auto   # 항상 patch+1 (레거시 동작)
 
 기본 설치(pr-flow) 기준으로 일상적인 기능 PR은 `develop`을 대상으로 열리므로, 이 봇은 develop→main 릴리스 PR에서만 실제로 동작합니다 — 해당 PR에서는 `AUTO-CHANGELOG-CONTROL`이 이미 같은 엔진으로 체인지로그 요약을 생성하므로, 이 봇은 그 요약을 PR 코멘트 형태로도 남겨주는 보조 역할입니다. 릴리스 브랜치 = 개발 브랜치인 trunk-based 모드에서는 모든 PR이 곧 릴리스 대상 브랜치를 향하므로 매 PR마다 동작합니다.
 
+<a id="post-install"></a>
+
 ## 설치 후 확인할 것
 
 | 항목 | 내용 |

package/package.json

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

package/src/commands/doctor.js

@@ -1,73 +1,219 @@
 // doctor 명령 — 로컬 환경 진단(읽기 전용, 규칙 기반). gh CLI에 위임해 원격 상태를 점검한다.
 // AI 진단은 포함하지 않는다(스펙 §4에서 검토 후 기각 — 복잡도 대비 이득 낮음).
+//
+// 출력 설계(이슈 #29) — `flutter doctor` 패턴을 차용한다.
+//   ① 항목 라벨에 purpose("무엇을 위한 설정인지")를 병기한다. `WORKFLOW_PAT`만 보고는 그게
+//      자기 릴리스 흐름의 무엇을 담당하는지 알 수 없다 — flutter의
+//      `Android toolchain - develop for Android devices`와 같은 이유다.
+//   ② 도구가 "설치해도 된다/안 된다"를 판정하지 않는다. 발견한 사실(문제 N개)만 진술하고
+//      그게 자신에게 문제인지는 사용자가 판단한다.
+//   ③ 문제 항목만 `현상 → 영향 → 조치 → 문서` 4단으로 펼치고, 정상 항목은 한 줄로 압축한다.
+//   ④ GitHub 설정 화면에 실제로 표시되는 문자열("Read and write permissions" 등)은 번역하지
+//      않는다. 번역하면 설명은 읽히지만 정작 화면에서 그 항목을 찾지 못한다.
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { A, paint, colorEnabled, visualWidth } from "../ui/ansi.js";
 
 const defaultExec = (cmd, args) => spawnSync(cmd, args, { encoding: "utf8" });
 
+// 해결 가이드 링크 (스펙 2026-07-25-osscontest-scope-design.md §3.3② "각 실패 항목에 대한
+// 해결 가이드 링크(README 앵커)"). README에 심은 영문 HTML 앵커를 가리킨다 — 한글 헤딩
+// 자동 앵커는 URL 인코딩되어 터미널에서 알아볼 수 없게 깨진다.
+const REPO_URL = "https://github.com/Twin-Fang/project-auto-wizard";
+export const DOC = {
+  postInstall: `${REPO_URL}#post-install`,
+};
+
 export function runDoctor(cwd = process.cwd(), { exec = defaultExec } = {}) {
   const results = [];
-  const add = (name, status, detail) => { results.push({ name, status, detail }); return results; };
+  // name은 항목 식별자(테스트·프로그램 참조용), label은 화면 표기용. label 생략 시 name을 쓴다.
+  const add = (item) => { results.push({ actions: [], ...item }); return results; };
 
   const installed = existsSync(join(cwd, "version.yml"));
-  add("설치 여부", installed ? "OK" : "WARN",
-    installed ? "version.yml 발견" : "이 디렉터리에 project-auto-wizard가 설치되어 있지 않습니다 (version.yml 없음)");
+  // 미설치는 문제가 아니다 — doctor는 설치 "전에" 돌려보는 것이 정상 사용 경로다.
+  add(installed
+    ? { name: "설치 여부", label: "설치 상태", purpose: "이 폴더의 마법사 설치 여부", status: "OK", value: "version.yml 있음" }
+    : {
+      name: "설치 여부", label: "설치 상태", purpose: "이 폴더의 마법사 설치 여부", status: "INFO",
+      note: ["이 폴더엔 아직 설치되지 않았습니다 — 지금 설치하면 됩니다."],
+    });
 
   const ghVersion = exec("gh", ["--version"]);
   if (ghVersion.error || ghVersion.status !== 0) {
-    add("gh CLI", "WARN", "gh CLI를 찾을 수 없습니다 — 원격 점검을 건너뜁니다 (https://cli.github.com/ 설치 권장)");
+    add({
+      name: "gh CLI", purpose: "레포 설정 조회용", status: "WARN",
+      value: "gh CLI를 찾을 수 없습니다.",
+      impact: ["레포 권한·secret 설정을 조회할 수 없어 아래 원격 점검을 모두 건너뜁니다."],
+      actions: ["https://cli.github.com/ 에서 gh CLI를 설치한 뒤 다시 실행하세요"],
+    });
     return results;
   }
-  add("gh CLI", "OK", (ghVersion.stdout || "").split("\n")[0] || "설치됨");
+  add({
+    name: "gh CLI", purpose: "레포 설정 조회용", status: "OK",
+    value: (ghVersion.stdout || "").split("\n")[0] || "설치됨",
+  });
 
   const auth = exec("gh", ["auth", "status"]);
   const authOk = !auth.error && auth.status === 0;
-  add("gh 인증", authOk ? "OK" : "FAIL", authOk ? "인증됨" : "`gh auth login`이 필요합니다");
-  if (!authOk) return results;
+  if (!authOk) {
+    add({
+      name: "gh 인증", label: "GitHub 로그인", purpose: "레포 설정 조회 권한", status: "FAIL",
+      value: "로그인되어 있지 않습니다.",
+      impact: ["레포 설정을 읽을 수 없어 아래 원격 점검을 모두 건너뜁니다."],
+      actions: ["터미널에서 `gh auth login` 실행"],
+    });
+    return results;
+  }
+  add({ name: "gh 인증", label: "GitHub 로그인", purpose: "레포 설정 조회 권한", status: "OK", value: "인증됨" });
 
   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)?$/);
   if (!match) {
-    add("GitHub 원격", "WARN", "origin 리모트에서 GitHub owner/repo를 확인하지 못했습니다");
+    add({
+      name: "GitHub 원격", purpose: "점검 대상 레포 식별", status: "WARN",
+      value: "origin 리모트에서 GitHub owner/repo를 찾지 못했습니다.",
+      impact: ["어느 레포를 점검해야 할지 알 수 없어 아래 원격 점검을 모두 건너뜁니다."],
+      actions: ["`git remote -v`로 origin이 GitHub 주소를 가리키는지 확인하세요"],
+    });
     return results;
   }
   const [, owner, repo] = match;
 
   const perm = exec("gh", ["api", `repos/${owner}/${repo}/actions/permissions/workflow`, "--jq", ".default_workflow_permissions"]);
   const permValue = (perm.stdout || "").trim();
-  add("Workflow permissions", perm.status === 0 && permValue === "write" ? "OK" : "WARN",
-    perm.status === 0
-      ? `현재값: ${permValue || "확인불가"} (Settings → Actions → General → Workflow permissions: Read and write 권장)`
-      : "조회 실패 — repo 관리자 권한이 필요할 수 있습니다");
+  if (perm.status !== 0) {
+    add({
+      name: "Workflow permissions", purpose: "버전 커밋 자동 push", status: "WARN",
+      value: "설정을 조회하지 못했습니다.",
+      impact: ["레포 관리자 권한이 없으면 이 설정은 조회되지 않습니다 — 값 자체는 정상일 수 있습니다."],
+      actions: ["레포 관리자에게 Settings → Actions → General → Workflow permissions 값을 확인하세요"],
+      doc: DOC.postInstall,
+    });
+  } else if (permValue === "write") {
+    add({ name: "Workflow permissions", purpose: "버전 커밋 자동 push", status: "OK", value: "Read and write" });
+  } else {
+    add({
+      name: "Workflow permissions", purpose: "버전 커밋 자동 push", status: "WARN",
+      value: `현재 ${permValue || "확인불가"} 입니다.`,
+      impact: ["워크플로가 버전 올림 커밋을 push하지 못해 릴리스가 중단됩니다."],
+      actions: [
+        "레포 Settings → Actions → General → Workflow permissions",
+        '"Read and write permissions" 선택 후 Save',
+      ],
+      doc: DOC.postInstall,
+    });
+  }
 
   const secrets = exec("gh", ["secret", "list", "--repo", `${owner}/${repo}`]);
   const hasPat = secrets.status === 0 && (secrets.stdout || "").split("\n").some((l) => l.startsWith("WORKFLOW_PAT"));
-  add("WORKFLOW_PAT secret", hasPat ? "OK" : "WARN",
-    hasPat
-      ? "등록됨"
-      : "미등록 — automerge 후 후속 워크플로우(tag/Release)가 트리거되지 않을 수 있습니다. Settings → Secrets → Actions에 등록 (scopes: repo, workflow)");
+  add(hasPat
+    ? { name: "WORKFLOW_PAT secret", label: "WORKFLOW_PAT", purpose: "자동 태그·Release 발행", status: "OK", value: "등록됨" }
+    : {
+      name: "WORKFLOW_PAT secret", label: "WORKFLOW_PAT", purpose: "자동 태그·Release 발행", status: "WARN",
+      value: "secret이 등록되어 있지 않습니다.",
+      impact: [
+        "PR 자동 머지 뒤 태그·Release 워크플로가 이어지지 않습니다.",
+        "(GitHub 정책상 기본 토큰으로 만든 커밋은 다음 워크플로를 깨우지 못합니다)",
+      ],
+      actions: [
+        "개인 액세스 토큰 발급 (scopes: repo, workflow)",
+        "레포 Settings → Secrets and variables → Actions",
+        "New repository secret · 이름은 WORKFLOW_PAT",
+      ],
+      doc: DOC.postInstall,
+    });
 
   const mergeSettings = exec("gh", ["api", `repos/${owner}/${repo}`, "--jq", ".allow_merge_commit"]);
   const automergeOk = mergeSettings.status === 0 && mergeSettings.stdout.trim() === "true";
-  add("automerge 호환성(merge commit 허용)", automergeOk ? "OK" : "WARN",
-    mergeSettings.status === 0
-      ? (automergeOk
-        ? "머지 커밋 허용됨"
-        : "이 레포는 merge commit이 비활성화되어 있습니다 — automerge/RELEASE-PUBLISH가 머지 커밋 subject를 감지하는 방식과 충돌할 수 있습니다. Settings → General → Pull Requests → Allow merge commits 활성화 권장")
-      : "조회 실패 — repo 관리자 권한이 필요할 수 있습니다");
+  if (mergeSettings.status !== 0) {
+    add({
+      name: "automerge 호환성(merge commit 허용)", label: "merge commit 허용", purpose: "릴리스 PR 자동 머지 조건", status: "WARN",
+      value: "설정을 조회하지 못했습니다.",
+      impact: ["레포 관리자 권한이 없으면 이 설정은 조회되지 않습니다 — 값 자체는 정상일 수 있습니다."],
+      actions: ["레포 관리자에게 Settings → General → Pull Requests 설정을 확인하세요"],
+      doc: DOC.postInstall,
+    });
+  } else if (automergeOk) {
+    add({ name: "automerge 호환성(merge commit 허용)", label: "merge commit 허용", purpose: "릴리스 PR 자동 머지 조건", status: "OK", value: "허용됨" });
+  } else {
+    add({
+      name: "automerge 호환성(merge commit 허용)", label: "merge commit 허용", purpose: "릴리스 PR 자동 머지 조건", status: "WARN",
+      value: "이 레포는 merge commit이 꺼져 있습니다.",
+      impact: ["RELEASE-PUBLISH가 머지 커밋 제목으로 릴리스를 감지하므로 자동 머지 흐름이 어긋날 수 있습니다."],
+      actions: [
+        "레포 Settings → General → Pull Requests",
+        "Allow merge commits 체크",
+      ],
+      doc: DOC.postInstall,
+    });
+  }
 
-  add("GitHub Models 활성화", "INFO",
-    "자동 확인 불가 — Settings → Models에서 조직 정책으로 차단되지 않았는지 직접 확인하세요 (차단 시 규칙 기반 fallback으로 자동 전환됩니다)");
+  add({
+    name: "GitHub Models 활성화", label: "GitHub Models", purpose: "AI 릴리스 노트 생성", status: "INFO",
+    note: [
+      "조직 정책으로 차단됐는지는 자동으로 확인할 수 없습니다 (Settings → Models).",
+      "차단돼 있어도 규칙 기반 요약으로 자동 전환되므로 그대로 두셔도 됩니다.",
+    ],
+  });
 
   return results;
 }
 
-export function printDoctorReport(results) {
-  const icon = { OK: "✅", WARN: "⚠️ ", FAIL: "❌", INFO: "ℹ️ " };
-  const lines = ["", "project-auto-wizard doctor — 환경 진단 결과", ""];
-  for (const r of results) lines.push(`${icon[r.status] || "  "} [${r.status}] ${r.name} — ${r.detail}`);
-  lines.push("");
-  console.log(lines.join("\n"));
+const asLines = (v) => (Array.isArray(v) ? v : v ? [String(v)] : []);
+const headOf = (r) => `${r.label || r.name}${r.purpose ? ` — ${r.purpose}` : ""}`;
+
+export function printDoctorReport(results, { out = (s) => console.log(s), color = colorEnabled() } = {}) {
+  const p = (s, c) => paint(s, c, color);
+  const oks = results.filter((r) => r.status === "OK");
+  const problems = results.filter((r) => r.status === "WARN" || r.status === "FAIL");
+  const infos = results.filter((r) => r.status === "INFO");
+
+  const lines = ["", `${p("◆", A.cyan)}  ${p("환경 진단", A.bold)} ${p("— project-auto-wizard doctor", A.dim)}`, ""];
+
+  // 정상 — 한 줄씩. 값은 라벨 폭에 맞춰 우측으로 정렬한다(CJK 2칸 계산은 visualWidth에 위임).
+  if (oks.length) {
+    const width = Math.max(...oks.map((r) => visualWidth(headOf(r))));
+    for (const r of oks) {
+      const head = headOf(r);
+      const pad = " ".repeat(width - visualWidth(head) + 4);
+      lines.push(`  ${p("[✓]", A.green)} ${head}${r.value ? `${pad}${p(r.value, A.dim)}` : ""}`);
+    }
+    lines.push("");
+  }
+
+  // 문제 — 현상 → 영향 → 조치 → 문서 순으로 펼친다.
+  for (const r of problems) {
+    const fail = r.status === "FAIL";
+    lines.push(`  ${p(fail ? "[✗]" : "[!]", fail ? A.red : A.yellow)} ${p(headOf(r), A.bold)}`);
+    if (r.value) lines.push(`      ${p(fail ? "✗" : "✗", fail ? A.red : A.yellow)} ${r.value}`);
+    for (const l of asLines(r.impact)) lines.push(`        ${p(l, A.dim)}`);
+    for (const a of asLines(r.actions)) lines.push(`      ${p("→", A.cyan)} ${a}`);
+    if (r.doc) lines.push(`      ${p("→", A.cyan)} 자세히: ${p(r.doc, A.dim)}`);
+    lines.push("");
+  }
+
+  // 참고 — 조치가 필요 없는 안내.
+  for (const r of infos) {
+    lines.push(`  ${p("[i]", A.gray)} ${headOf(r)}`);
+    for (const l of asLines(r.note)) lines.push(`      ${p(l, A.dim)}`);
+  }
+  if (infos.length) lines.push("");
+
+  lines.push(summaryLine(problems, p), "");
+  out(lines.join("\n"));
+}
+
+// 요약 — "설치해도 된다"는 판정 대신 발견한 사실만 말한다(flutter doctor의 마지막 줄과 같은 태도).
+function summaryLine(problems, p) {
+  if (!problems.length) return `  ${p("✓", A.green)} 문제를 찾지 못했습니다.`;
+  const n = problems.length;
+  if (problems.some((r) => r.status === "FAIL")) {
+    return `  ${p("✗", A.red)} ${n}개 항목에서 문제를 찾았습니다 — 일부 점검은 실행하지 못했습니다.`;
+  }
+  return [
+    `  ${p("!", A.yellow)} ${n}개 항목에서 문제를 찾았습니다.`,
+    `    설치 자체는 지금 진행할 수 있고, 위 ${n}개는 나중에 설정해도 됩니다.`,
+  ].join("\n");
 }

package/src/commands/interactive.js

@@ -43,12 +43,17 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), payloadRoot
   io.installKind?.({ currentTemplateVersion: existing?.templateVersion || "", templateVersion });
 
   // 1) 모드 선택
-  const mode = await io.selectMode();
-  if (mode === CANCEL || mode == null) { io.cancelMessage?.("설치를 취소했습니다."); return 0; }
-
-  // status/doctor — 읽기 전용, 감지·breaking 게이트 불필요. CLI --mode status/doctor(index.js)와 동일하게 즉시 종료.
-  if (mode === "status") { printStatus(runStatus(payload, cwd)); return 0; }
-  if (mode === "doctor") { printDoctorReport(runDoctor(cwd)); return 0; }
+  // status/doctor — 읽기 전용이라 감지·breaking 게이트가 필요 없다. 결과를 보여준 뒤 메뉴로
+  // 돌아온다(이슈 #31): 진단의 목적이 설치 준비이므로 확인 → 설치를 한 세션에서 끝내야 한다.
+  // CLI 경로(index.js의 --mode status/doctor)는 단발 명령이므로 지금처럼 즉시 종료한다.
+  let mode;
+  for (let round = 0; ; round++) {
+    mode = await io.selectMode({ again: round > 0 });
+    if (mode === CANCEL || mode == null) { io.cancelMessage?.("설치를 취소했습니다."); return 0; }
+    if (mode === "status") { printStatus(runStatus(payload, cwd)); continue; }
+    if (mode === "doctor") { printDoctorReport(runDoctor(cwd)); continue; }
+    break;
+  }
 
   // revert 모드 — 확인 질문(기본 아니오) 후 payload 유래 파일 제거. 감지·breaking 게이트 불필요.
   if (mode === "revert") {

package/src/ui/ansi.js

@@ -7,6 +7,7 @@ export const A = {
   cyan: `${E}36m`,
   green: `${E}32m`,
   yellow: `${E}33m`,
+  red: `${E}31m`,
   magenta: `${E}35m`,
   gray: `${E}90m`,
 };

package/src/ui/prompts.js

@@ -6,9 +6,11 @@ import * as engine from "./readline-engine.js";
 export const CANCEL = engine.CANCEL;
 
 // 모드 선택 — 한국어 라벨, 내부 키 반환. 취소 시 CANCEL.
-export async function selectMode() {
+// again=true는 읽기 전용 모드(status/doctor)를 실행하고 메뉴로 돌아온 재진입이다 —
+// 이때 "무엇을 설치할까요?"를 다시 묻는 건 어색하므로 문구를 바꾼다.
+export async function selectMode({ again = false } = {}) {
   return engine.select({
-    message: "무엇을 설치할까요?",
+    message: again ? "다음으로 무엇을 할까요?" : "무엇을 설치할까요?",
     options: [
       { value: "full", label: "전체 설치 — 버전관리 + 자동화 워크플로우 (처음이라면 추천)" },
       { value: "version", label: "버전 관리만 — 버전 자동 증가·동기화 시스템만 설치" },