project-auto-wizard 0.8.2 → 0.9.0

package/README.md

@@ -17,7 +17,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.8.2 (2026-08-26)
+## 최신 버전 : v0.9.0 (2026-08-29)
 
 [전체 버전 기록 보기](CHANGELOG.md)
 
@@ -75,11 +75,20 @@ flutter.APP_ARTIFACT_NAME:
 - **python**: CI / PR 프리뷰 / SimpleCICD
 - **go**: CI(Dockerfile 불필요, go test/vet/build/lint) / PR 프리뷰 / SimpleCICD(Dockerfile 있는 프로젝트만 해당)
 
-### 설치 기록 (`.github/.wizard/logs/`)
+### 실행 로그 (`.github/.wizard/logs/`)
 
-설치가 끝나면 그 실행에서 무엇을 어떤 값으로 설치했는지 `.github/.wizard/logs/<시각>-install.md`에 한 건 남깁니다. 감지된 타입과 그 근거 파일, 버전, 브랜치, 선택 워크플로우, **환경설정 질문별 답변(기본값 그대로인지 여부 포함)**, 설치된 파일, 값이 채워지지 않은 항목, 등록해야 하는 GitHub Secret이 담깁니다.
+설치·업데이트·삭제를 실행할 때마다 `.github/.wizard/logs/<시각>-<동작>.log`에 실행 추적이 남습니다. 감지 근거, **파일별 처리 결정과 그 사유**, 치환된 값, 미치환 항목, 등록해야 하는 GitHub Secret이 시간순으로 기록되고, 파일 끝에 결과 요약이 붙습니다.
 
-상단은 기계가 읽는 YAML front matter, 아래는 사람이 읽는 마크다운입니다. 배포가 예상과 다르게 동작할 때 "설치할 때 뭘로 답했더라"를 여기서 확인할 수 있고, 레포에 커밋되므로 AI 에이전트나 다른 팀원도 참고할 수 있습니다. 로그 기록에 실패해도 설치 자체는 정상 완료됩니다.
+```
+07:46:01 INFO  detect    type        spring (근거: build.gradle)
+07:46:01 INFO  copy      write       PROJECT-SPRING-SIMPLE-CICD.yaml (new)
+07:46:01 INFO  copy      keep-local  PROJECT-COMMON-VERSION-CONTROL.yaml (업스트림 무변경, 사용자 수정본 유지)
+07:46:01 WARN  verify    unresolved  PROJECT-SPRING-PR-PREVIEW.yaml:43 __APPLICATION_YML_PATH__
+```
+
+업데이트에서 "내가 고친 워크플로우가 유지됐는지 덮였는지"를 이 로그로 확인할 수 있습니다. 한 줄씩 즉시 기록하므로 도중에 중단되어도 직전까지의 흐름이 남습니다. 로그 기록에 실패해도 설치 자체는 정상 완료됩니다.
+
+이 폴더에는 자체 `.gitignore`(`*`, `!.gitignore`)가 함께 생성되어 **로그가 git에 올라가지 않습니다**. 최근 20개만 보관하고 오래된 것부터 정리합니다. `--dry-run`은 파일을 만들지 않는 것이 계약이므로 로그도 남기지 않습니다.
 
 `.github/.wizard/`에는 업데이트 3-way 판정에 쓰는 `baseline.json`도 함께 들어 있어, 완전 삭제 시 워크플로우와 함께 제거됩니다.
 

package/package.json

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

package/payload/scripts/issue_helper.py

@@ -61,11 +61,15 @@ def extract_issue_number(issue_url):
     return parts[-1] if parts and parts[-1] else ""
 
 
-_BRANCH_ISSUE_RE = re.compile(r"#(\d+)")
+_BRANCH_ISSUE_HASH_RE = re.compile(r"#(\d+)")
+_BRANCH_ISSUE_WORD_RE = re.compile(r"issues?[-_/](\d+)", re.IGNORECASE)
 
 
 def extract_issue_number_from_branch(branch_name):
-    match = _BRANCH_ISSUE_RE.search(branch_name)
+    match = _BRANCH_ISSUE_HASH_RE.search(branch_name)
+    if match:
+        return match.group(1)
+    match = _BRANCH_ISSUE_WORD_RE.search(branch_name)
     return match.group(1) if match else None
 
 

package/src/commands/full.js

@@ -16,7 +16,7 @@ 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 { writeInstallLog } from "../core/install-log.js";
+import { log, maskValue } from "../core/logger.js";
 
 // context: { version, types, paths:Map, branch, versionCode, includeNexus, includeSecretBackup,
 //            force, repoName, resolvers, now, today }
@@ -31,7 +31,16 @@ export function runFull(context, payloadRoot, targetRoot = ".", hooks = {}) {
   // 대표 마커명이 아니라 그 폴더에 실제로 있는 파일을 쓴다 — build.gradle.kts만 있는 레포의
   // version.yml에 "# build.gradle"이라고 적히면 감지 로그와 같은 종류의 거짓말이 된다 (이슈 #77).
   const pathMarkers = new Map();
-  for (const [t, p] of paths) pathMarkers.set(t, existingMarkerInDir(t, join(targetRoot, p || ".")));
+  for (const [t, p] of paths) {
+    const marker = existingMarkerInDir(t, join(targetRoot, p || "."));
+    pathMarkers.set(t, marker);
+    log.info("detect", "type", `${t} (근거: ${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}` : ""}`);
+  for (const a of context.envAnswers || []) {
+    log.info("prompt", a.isDefault ? "default" : "answer", `${a.key}=${maskValue(a.key, a.value)}`);
+  }
 
   // 1. 워크플로우 복사 (+ env 치환) — deploy 블록에 쓸 ask 값을 수집한다.
   //    hooks.decisions: 대화형 충돌 3지선 결정 Map (미지정=skip — 현행 force 동작)
@@ -46,6 +55,8 @@ export function runFull(context, payloadRoot, targetRoot = ".", hooks = {}) {
   writeText(join(targetRoot, PATHS.versionFile),
     renderVersionYml(context, readVersionYmlTemplate(payloadRoot), { pathMarkers, deployValues, extraTopLevel }));
 
+  log.info("version", "write", `version.yml (v${version}, code=${versionCode})`);
+
   // 3. README 버전 섹션
   addVersionSectionToReadme(version, targetRoot);
 
@@ -67,6 +78,8 @@ export function runFull(context, payloadRoot, targetRoot = ".", hooks = {}) {
   // 지운 파일의 기준점은 baseline에서도 빼야 다음 실행에서 "사용자가 지웠다"로 오인하지 않는다.
   for (const f of [...cleanup.removed, ...cleanup.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`);
   const gitignoreUpdated = gitignoreUpdated0 || cleanup.backedUp.length > 0;
   if (gitignoreUpdated) ensureGitignore(targetRoot);
 
@@ -95,33 +108,21 @@ export function runFull(context, payloadRoot, targetRoot = ".", hooks = {}) {
     firstDeployValue(deployValues, "SSH_AUTH_METHOD"),
   );
 
-  // 9. 설치 로그 (이슈 #79) — 이 실행에서 무엇을 어떤 값으로 설치했는지 레포에 남긴다.
-  //    실패해도 설치는 성공으로 끝난다.
-  const installLog = writeInstallLog(targetRoot, {
-    action: context.previousTemplateVersion ? "update" : "install",
-    at: now || today || "",
-    templateVersion,
-    previousTemplateVersion: context.previousTemplateVersion || "",
-    mode: context.mode || "full",
-    types, markers: context.markers || new Map(), version,
-    versionSource: context.versionSource || "",
-    branch, branches: context.branches, paths,
-    options: {
-      nexus: includeNexus,
-      secretBackup: includeSecretBackup,
-      semverAuto: includeSemverAuto !== false,
-      deployStyle: context.deployStyle || "",
-    },
-    answers: context.envAnswers || [],
-    warnings: context.detectWarnings || [],
-    result: {
-      copiedFiles: wfCounters.copiedFiles || [],
-      gitignoreUpdated,
-    },
-    unresolved, secrets, cleanup,
-  });
+  // 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(", ")}`);
+  log.summary([
+    ["설치", `${(wfCounters.copiedFiles || []).length}개 파일`],
+    ["자동 갱신", `${(wfCounters.autoUpdated || []).length}개 (사용자 미수정)`],
+    ["유지", `${(wfCounters.keptLocal || []).length}개 (사용자 수정본)`],
+    ["변경 없음", `${(wfCounters.unchangedFiles || []).length}개`],
+    ["백업 교체", `${wfCounters.backupAdded || 0}개 (.bak 생성)`],
+    ["미치환", `${unresolved.length}건${unresolved.length ? "  ← 조치 필요" : ""}`],
+    ["필요 Secret", `${secrets.size}개`],
+    ["결과", unresolved.length ? `주의 (미치환 ${unresolved.length}건)` : "OK"],
+  ]);
 
-  return { workflows: wfCounters, gitignoreUpdated, unresolved, secrets, installLog, cleanup };
+  return { workflows: wfCounters, gitignoreUpdated, unresolved, secrets, cleanup };
 }
 
 // deployValues는 Map<type, Map<key,value>> — 타입 구분 없이 첫 값만 필요할 때 쓴다.

package/src/commands/interactive.js

@@ -20,6 +20,7 @@ import { runUninstallFlow } from "./uninstall.js";
 import * as prompts from "../ui/prompts.js";
 import { runStatus, printStatus } from "./status.js";
 import { runDoctor, printDoctorReport } from "./doctor.js";
+import { currentLogPath, hasLegacyMdLogs } from "../core/logger.js";
 
 const CANCEL = prompts.CANCEL;
 const isCancel = (v) => v === CANCEL || typeof v === "symbol";
@@ -305,7 +306,8 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), payloadRoot
     answers: envAnswers,
     unresolved: result?.unresolved ?? [],
     secrets: result?.secrets ?? new Map(),
-    installLogPath: result?.installLog?.path ?? "",
+    logPath: currentLogPath(),
+    legacyMdLogs: hasLegacyMdLogs(cwd),
     cleanup: result?.cleanup ?? null,
   });
   io.outro?.(`통합 완료 — ${mode} 모드로 설치했습니다.`);

package/src/commands/purge.js

@@ -9,6 +9,7 @@ import { PATHS } from "../core/paths.js";
 import { remove } from "../core/fsutil.js";
 import { planRemoval } from "../core/removal-plan.js";
 import { removeVersionSectionFromReadme, hasVersionSection } from "../core/copy/readme.js";
+import { log } from "../core/logger.js";
 
 const CHANGELOG_FILES = ["CHANGELOG.json", "CHANGELOG.md"];
 
@@ -54,12 +55,12 @@ export function printPurgePlan(plan, { dryRun = false } = {}) {
 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));
-  for (const p of plan.baseline || []) remove(join(targetRoot, p));
-  if (plan.versionYml) remove(join(targetRoot, PATHS.versionFile));
+  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); }
+  if (plan.versionYml) { remove(join(targetRoot, PATHS.versionFile)); log.info("remove", "version", PATHS.versionFile); }
   const readmeSection = plan.readmeSection && removeVersionSectionFromReadme(targetRoot) === "removed";
-  for (const f of plan.changelog) remove(join(targetRoot, f));
+  for (const f of plan.changelog) { remove(join(targetRoot, f)); log.info("remove", "changelog", f); }
   return { ...plan, readmeSection };
 }
 

package/src/commands/uninstall.js

@@ -9,6 +9,7 @@ import { planRemoval } 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";
 
 // selection: { workflows, scripts, readme, gitignore, versionYml } (모두 boolean).
 // 반환: 위와 동일한 키의 boolean/배열 — 실제로 제거 "대상"인지 여부(순수 함수, 아무것도 지우지 않음).
@@ -29,16 +30,16 @@ 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));
-  for (const name of plan.scripts) remove(join(targetRoot, PATHS.scriptsDir, name));
-  for (const p of plan.baseline || []) remove(join(targetRoot, p));
+  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); }
   // 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));
+  if (plan.versionYml) { remove(join(targetRoot, PATHS.versionFile)); log.info("remove", "version", PATHS.versionFile); }
   return { ...plan, readme: readmeRemoved, gitignore: gitignoreRemoved };
 }
 

package/src/core/copy/workflows.js

@@ -10,6 +10,7 @@ import { exists, writeText, listYamlFiles } from "../fsutil.js";
 import { substituteEnv } from "../wizard-env.js";
 import { substitute } from "../branding.js";
 import { sha256, readBaseline } from "../baseline.js";
+import { log } from "../logger.js";
 
 // 원본 텍스트 로더 — context.branches가 있으면 {{MAIN_BRANCH}}/{{DEVELOP_BRANCH}} 치환 적용.
 // classify(unchanged 판정)와 실제 복사가 같은 치환본을 봐야 재실행 시 가짜 충돌이 없다.
@@ -97,20 +98,37 @@ function processDir(srcDir, workflowsDir, envOpts, ctx, counters, filter = () =>
   const track = (f, wrote) => baselineTargets.set(f, { srcPath: join(srcDir, f), envOpts, wrote });
   const write = (f) => { writeText(join(workflowsDir, f), srcText(join(srcDir, f))); counters.copied++; counters.copiedFiles.push(f); track(f, true); };
 
-  for (const f of c.unchanged.filter(filter)) { counters.skipped++; track(f, false); }
+  for (const f of c.unchanged.filter(filter)) {
+    counters.skipped++; counters.unchangedFiles.push(f); track(f, false);
+    log.info("copy", "skip", `${f} (unchanged)`);
+  }
 
-  for (const f of c.localOnly.filter(filter)) { counters.skipped++; counters.keptLocal.push(f); track(f, false); }
+  for (const f of c.localOnly.filter(filter)) {
+    counters.skipped++; counters.keptLocal.push(f); track(f, false);
+    log.info("copy", "keep-local", `${f} (업스트림 무변경, 사용자 수정본 유지)`);
+  }
 
-  for (const f of c.newFiles.filter(filter)) write(f);
+  for (const f of c.newFiles.filter(filter)) {
+    write(f);
+    log.info("copy", "write", `${f} (new)`);
+  }
 
-  for (const f of c.upstreamOnly.filter(filter)) { write(f); counters.autoUpdated.push(f); }
+  for (const f of c.upstreamOnly.filter(filter)) {
+    write(f); counters.autoUpdated.push(f);
+    log.info("copy", "auto-update", `${f} (사용자 미수정, 최신으로 교체)`);
+  }
 
   // 사용자가 지운 파일은 조용히 되살리지 않는다. 복원 결정이 있을 때만 다시 쓴다.
   // 되살리지 않은 파일은 baselineTargets에 넣지 않는다 — 디스크에 없어 해시할 것이 없고,
   // 기존 baseline 항목은 병합으로 남아 다음 실행에서도 "지운 파일"로 인식된다.
   for (const f of c.removed.filter(filter)) {
-    if (restoreRemoved.has(f)) { write(f); counters.restoredFiles.push(f); }
-    else counters.removedKept.push(f);
+    if (restoreRemoved.has(f)) {
+      write(f); counters.restoredFiles.push(f);
+      log.info("copy", "restore", `${f} (사용자가 지웠지만 복원 결정)`);
+    } else {
+      counters.removedKept.push(f);
+      log.info("copy", "removed-kept", `${f} (사용자가 지움, 되살리지 않음)`);
+    }
   }
 
   for (const f of c.changed.filter(filter)) {
@@ -141,6 +159,7 @@ export function copyWorkflows(context, payloadRoot, targetRoot = ".", hooks = {}
   const deployValues = new Map(); // Map<type, Map<key,value>> — deploy 블록용 ask 값
   counters.deployValues = deployValues;
   counters.copiedFiles = []; // 이번 실행에서 실제로 새로 쓰여진 파일명 (issue #19 — printSummary 정확성용)
+  counters.unchangedFiles = []; // skip(unchanged) 대상 — 로그에서 "왜 안 바뀌었나"의 근거
   counters.autoUpdated = [];    // 질문 없이 최신으로 교체된 파일 (사용자 미수정)
   counters.keptLocal = [];      // 질문 없이 사용자 수정본을 유지한 파일 (업스트림 무변경)
   counters.removedKept = [];    // 사용자가 지웠고 되살리지 않은 파일
@@ -228,6 +247,7 @@ function applyDecision(decision, srcDir, workflowsDir, filename, counters, srcTe
     counters.copied++;
     counters.backupAdded++;
     counters.copiedFiles.push(filename);
+    log.info("copy", "backup", `${filename} → ${filename}.bak (사용자 결정, 새 버전으로 교체)`);
     return;
   }
   if (decision === "template") {
@@ -236,9 +256,11 @@ function applyDecision(decision, srcDir, workflowsDir, filename, counters, srcTe
     writeText(join(workflowsDir, templateName), srcText(src)); // 기존 .template.yaml 덮어씀(.sh rm -f + cp 등가)
     counters.templateAdded++;
     counters.copiedFiles.push(templateName);
+    log.info("copy", "template", `${filename} 유지 + ${templateName} 생성 (사용자 결정)`);
     return;
   }
   counters.skipped++; // 'skip'/미지정/ESC → 기존 유지 (.sh S)·force 기본)
+  log.info("copy", "skip", `${filename} (사용자 결정: 기존 유지)`);
 }
 
 // 대화형 사전 조사 — 사람이 답해야 하는 것만 뽑는다 (issue #69).

package/src/core/logger.js

@@ -0,0 +1,141 @@
+// 실행 추적 로그 — "무엇을 어떤 순서로 왜 그렇게 했는지"를 시간순으로 남긴다.
+//
+// 왜 즉시 append인가: 디버깅에서 가장 알고 싶은 순간은 크래시 직전이다. 끝나고 한 번에
+// 쓰는 구조는 예외가 나면 아무것도 남기지 못한다(구 install-log.js가 그랬다).
+//
+// 왜 로컬 전용인가: 상세도를 제약하지 않기 위해서다. 로그 디렉토리에 .gitignore를 직접
+// 두어 그 폴더만 추적에서 뺀다 — 루트 .gitignore는 건드리지 않는다(이슈 #7 원칙).
+import { appendFileSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const LOG_DIR = ".github/.wizard/logs";
+const KEEP = 20;              // 유지할 로그 파일 수
+const GITIGNORE_BODY = "*\n!.gitignore\n";
+
+// 값에 비밀이 들어갈 수 있는 키 — 현재 질문 항목에는 없지만(도메인·경로·포트·인증 '방식'),
+// 앞으로 추가될 때 그냥 평문으로 남지 않도록 처음부터 걸어둔다.
+const SECRET_KEY_RE = /(PASSWORD|SECRET|TOKEN|KEY|CREDENTIAL)/i;
+const MASK = "***";
+
+let state = null; // { file, clock, startedAt, disabled }
+
+export function maskValue(key, value) {
+  // SSH_AUTH_METHOD처럼 "방식"만 담는 키는 비밀이 아니다 — 이름에 KEY가 들어가도 마스킹하지 않는다.
+  if (key === "SSH_AUTH_METHOD") return value;
+  return SECRET_KEY_RE.test(key) ? MASK : value;
+}
+
+// "2026-08-26 12:03:41" → "20260826-120341". 파일명이 곧 정렬 키가 되도록.
+export function stampFrom(now = "") {
+  const m = String(now).match(/(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})/);
+  if (!m) return "unknown";
+  return `${m[1]}${m[2]}${m[3]}-${m[4]}${m[5]}${m[6]}`;
+}
+
+export function logFilename(now, action = "install") {
+  return `${stampFrom(now)}-${action}.log`;
+}
+
+// 최근 KEEP개만 남기고 오래된 것부터 지운다. 파일명이 시각 오름차순이라 이름 정렬로 충분하다.
+// 새 파일이 곧 하나 추가되므로 KEEP-1개까지 줄인다.
+function rotate(dir) {
+  const logs = readdirSync(dir).filter((f) => f.endsWith(".log")).sort();
+  for (const f of logs.slice(0, Math.max(0, logs.length - (KEEP - 1)))) {
+    rmSync(join(dir, f), { force: true });
+  }
+}
+
+export function initLogger(targetRoot, opts = {}) {
+  const { action = "install", now = "", argv = [], templateVersion = "unknown", clock = () => new Date() } = opts;
+  try {
+    const dir = join(targetRoot, LOG_DIR);
+    mkdirSync(dir, { recursive: true });
+    // 사용자가 직접 둔 .gitignore가 있으면 존중한다.
+    const gi = join(dir, ".gitignore");
+    if (!existsSync(gi)) writeFileSync(gi, GITIGNORE_BODY);
+    rotate(dir);
+
+    const rel = `${LOG_DIR}/${logFilename(now, action)}`;
+    const file = join(targetRoot, rel);
+    const header =
+      `=== project-auto-wizard v${templateVersion} | ${action} | ${now} ===\n` +
+      `argv    : ${["project-auto-wizard", ...argv].join(" ")}\n` +
+      `node    : ${process.version} | ${process.platform} ${process.arch}\n` +
+      `target  : ${targetRoot}\n\n`;
+    writeFileSync(file, header);
+    state = { file, rel, clock, startedAt: Date.now(), disabled: false };
+    return { path: rel };
+  } catch (e) {
+    // 로그를 못 남긴 것이 설치를 되돌릴 이유는 아니다 — 다만 조용히 삼키지는 않는다.
+    process.stderr.write(`[warn] 실행 로그를 시작하지 못했습니다: ${e.message}\n`);
+    state = null;
+    return null;
+  }
+}
+
+export function resetLogger() {
+  state = null;
+}
+
+// 이번 실행의 로그 경로(레포 상대). 설치 요약 화면이 사용자에게 안내할 때 쓴다.
+export function currentLogPath() {
+  return state && !state.disabled ? state.rel : "";
+}
+
+// 구버전(.md) 설치 기록이 남아 있는지 — .gitignore는 이미 git이 추적 중인 파일에는
+// 영향이 없으므로, 있으면 사용자가 직접 추적을 끊도록 안내해야 한다.
+export function hasLegacyMdLogs(targetRoot) {
+  try {
+    const dir = join(targetRoot, LOG_DIR);
+    return existsSync(dir) && readdirSync(dir).some((f) => f.endsWith(".md"));
+  } catch { return false; }
+}
+
+// 열 너비 — 사람이 훑을 때 컬럼이 맞고, 에이전트가 컬럼 단위로 끊어 읽을 수 있게 고정한다.
+const SCOPE_W = 8;  // 가장 긴 scope('baseline')에 맞춘다 — 컬럼이 밀리면 훑기가 나빠진다
+const ACTION_W = 10;
+
+// 동아시아 전각 문자는 폭 2로 센다 (요약 블록 정렬용).
+const WIDE_RE = /[\u1100-\u115F\u2E80-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE6F\uFF00-\uFF60\uFFE0-\uFFE6]/;
+const dispWidth = (s) => [...String(s)].reduce((n, c) => n + (WIDE_RE.test(c) ? 2 : 1), 0);
+
+// 헤더의 실행 시각과 파일명이 UTC 기준(utcNow)이므로 라인 시각도 UTC로 맞춘다 —
+// 로컬 시간을 쓰면 같은 파일 안에서 헤더와 라인이 시간대만큼 어긋난다.
+function hhmmss(date) {
+  const p = (n, w = 2) => String(n).padStart(w, "0");
+  return `${p(date.getUTCHours())}:${p(date.getUTCMinutes())}:${p(date.getUTCSeconds())}.${p(date.getUTCMilliseconds(), 3)}`;
+}
+
+function write(level, scope, action, detail = "") {
+  if (!state || state.disabled) return;
+  try {
+    const line = `${hhmmss(state.clock())} ${level}  ${String(scope).padEnd(SCOPE_W)}  ${String(action).padEnd(ACTION_W)}  ${detail}`.trimEnd();
+    appendFileSync(state.file, line + "\n");
+  } catch (e) {
+    // 첫 실패에서 한 번만 알리고 이후는 조용히 끈다 — 매 줄 경고를 뱉으면 설치 화면이 무너진다.
+    state.disabled = true;
+    process.stderr.write(`[warn] 실행 로그 기록을 중단합니다: ${e.message}\n`);
+  }
+}
+
+export const log = {
+  info: (scope, action, detail) => write("INFO", scope, action, detail),
+  warn: (scope, action, detail) => write("WARN", scope, action, detail),
+  fail: (scope, action, detail) => write("FAIL", scope, action, detail),
+  // rows: Array<[label, value]> — 라벨 폭을 맞춰 정렬한다.
+  summary(rows = []) {
+    if (!state || state.disabled || !rows.length) return;
+    // 한글은 터미널에서 2칸을 차지한다 — 문자 수로 맞추면 눈으로 볼 때 어긋난다.
+    const w = Math.max(...rows.map(([k]) => dispWidth(k)));
+    const body = rows.map(([k, v]) => `${k}${" ".repeat(w - dispWidth(k))} : ${v}`).join("\n");
+    try {
+      appendFileSync(state.file, `\n=== 요약 ===\n${body}\n`);
+    } catch {
+      state.disabled = true;
+    }
+  },
+};
+
+export function closeLogger() {
+  state = null;
+}

package/src/index.js

@@ -21,6 +21,7 @@ import { runFull } from "./commands/full.js";
 import { runUninstall, runUninstallFlow } from "./commands/uninstall.js";
 import * as prompts from "./ui/prompts.js";
 import { runInteractive } from "./commands/interactive.js";
+import { initLogger, closeLogger, currentLogPath, hasLegacyMdLogs } from "./core/logger.js";
 import { runStatus, printStatus } from "./commands/status.js";
 import { runDoctor, printDoctorReport } from "./commands/doctor.js";
 import { planDryRun, printDryRun } from "./commands/dry-run.js";
@@ -59,7 +60,7 @@ async function defaultPromptRepoName(repoName) {
 //   payloadRoot: 테스트 픽스처 주입점 (기본: 패키지 동봉 payload/)
 //   clock: {now, today} 주입 (기본 현재 UTC).
 //   exec/promptRepoName: purge 모드 안전장치 게이트용 주입점 (기본 실제 구현, 테스트는 mock 주입).
-export async function run(argv, {
+async function runInner(argv, {
   cwd = process.cwd(), payloadRoot, clock,
   exec = defaultExec, promptRepoName = defaultPromptRepoName,
 } = {}) {
@@ -75,6 +76,19 @@ export async function run(argv, {
 
   const payload = assertPayload(payloadRoot ?? resolvePayloadRoot());
 
+  // 시각은 여기서 한 번만 계산한다 — 로그 파일명과 설치 기록이 같은 값을 쓰도록.
+  const { now, today } = clock || utcNow();
+
+  // dry-run은 "파일을 바꾸지 않는다"가 계약이므로 로그도 남기지 않는다.
+  // --version/--help는 이 지점 이전에 이미 반환되므로 자연히 제외된다.
+  const loggedAction = opts.dryRun ? null
+    : opts.mode === "uninstall" ? "uninstall"
+    : opts.mode === "purge" ? "purge"
+    : "install";
+  if (loggedAction) {
+    initLogger(cwd, { action: loggedAction, now, argv, templateVersion: readTemplateVersion() });
+  }
+
   // 대화형 모드 — 인자 없이 실행 or --mode interactive
   if (opts.mode === "interactive") {
     // --dry-run은 대화형 모드에서 조용히 무시되면 안 됨(실제 설치가 진행돼버림) — 명시 에러로 차단.
@@ -254,8 +268,6 @@ export async function run(argv, {
     }
   }
 
-  const { now, today } = clock || utcNow();
-
   const context = createContext({
     mode: opts.mode, force: opts.force, types, version, versionCode, branch,
     branches,
@@ -304,8 +316,19 @@ export async function run(argv, {
     gitignoreUpdated: result?.gitignoreUpdated === true,
     unresolved: result?.unresolved ?? [],
     secrets: result?.secrets ?? new Map(),
-    installLogPath: result?.installLog?.path ?? "",
+    logPath: currentLogPath(),
+    legacyMdLogs: hasLegacyMdLogs(cwd),
     cleanup: result?.cleanup ?? null,
   });
   return 0;
 }
+
+// 공개 진입점 — 어떤 경로로 끝나든(정상 반환·CliError·예외) 로거를 닫는다.
+// 본문을 통째로 try로 감싸면 들여쓰기가 전부 바뀌므로 얇은 래퍼로 분리했다.
+export async function run(argv, opts = {}) {
+  try {
+    return await runInner(argv, opts);
+  } finally {
+    closeLogger();
+  }
+}

package/src/ui/summary.js

@@ -8,7 +8,7 @@ const SEPARATOR = "────────────────────
 export function printSummary(ctx) {
   const { mode, types = [], version = "", versionCode = null, copiedFiles = [], branches = null, gitignoreUpdated = false,
     // 설치 후 검증·기록 (#79, #80, #81)
-    answers = [], unresolved = [], secrets = new Map(), installLogPath = "", cleanup = null } = ctx || {};
+    answers = [], unresolved = [], secrets = new Map(), logPath = "", legacyMdLogs = false, cleanup = null } = ctx || {};
   const err = (s = "") => process.stderr.write(`${s}\n`);
   // 색상은 ansi.js의 공용 가드로 통일 (NO_COLOR + stderr TTY 여부)
   const enabled = colorEnabled(process.stderr);
@@ -111,9 +111,14 @@ export function printSummary(ctx) {
     for (const f of cleanup.backedUp || []) err(`     • ${f} → ${f}.bak ${paint("수정하신 내용이 있어 백업", A.dim, enabled)}`);
     err("");
   }
-  if (installLogPath) {
-    err(`  📋 설치 기록: ${installLogPath}`);
-    err("     → 나중에 '무엇을 어떤 값으로 설치했는지' 확인할 때 이 파일을 보세요");
+  if (logPath) {
+    err(`  📋 실행 로그: ${logPath}`);
+    err("     → 무엇을 어떤 값으로 설치했는지 시간순으로 남아 있습니다 (git에 올라가지 않습니다)");
+    err("");
+  }
+  if (legacyMdLogs) {
+    err("  ℹ️  이전 버전의 설치 기록(.md)이 git에 추적 중입니다:");
+    err("     git rm -r --cached .github/.wizard/logs");
     err("");
   }
 

package/src/core/install-log.js

@@ -1,182 +0,0 @@
-// 설치 로그 (이슈 #79) — 실행마다 "무엇을 어떤 값으로 설치했는지"를 레포에 한 건 남긴다.
-//
-// 왜 필요한가: version.yml에는 버전·타입·경로·브랜치·옵션만 남는다. 감지 근거, 질문별 답변,
-// 특히 환경설정 답변(도메인·포트·볼륨 경로)은 워크플로우 YAML 안으로 흩어질 뿐 한 곳에
-// 기록되지 않아, 배포가 실패했을 때 "설치할 때 뭘로 답했더라"를 역추적할 방법이 없었다.
-// 터미널 스크롤백은 에이전트가 볼 수 없고 다른 클론에도 남지 않는다.
-//
-// 위치는 .github/.wizard/ 아래 — 마법사가 이미 baseline.json을 두는 자기 메타데이터 폴더다.
-// 새 최상위 폴더를 만들 이유가 없고, 삭제 모드에서도 경계가 이 폴더 하나로 끝난다.
-import { join } from "node:path";
-import { writeText } from "./fsutil.js";
-
-export const LOG_DIR = ".github/.wizard/logs";
-
-// 값에 비밀이 들어갈 수 있는 키 — 현재 질문 항목에는 없지만(도메인·경로·포트·인증 '방식'),
-// 앞으로 추가될 때 그냥 평문으로 커밋되지 않도록 처음부터 걸어둔다. 이 파일은 커밋 대상이다.
-const SECRET_KEY_RE = /(PASSWORD|SECRET|TOKEN|KEY|CREDENTIAL)/i;
-const MASK = "***";
-
-export function maskValue(key, value) {
-  // SSH_AUTH_METHOD처럼 "방식"만 담는 키는 비밀이 아니다 — 이름에 KEY가 들어가도 마스킹하지 않는다.
-  if (key === "SSH_AUTH_METHOD") return value;
-  return SECRET_KEY_RE.test(key) ? MASK : value;
-}
-
-// "2026-08-12 18:15:30" → "20260812-181530". 파일명이 곧 정렬 키가 되도록.
-export function stampFrom(now = "") {
-  const m = String(now).match(/(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})/);
-  if (!m) return "unknown";
-  return `${m[1]}${m[2]}${m[3]}-${m[4]}${m[5]}${m[6]}`;
-}
-
-export function logFilename(now, action = "install") {
-  return `${stampFrom(now)}-${action}.md`;
-}
-
-const yamlStr = (v) => `"${String(v ?? "").replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-const yamlList = (arr) => `[${(arr || []).map(yamlStr).join(", ")}]`;
-
-// 마크다운 렌더 — 상단은 기계가 읽는 front matter, 아래는 사람이 읽는 본문.
-// 에이전트가 파싱만 해도 핵심을 얻고, 사람이 열면 그대로 읽힌다.
-export function renderInstallLog(d = {}) {
-  const {
-    action = "install", at = "", templateVersion = "",
-    previousTemplateVersion = "", mode = "", types = [], markers = new Map(),
-    version = "", branch = "", branches = null, paths = new Map(),
-    options = {}, answers = [], result = {}, unresolved = [], secrets = new Map(),
-    warnings = [], cleanup = null,
-  } = d;
-
-  const L = [];
-  L.push("---");
-  L.push(`action: ${yamlStr(action)}`);
-  L.push(`at: ${yamlStr(at)}`);
-  L.push(`template_version: ${yamlStr(templateVersion)}`);
-  if (previousTemplateVersion) L.push(`previous_template_version: ${yamlStr(previousTemplateVersion)}`);
-  L.push(`mode: ${yamlStr(mode)}`);
-  L.push(`project_types: ${yamlList(types)}`);
-  L.push(`version: ${yamlStr(version)}`);
-  L.push(`default_branch: ${yamlStr(branch)}`);
-  if (branches) {
-    L.push(`branches: { main: ${yamlStr(branches.main)}, develop: ${yamlStr(branches.develop)}, mode: ${yamlStr(branches.mode)} }`);
-  }
-  L.push(`unresolved_count: ${unresolved.length}`);
-  L.push(`required_secrets: ${yamlList([...secrets.keys()])}`);
-  L.push("---");
-  L.push("");
-  L.push(`# 설치 로그 — ${at}`);
-  L.push("");
-  L.push("project-auto-wizard가 이 레포에 무엇을 설치했는지 남긴 기록입니다. 직접 편집하지 마세요.");
-  L.push("");
-
-  L.push("## 실행");
-  L.push("");
-  L.push("| 항목 | 값 |");
-  L.push("|---|---|");
-  L.push(`| 동작 | ${action === "install" ? "신규 설치" : action === "update" ? "업데이트" : action} |`);
-  L.push(`| 템플릿 버전 | ${previousTemplateVersion ? `${previousTemplateVersion} → ${templateVersion}` : templateVersion || "-"} |`);
-  L.push(`| 설치 모드 | ${mode || "-"} |`);
-  L.push("");
-
-  L.push("## 감지 결과");
-  L.push("");
-  L.push("| 항목 | 값 | 근거 |");
-  L.push("|---|---|---|");
-  for (const t of types) {
-    L.push(`| 타입 | ${t} | ${markers?.get?.(t) || "직접 선택"} |`);
-  }
-  L.push(`| 버전 | ${version} | ${d.versionSource || "자동 감지"} |`);
-  L.push(`| 브랜치 | ${branch} | git |`);
-  for (const [t, p] of paths) L.push(`| 경로 (${t}) | ${p} | |`);
-  L.push("");
-  if (warnings.length) {
-    L.push("감지 중 경고:");
-    L.push("");
-    for (const w of warnings) L.push(`- ${w}`);
-    L.push("");
-  }
-
-  L.push("## 선택 항목");
-  L.push("");
-  L.push("| 항목 | 값 |");
-  L.push("|---|---|");
-  L.push(`| 라이브러리 publish (Nexus·GitHub Packages) | ${options.nexus ? "포함" : "제외"} |`);
-  L.push(`| Secret 서버 백업 | ${options.secretBackup ? "포함" : "제외"} |`);
-  L.push(`| 자동 버전 승격 | ${options.semverAuto === false ? "사용 안 함" : "사용"} |`);
-  L.push(`| 서버 배포 방식 | ${options.deployStyle || "-"} |`);
-  L.push("");
-
-  L.push("## 환경설정 답변");
-  L.push("");
-  if (!answers.length) {
-    L.push("이 설치에서는 환경설정 질문이 없었습니다.");
-  } else {
-    L.push("`기본값` 열이 `예`면 질문에서 그대로 Enter를 누른 값입니다. 배포가 예상과 다르게 동작하면 여기부터 확인하세요.");
-    L.push("");
-    L.push("| 키 | 항목 | 값 | 기본값 | 사용처 |");
-    L.push("|---|---|---|---|---|");
-    for (const a of answers) {
-      L.push(`| \`${a.key}\` | ${a.label} | \`${maskValue(a.key, a.value)}\` | ${a.isDefault ? "예" : "아니오"} | ${a.scope || ""} |`);
-    }
-  }
-  L.push("");
-
-  L.push("## 설치 결과");
-  L.push("");
-  const sec = (title, items, fmt = (x) => `- \`${x}\``) => {
-    if (!items || !items.length) return;
-    L.push(`### ${title} (${items.length})`);
-    L.push("");
-    for (const it of items) L.push(fmt(it));
-    L.push("");
-  };
-  sec("새로 설치된 파일", result.copiedFiles);
-  sec("이전 배포 방식 정리 — 삭제", cleanup?.removed);
-  sec("이전 배포 방식 정리 — .bak 백업 (수정 내용 보존)", cleanup?.backedUp);
-  sec("건너뛴 파일", result.skippedFiles);
-  sec("백업 후 교체한 파일", result.backupFiles);
-  if (result.gitignoreUpdated) { L.push("`.gitignore`를 갱신했습니다 (충돌 백업 파일 무시 항목 추가)."); L.push(""); }
-
-  L.push("## 남은 할 일");
-  L.push("");
-  if (unresolved.length) {
-    L.push("### ⚠️ 값이 채워지지 않은 항목");
-    L.push("");
-    L.push("마법사가 값을 계산하지 못해 플레이스홀더가 그대로 남았습니다. **이 상태로는 해당 워크플로우가 정상 동작하지 않습니다.** 직접 채워 주세요.");
-    L.push("");
-    L.push("| 파일 | 줄 | 토큰 |");
-    L.push("|---|---|---|");
-    for (const u of unresolved) L.push(`| \`${u.filename}\` | ${u.line} | \`${u.token}\` |`);
-    L.push("");
-  }
-  if (secrets.size) {
-    L.push("### 등록해야 하는 GitHub Secret");
-    L.push("");
-    L.push("Settings > Secrets and variables > Actions 에서 등록합니다. 등록 전에는 해당 워크플로우가 실패합니다.");
-    L.push("");
-    L.push("| Secret | 사용하는 워크플로우 |");
-    L.push("|---|---|");
-    for (const [name, users] of secrets) L.push(`| \`${name}\` | ${users.map((u) => `\`${u}\``).join(", ")} |`);
-    L.push("");
-  }
-  if (!unresolved.length && !secrets.size) {
-    L.push("추가로 조치할 항목이 없습니다.");
-    L.push("");
-  }
-
-  return L.join("\n") + "\n";
-}
-
-// 로그 기록. 실패해도 설치 자체는 성공으로 끝나야 하므로 예외를 삼키고 null을 돌려준다 —
-// 로그를 못 남긴 것이 설치를 되돌릴 이유는 아니다.
-export function writeInstallLog(targetRoot, data = {}) {
-  try {
-    const filename = logFilename(data.at, data.action || "install");
-    const rel = `${LOG_DIR}/${filename}`;
-    writeText(join(targetRoot, rel), renderInstallLog(data));
-    return { path: rel };
-  } catch {
-    return null;
-  }
-}