projectops 4.27.0 → 4.28.1

package/README.md

@@ -7,7 +7,7 @@
 > 이슈 등록부터 커밋, 보고서, 배포까지. 개발자는 코드만 작성하세요.
 
 <!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->
-## 최신 버전 : v4.26.0 (2026-09-30)
+## 최신 버전 : v4.28.0 (2026-09-30)
 
 [전체 버전 기록 보기](CHANGELOG.md)
 
@@ -168,6 +168,7 @@ npx projectops --mode skills
 | `/pro-build` | 프로젝트 빌드 실행, 에러 분석, 최적화 제안 |
 | `/pro-launch` | 앱·웹·서버를 띄우고 조작하고 찍는다 — 상태바 고정 캡처, 폭 바꾸기, 응답 바꿔치기(빈 목록·실패 연출), 코드 렌더 |
 | `/pro-design-brief` | 시안보다 먼저 만든 화면의 디자인 요청서 — 상태별 캡처·대안·문구 후보·꼭 지킬 것을 보드로 만들어 디자이너에게 |
+| `/pro-oss-consult` | GitHub 레포를 오픈소스로서 진단 — 성격 판별, 6축 채점, 성숙도 단계, 승인받은 것만 About·topics·라벨·파일 수정. 단일 레포·계정 전체 일괄 |
 
 > 설계·계획·구현 흐름은 `superpowers`(brainstorming → writing-plans → executing-plans)가 담당합니다.
 > `/pro-plan` · `/pro-analyze` · `/pro-implement`는 같은 역할의 이전 세대 경로로, 명시적으로 호출할 때만 동작합니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectops",
-  "version": "4.27.0",
+  "version": "4.28.1",
   "description": "ProjectOps — 완전 자동화 GitHub 프로젝트 관리 템플릿 통합 CLI",
   "keywords": [
     "devops",

package/src/cli/args.js

@@ -1,9 +1,15 @@
 // CLI 인자 파싱 (.sh top-level while-case 등가) — template_integrator.sh 842~920.
+import { existsSync, statSync, realpathSync } from "node:fs";
+import { join, relative, isAbsolute } from "node:path";
 import { VALID_TYPES } from "../context.js";
 
 export const DEPLOY_TARGETS = ["docker-ssh", "vercel", "none"];
 export const PUBLISH_TARGETS = ["nexus", "npm", "github-packages"];
 export const INTENT_VALUES = ["app", "library", "both", "none", "manual"];
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+// 허용 실행 모드 (#665) — 오타가 조용히 "복사 0건 성공"으로 끝나지 않게 한다.
+export const MODE_VALUES = ["full", "version", "workflows", "issues", "skills", "doctor", "interactive"];
 
 // argv(process.argv.slice(2)) → 파싱 결과. 오류 시 throw(호출부에서 exit 1).
 export function parseArgs(argv) {
@@ -28,12 +34,28 @@ export function parseArgs(argv) {
     const a = args.shift();
     switch (a) {
       case "-m": case "--mode":
-        result.mode = args.shift() ?? ""; break;
+      {
+        const v = (args.shift() ?? "").trim();
+        if (!MODE_VALUES.includes(v)) {
+          throw new CliError(`--mode 값은 ${MODE_VALUES.join(" | ")} 중 하나여야 합니다: '${v}'`);
+        }
+        result.mode = v;
+        break;
+      }
       case "-v": case "--version":
         // npm 관례: -v/--version 은 패키지 버전 출력. (초기 버전 지정은 --project-version)
         result.showVersion = true; break;
       case "--project-version":
-        result.version = args.shift() ?? ""; break;
+      {
+        // version.yml·셸 스크립트가 그대로 읽는 값이라 x.y.z 외에는 받지 않는다 (#676)
+        // 'v1.0.0'은 사용자가 흔히 쓰는 표기라 거부하지 않고 접두사만 떼어 받는다
+        const v = (args.shift() ?? "").trim().replace(/^[vV](?=\d)/, "");
+        if (!SEMVER_RE.test(v)) {
+          throw new CliError(`--project-version 값은 x.y.z (예: 1.0.0) 형식이어야 합니다: '${v}'`);
+        }
+        result.version = v;
+        break;
+      }
       case "-t": case "--type": {
         const csv = args.shift() ?? "";
         const seen = new Set();
@@ -79,6 +101,10 @@ export function parseArgs(argv) {
       case "--deploy-branch": {
         // 릴리스 PR head 브랜치 (#456). default_branch와 별개.
         const v = (args.shift() ?? "").trim();
+        // 워크플로우 yaml·셸에 그대로 삽입되므로 안전한 브랜치명만 허용 (#676)
+        if (v && (!BRANCH_RE.test(v) || v.includes("..") || v.endsWith("/") || v.endsWith(".lock"))) {
+          throw new CliError(`--deploy-branch 값은 영문·숫자·. _ - / 로 이루어진 브랜치명이어야 합니다: '${v}'`);
+        }
         if (v) result.deployBranch = v;
         break;
       }
@@ -132,6 +158,29 @@ export function normalizePath(p) {
   return s === "" ? "." : s;
 }
 
+// --paths 맵 검증 (#674) — 저장소 밖 경로는 version_manager가 그 파일을 실제로 수정하므로 가장 위험하다.
+//   · 절대경로·`..` 세그먼트 거부 (저장소 루트 기준 상대경로만)
+//   · --type 으로 고르지 않은 타입 키 거부
+//   · 존재하지 않는 폴더 거부 (심볼릭 링크로 밖을 가리키는 경우도 realpath 로 막는다)
+export function validatePathsMap(map, { root, types }) {
+  for (const [type, p] of map) {
+    if (!types.includes(type)) {
+      throw new CliError(`--paths 에 선택하지 않은 타입이 있습니다: '${type}' (선택한 타입: ${types.join(",") || "없음"})`);
+    }
+    if (p.startsWith("/") || /^[A-Za-z]:/.test(p) || p.split("/").includes("..")) {
+      throw new CliError(`--paths ${type}=${p} : 저장소 루트 기준 상대 경로여야 합니다 (절대경로, '..' 불가)`);
+    }
+    const abs = join(root, p);
+    if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+      throw new CliError(`--paths ${type}=${p} : 존재하지 않는 폴더입니다`);
+    }
+    const rel = relative(realpathSync(root), realpathSync(abs));
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+      throw new CliError(`--paths ${type}=${p} : 저장소 밖을 가리킵니다`);
+    }
+  }
+}
+
 // "flutter=app,react=client" → Map<type, normalizedPath>. 타입 검증(무효 → throw).
 export function parsePathsCsv(csv) {
   const map = new Map();

package/src/cli/errors.js

@@ -0,0 +1,40 @@
+// 예기치 못한 예외를 사용자가 읽을 수 있는 한 줄 오류 + 조치 안내로 바꾼다 (#672).
+// 스택 트레이스는 사용자가 고칠 수 있는 정보가 아니므로 DEBUG 환경변수가 있을 때만 노출한다.
+
+// err → { message, hint }. 분류 근거는 Node 가 던지는 err.code / 메시지 형식이다.
+export function describeError(err) {
+  const msg = String(err?.message || err);
+  const code = err?.code;
+
+  // PATH 에 git 이 없음 — spawn 계열이 ENOENT 를 던진다
+  if (code === "ENOENT" && /\bgit\b/.test(`${err?.path ?? ""} ${err?.syscall ?? ""} ${msg}`)) {
+    return { message: "git 을 실행할 수 없습니다.", hint: "git 이 설치되어 있고 PATH 에 있는지 확인하세요." };
+  }
+  // 템플릿 내려받기 실패 — execFileSync 가 "Command failed: git clone ..." 를 던진다
+  if (/Command failed: git clone/.test(msg)) {
+    return {
+      message: "템플릿을 내려받지 못했습니다.",
+      hint: "네트워크·프록시 설정과 GitHub 접근 가능 여부를 확인한 뒤 다시 실행하세요.",
+    };
+  }
+  // 권한/읽기 전용 파일시스템
+  if (code === "EACCES" || code === "EPERM" || code === "EROFS") {
+    const where = err?.path ? ` (${err.path})` : "";
+    return {
+      message: `파일을 쓸 수 없습니다${where}.`,
+      hint: "프로젝트 폴더와 .github 폴더의 쓰기 권한(읽기 전용 여부)을 확인하세요.",
+    };
+  }
+  if (code === "ENOSPC") {
+    return { message: "디스크 공간이 부족합니다.", hint: "공간을 확보한 뒤 다시 실행하세요." };
+  }
+  return { message: `예기치 못한 오류: ${msg}`, hint: "자세한 내용은 DEBUG=1 로 다시 실행하면 볼 수 있습니다." };
+}
+
+// 오류를 stderr 로 출력한다. 호출부는 비0 종료코드를 돌려주면 된다.
+export function reportFatal(err, { env = process.env, write = (s) => process.stderr.write(s) } = {}) {
+  const { message, hint } = describeError(err);
+  write(`❌ ${message}\n`);
+  if (hint) write(`   ${hint}\n`);
+  if (env.DEBUG) write(`\n${err?.stack || err}\n`);
+}

package/src/commands/full.js

@@ -2,9 +2,10 @@
 // 복사 순서: version.yml → readme → workflows → (deploy블록) → scripts → config →
 //            util(타입별) → issue → discussion → coderabbit → gitignore → setup_guide → (옵션저장)
 import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 import { writeText } from "../core/fsutil.js";
 import { PATHS } from "../core/paths.js";
-import { buildVersionYml } from "../core/version-yml.js";
+import { buildVersionYml, mergeDeployValues } from "../core/version-yml.js";
 import { markerForType } from "../core/detect.js";
 import { addVersionSectionToReadme } from "../core/copy/readme.js";
 import { copyWorkflows } from "../core/copy/workflows.js";
@@ -36,7 +37,10 @@ export function runFull(context, tempDir, targetRoot = ".", hooks = {}) {
   const step = (name, fn, d) => (hooks.trace ? hooks.trace.step(name, fn, d) : fn());
   const wfCounters = step("copy-workflows", () => copyWorkflows(context, tempDir, targetRoot, hooks),
     { types, deploy: deployTarget, publish: publishTargets });
-  const deployValues = wfCounters.deployValues || new Map(); // Map<type, Map<key,value>>
+  // 기존 version.yml 의 deploy 값은 보존한다 (#670) — 전체 재생성이라 읽지 않으면 사용자 수정이 사라진다.
+  const vyFile = join(targetRoot, PATHS.versionFile);
+  const deployValues = mergeDeployValues(existsSync(vyFile) ? readFileSync(vyFile, "utf8") : "",
+    wfCounters.deployValues || new Map()); // Map<type, Map<key,value>
 
   // 1. version.yml 생성 (전체 재생성 — metadata → deploy → template 순, .sh 최종형과 동일)
   step("write-version-yml", () => writeText(join(targetRoot, PATHS.versionFile),

package/src/commands/interactive.js

@@ -408,6 +408,7 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
       mode, types, version, deployBranch, deployBranchReady, migrationGuidePath,
       counters: { workflows: result?.workflows?.copied ?? 0, workflowFiles: result?.workflows?.copiedFiles ?? [], utilModules: 0 },
       skippedConflicts: result?.workflows?.skippedConflicts ?? [],   // #654 병합 안내
+      replacedBak: result?.workflows?.replacedBak ?? [],             // #673 기준점 없이 교체한 파일 안내
       verification: result?.verification,      // #549 설치 검증 결과
       aiPrSummary, codeReviewCoderabbit,       // #569 — 고른 것만 안내
       logDir: files ? MIGRATION_DIR : null,    // #561 기록 위치 안내

package/src/commands/version.js

@@ -1,10 +1,11 @@
 // version 모드 (.sh execute_integration version case 등가) — template_integrator.sh 4517~4530.
 // 순서: version.yml → readme → scripts → config → gitignore → setup_guide.
 // (워크플로우 미복사 → deploy 블록 없음. util·issue·coderabbit도 없음.)
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { writeText } from "../core/fsutil.js";
 import { PATHS } from "../core/paths.js";
-import { buildVersionYml } from "../core/version-yml.js";
+import { buildVersionYml, mergeDeployValues } from "../core/version-yml.js";
 import { markerForType } from "../core/detect.js";
 import { addVersionSectionToReadme } from "../core/copy/readme.js";
 import { copyScripts, copyConfigFolder, copySetupGuide } from "../core/copy/simple.js";
@@ -19,9 +20,14 @@ export function runVersion(context, tempDir, targetRoot = ".") {
   const pathMarkers = new Map();
   for (const [t] of paths) pathMarkers.set(t, markerForType(t));
 
-  writeText(join(targetRoot, PATHS.versionFile),
+  // version.yml 은 전체 재생성이라, 읽지 않으면 이전 통합이 남긴 deploy 값(사용자 수정 포함)이 사라진다 (#670)
+  const vyFile = join(targetRoot, PATHS.versionFile);
+  const deployValues = mergeDeployValues(existsSync(vyFile) ? readFileSync(vyFile, "utf8") : "", new Map());
+
+  writeText(vyFile,
     buildVersionYml({
       version, types, paths, pathMarkers, branch, deployBranch, versionCode, now, today,
+      deployValues,
       // mode(#502): version 모드가 기존 full 통합 기록을 "version"으로 강등하지 않도록
       // 호출부가 recordMode로 기존 값을 넘긴다 (full이 우세 — 업데이트 재실행 범위 축소 방지).
       templateOptions: { templateVersion, deployTarget, publishTargets, includeSecretBackup, optionsDate: today,

package/src/commands/workflows.js

@@ -7,7 +7,7 @@ import { PATHS } from "../core/paths.js";
 import { copyWorkflows } from "../core/copy/workflows.js";
 import { copyScripts, copyConfigFolder, copySetupGuide } from "../core/copy/simple.js";
 import { copyUtilModules } from "../core/copy/util.js";
-import { convertLegacySingularType } from "../core/version-yml.js";
+import { convertLegacySingularType, mergeDeployValues } from "../core/version-yml.js";
 import { verifyInstall } from "../core/verify.js";
 
 export function runWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
@@ -25,7 +25,8 @@ export function runWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
 
   // update_version_yml_deploy: 기존 version.yml이 있고 ask 값이 있을 때만 deploy 블록 갱신
   if (existsSync(vy) && wf.deployValues && wf.deployValues.size) {
-    writeFileSync(vy, upsertDeployBlock(readFileSync(vy, "utf8"), wf.deployValues));
+    const cur = readFileSync(vy, "utf8");
+    writeFileSync(vy, upsertDeployBlock(cur, mergeDeployValues(cur, wf.deployValues)));   // 기존 값 우선 (#670)
   }
 
   copyScripts(tempDir, targetRoot);
@@ -62,8 +63,10 @@ export function upsertDeployBlock(content, deployValues) {
   for (const line of lines) {
     if (/^deploy:/.test(line)) { inDeploy = true; continue; }
     if (inDeploy) {
-      if (/^\s/.test(line) || line === "") continue; // 들여쓰기/빈줄 = deploy 내부
-      inDeploy = false;
+      // 4.28.0 이 만든 깨진 구조: deploy 아래 2칸 `template:` 은 deploy 내용이 아니라 metadata 의 자식이다 (#670)
+      if (/^ {2}template:/.test(line)) inDeploy = false;
+      else if (/^\s/.test(line) || line === "") continue; // 들여쓰기/빈줄 = deploy 내부
+      else inDeploy = false;
     }
     out.push(line);
   }

package/src/core/copy/workflows.js

@@ -81,6 +81,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   if (!exists(projectTypesDir)) throw new Error("템플릿 저장소 구조 오류 — project-types 폴더를 찾지 못했습니다.");
 
   const counters = { copied: 0, skipped: 0, templateAdded: 0, optionalCopied: 0, copiedFiles: [],
+    replacedBak: [], // #673 — 기준점이 없어 수정 여부를 모른 채 .bak 백업 후 교체한 파일명
     skippedConflicts: [] }; // #654 — 유지한 사용자 수정본별 { filename, incoming, added, removed }
   const deployValues = new Map(); // Map<type, Map<key,value>> — deploy 블록용 ask 값
   counters.deployValues = deployValues;
@@ -152,6 +153,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
         counters.copied++;
         counters.copiedFiles.push(filename);
         trace?.event("copy", "replaced-bak", filename, { group: "common", reason: "baseline-absent" });
+        counters.replacedBak.push(filename);   // #673 — 수정 가능성이 있는 파일을 교체했음을 화면에 알린다
         continue;
       }
       // 사용자가 손댄 것이 확인된 파일 — 결정에 따라 처리(미지정이면 유지).
@@ -184,6 +186,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
       counters.copied++;
       counters.copiedFiles.push(filename);
       trace?.event("copy", backedUp ? "replaced-bak" : "copied", filename, { group: "common-deploy" });
+      if (backedUp) counters.replacedBak.push(filename);   // #673
     }
   }
 
@@ -207,6 +210,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
       counters.copied++;
       counters.copiedFiles.push(filename);
       trace?.event("copy", backedUp ? "replaced-bak" : "copied", filename, { group: "pr-summary" });
+      if (backedUp) counters.replacedBak.push(filename);   // #673
     }
   }
 
@@ -407,6 +411,7 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
       counters.copied++;
       counters.copiedFiles.push(filename);
       trace?.event("copy", backedUp ? "replaced-bak" : "copied", filename, { group: `${type}/publish/${target}` });
+      if (backedUp) counters.replacedBak.push(filename);   // #673
     }
   }
 

package/src/core/detect-fs.js

@@ -21,6 +21,8 @@ function gitOut(root, args) {
 const SCAN_PRUNE = new Set([
   "node_modules", ".git", "build", "dist", ".dart_tool",
   "android", "ios", ".gradle", "venv", ".venv", "__pycache__",
+  // 템플릿이 스스로 설치하는 .github/scripts/*.py 가 python 으로 오탐되지 않게 한다 (#671)
+  ".github",
 ]);
 export function listScanFiles(root, maxDepth = 3) {
   const files = [];

package/src/core/version-yml.js

@@ -267,6 +267,37 @@ export function parseExisting(content) {
   return { version, versionCode, types, paths, templateVersion, templateMode, options, defaultBranch, deployBranch };
 }
 
+// 기존 version.yml 의 deploy 블록 → Map<type, Map<key,value>> (#670 — 재실행 시 사용자 수정값 보존용).
+// 4.28.0 이 만든 깨진 구조(deploy 아래에 2칸 들여쓴 template 이 딸려 있음)도 읽을 수 있게,
+// 2칸 키 `template` 은 타입이 아니라 블록 종료로 본다.
+export function parseDeployBlock(content) {
+  const out = new Map();
+  let inDeploy = false;
+  let type = null;
+  for (const line of String(content || "").split(/\r?\n/)) {
+    if (/^deploy:/.test(line)) { inDeploy = true; type = null; continue; }
+    if (!inDeploy) continue;
+    if (line === "" || /^\s*#/.test(line)) continue;
+    if (/^\S/.test(line) || /^ {2}template:/.test(line)) { inDeploy = false; continue; }
+    const t = line.match(/^ {2}([A-Za-z0-9_-]+):\s*(#.*)?$/);
+    if (t) { type = t[1]; if (!out.has(type)) out.set(type, new Map()); continue; }
+    const kv = line.match(/^ {4}([A-Za-z0-9_.-]+):\s*"([^"]*)"/);
+    if (kv && type) out.get(type).set(kv[1], kv[2]);
+  }
+  return out;
+}
+
+// 재실행 시 기존 deploy 값 우선 병합 (#670) — 사용자가 version.yml 에서 직접 고친 값이 템플릿 기본값에
+// 덮이지 않게 한다. 기존 값이 이기고, 이번에 새로 묻는 키만 추가된다.
+export function mergeDeployValues(existingContent, fresh) {
+  const merged = parseDeployBlock(existingContent);
+  for (const [t, kv] of fresh) {
+    if (!merged.has(t)) merged.set(t, new Map());
+    for (const [k, v] of kv) if (!merged.get(t).has(k)) merged.get(t).set(k, v);
+  }
+  return merged;
+}
+
 // version.yml 전체 생성 (.sh create_version_yml + save_template_options 신규 케이스 등가).
 // opts: { version, types:[], paths:Map, pathMarkers?:Map, branch, versionCode, now, today, templateOptions? }
 // primary 타입은 별도 키 없이 project_types[0]이다 (v4.1.0 SSOT — 단수 project_type 키 제거).
@@ -302,18 +333,6 @@ export function buildVersionYml({ version, types = [], paths = new Map(), pathMa
   out += `  integrated_from: "projectops"\n`;
   out += `  integration_date: "${today}"\n`;
 
-  // deploy 블록 (.sh update_version_yml_deploy). deployValues: Map<type, Map<key,value>>.
-  // WF ask 값이 있는 타입만. metadata 뒤, template 앞. (앞에 빈 줄 1개)
-  const deployTypes = [...deployValues.keys()].filter((t) => deployValues.get(t) && deployValues.get(t).size > 0);
-  if (deployTypes.length) {
-    out += `\n`;
-    out += `deploy:                          # 마법사가 기억하는 배포 설정 (비민감 / 직접 수정 가능)\n`;
-    for (const t of deployTypes) {
-      out += `  ${t}:\n`;
-      for (const [k, v] of deployValues.get(t)) out += `    ${k}: "${v}"\n`;
-    }
-  }
-
   // template 옵션 블록 (.sh save_template_options 신규 추가 케이스). templateOptions 지정 시.
   if (templateOptions) {
     const { templateVersion = "unknown", deployTarget = "docker-ssh", publishTargets = [], includeSecretBackup = false, optionsDate = today,
@@ -347,5 +366,18 @@ export function buildVersionYml({ version, types = [], paths = new Map(), pathMa
     out += `        provider: "${changelogProvider}"\n`;
     out += `        base_url: "${changelogBaseUrl}"\n`;
   }
+
+  // deploy 블록 (.sh update_version_yml_deploy). deployValues: Map<type, Map<key,value>>.
+  // WF ask 값이 있는 타입만. 반드시 template 뒤의 별도 최상위 키로 둔다 — metadata 와 template
+  // 사이에 끼면 template 이 deploy 의 자식이 되어 metadata.template.options 구조가 깨진다 (#670).
+  const deployTypes = [...deployValues.keys()].filter((t) => deployValues.get(t) && deployValues.get(t).size > 0);
+  if (deployTypes.length) {
+    out += `\n`;
+    out += `deploy:                          # 마법사가 기억하는 배포 설정 (비민감 / 직접 수정 가능)\n`;
+    for (const t of deployTypes) {
+      out += `  ${t}:\n`;
+      for (const [k, v] of deployValues.get(t)) out += `    ${k}: "${v}"\n`;
+    }
+  }
   return out;
 }

package/src/index.js

@@ -3,8 +3,9 @@
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync, existsSync } from "node:fs";
-import { parseArgs, parsePathsCsv, CliError } from "./cli/args.js";
+import { parseArgs, parsePathsCsv, validatePathsMap, CliError } from "./cli/args.js";
 import { HELP_TEXT } from "./cli/help.js";
+import { reportFatal } from "./cli/errors.js";
 import { createContext } from "./context.js";
 import { PATHS } from "./core/paths.js";
 import { remove } from "./core/fsutil.js";
@@ -49,7 +50,18 @@ function utcNow(date = new Date()) {
 // run(argv, opts) → exitCode. opts: { cwd, source?, clock? }
 //   source: acquireTemplate용 (기본 git clone). 테스트는 {type:'local', path} 주입.
 //   clock: {now, today} 주입 (기본 현재 UTC).
-export async function run(argv, { cwd = process.cwd(), source = { type: "git" }, clock } = {}) {
+export async function run(argv, options = {}) {
+  try {
+    return await runCore(argv, options);
+  } catch (err) {
+    // 네트워크·git·권한 같은 환경 문제는 스택 트레이스 대신 한 줄 원인 + 조치로 알린다 (#672).
+    // 실행 기록(trace)은 runCore 의 finally 에서 이미 닫혔다.
+    reportFatal(err);
+    return 1;
+  }
+}
+
+async function runCore(argv, { cwd = process.cwd(), source = { type: "git" }, clock } = {}) {
   let opts;
   try {
     opts = parseArgs(argv);
@@ -130,8 +142,21 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
   const repoName = detectRepoName(cwd);
   trace.event("detect", "repo", repoName || "(미상)", { defaultBranch: branch, versionCode });
   // 경로 확정 (.sh resolve_project_paths 비대화형 경로 — --paths 우선 → 저장값 → 후보 1개 자동 → 루트 폴백)
+  let cliPaths;
+  try {
+    cliPaths = parsePathsCsv(opts.pathsCsv);
+    validatePathsMap(cliPaths, { root: cwd, types });   // #674 — 파일을 쓰기 전에 거른다
+  } catch (e) {
+    if (e instanceof CliError) {
+      console.error(e.message);
+      trace.mirrorStop();
+      disarmSignals();
+      return 1;
+    }
+    throw e;
+  }
   const paths = await resolveProjectPaths({
-    root: cwd, types, paths: parsePathsCsv(opts.pathsCsv),
+    root: cwd, types, paths: cliPaths,
     existingPaths: existing?.paths ?? new Map(), force: true, tty: false, io: {},
   });
 
@@ -322,6 +347,7 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
       mode: opts.mode, types, version, deployBranch: context.deployBranch, migrationGuidePath,
       counters: { workflows: result?.workflows?.copied ?? 0, workflowFiles: result?.workflows?.copiedFiles ?? [], utilModules: 0 },
       skippedConflicts: result?.workflows?.skippedConflicts ?? [],   // #654 병합 안내
+      replacedBak: result?.workflows?.replacedBak ?? [],             // #673 기준점 없이 교체한 파일 안내
       verification: result?.verification,   // #549 설치 후 검증 결과 (full/workflows 모드에서만 존재)
       // #569 — 고른 것만 안내하려면 선택값이 필요하다
       aiPrSummary: context.aiPrSummary, codeReviewCoderabbit: context.codeReviewCoderabbit,

package/src/ui/summary.js

@@ -18,6 +18,8 @@ export function printSummary(ctx, targetRoot = ".") {
   const CYAN = isTty ? "\x1b[0;36m" : "";
   const NC = isTty ? "\x1b[0m" : "";
   const utilModulesCopied = counters.utilModules ?? 0;
+  // README.md 가 없으면 버전 섹션 추가를 건너뛰므로 화면에도 추가·자동 갱신으로 표시하지 않는다 (#677)
+  const hasReadme = existsSync(join(targetRoot, "README.md"));
 
   err("");
   err(SEPARATOR);
@@ -32,7 +34,7 @@ export function printSummary(ctx, targetRoot = ".") {
   switch (mode) {
     case "full":
       err("  ✅ 버전 관리 시스템 (version.yml)");
-      err("  ✅ README.md 자동 버전 업데이트");
+      if (hasReadme) err("  ✅ README.md 자동 버전 업데이트");
       err("  ✅ GitHub Actions 워크플로우");
       if (utilModulesCopied > 0) err(`  ✅ 유틸리티 모듈 (${utilModulesCopied} 개)`);
       err("  ✅ 이슈/PR/Discussion 템플릿");
@@ -42,7 +44,7 @@ export function printSummary(ctx, targetRoot = ".") {
       break;
     case "version":
       err("  ✅ 버전 관리 시스템 (version.yml)");
-      err("  ✅ README.md 자동 버전 업데이트");
+      if (hasReadme) err("  ✅ README.md 자동 버전 업데이트");
       err("  ✅ .gitignore 필수 항목");
       err("  ✅ 템플릿 설정 가이드 (SETUP-GUIDE.md)");
       break;
@@ -72,7 +74,7 @@ export function printSummary(ctx, targetRoot = ".") {
   err("");
   err("추가된 파일:");
   err(`  📄 version.yml (버전: ${version}, 타입: ${types.join(",")})`);
-  err("  📝 README.md (버전 섹션 추가)");
+  err(hasReadme ? "  📝 README.md (버전 섹션 추가)" : "  📝 README.md 없음 — 버전 섹션 추가를 건너뜀");
   err("");
   err("추가된 워크플로우:");
 
@@ -110,6 +112,16 @@ export function printSummary(ctx, targetRoot = ".") {
     }
   }
 
+  // #673 — 업데이트 기준점이 없어 수정 여부를 구분하지 못하고 교체한 파일: 원본이 .bak 으로만 남으므로
+  // 사용자가 자기 수정이 사라졌는지 git diff 없이도 알 수 있어야 한다.
+  const replaced = ctx?.replacedBak ?? [];
+  if (replaced.length > 0) {
+    err("");
+    err(`  ${YELLOW}⚠️  수정 여부를 확인할 수 없어 ${replaced.length}개 워크플로를 새 템플릿으로 교체하고 원본을 .bak 으로 백업했습니다${NC}`);
+    for (const f of replaced) err(`     💾 .github/workflows/${f}.bak`);
+    err("     직접 수정한 내용이 있었다면 .bak 에서 옮겨 오세요. (업데이트 기준점은 이번 실행으로 새로 기록됩니다)");
+  }
+
   err("");
   err("  🔧 .github/scripts/");
   err("     ├─ version_manager.sh");
@@ -237,6 +249,13 @@ export function printSummary(ctx, targetRoot = ".") {
     err("");
     step++;
   }
+  // #668 — 라벨 동기화는 issue-labels.yml 이 바뀐 push 에서만 도는데, 설치 직후 첫 push 에서
+  // 실행 기록이 없는 경우가 실측됐다. 라벨이 없으면 상태 라벨 자동화가 조용히 무시되므로 1회 수동 실행을 안내한다.
+  err(`  ${step}️⃣  (권장) 템플릿 라벨 만들기`);
+  err("     → Actions 탭 > PROJECT-SYNC-GITHUB-LABELS > Run workflow 를 한 번 실행하세요.");
+  err("     → 안 하면 작업전·작업중 같은 상태 라벨이 레포에 없어 라벨 자동화가 무시됩니다.");
+  err("");
+  step++;
   err(SEPARATOR);
   err("");
   err(`${CYAN}📖 자세한 설정 방법은 다음 파일을 참고하세요:${NC}`);