projectops 4.2.46 → 4.3.0

package/README.md

@@ -7,7 +7,7 @@
 > 이슈 등록부터 커밋, 보고서, 배포까지. 개발자는 코드만 작성하세요.
 
 <!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->
-## 최신 버전 : v4.2.45 (2026-08-08)
+## 최신 버전 : v4.2.47 (2026-09-15)
 
 [전체 버전 기록 보기](CHANGELOG.md)
 
@@ -24,7 +24,7 @@
 
 | 기존 방식 | Projectops |
 |----------|---------------------|
-| 버전 수동 관리, 태그 직접 생성 | 릴리스(develop→main PR) 시 patch 버전 자동 증가 + 태그 생성 |
+| 버전 수동 관리, 태그 직접 생성 | 릴리스 시 커밋 내용에 맞는 버전 자동 증가 + 태그 생성 |
 | 체인지로그 직접 작성 (30분+) | CodeRabbit AI가 PR마다 자동 생성 |
 | CI/CD 처음부터 설정 | 프로젝트 타입별 워크플로우 즉시 구성 |
 | 이슈 매번 형식 맞춰 작성 (5분+) | `/pro-github` 한 번에 표준 템플릿 생성 + 등록 |
@@ -67,7 +67,7 @@ flowchart TD
 flowchart TD
     A([develop 푸시]) --> B[개발 통합]
     B --> C[develop→main 릴리스 PR]
-    C --> D["PR 내 버전 확정<br/>patch +1 + 태그 + AI 체인지로그"]
+    C --> D["PR 내 버전 확정<br/>커밋 기반 승격 + 태그 + AI 체인지로그"]
     D --> E[자동 머지]
     E --> F["main push → CI/CD 배포<br/>Flutter / Spring / React 등"]
     F --> G([완료])
@@ -131,7 +131,7 @@ npx projectops --mode skills
 | 기능 | 설명 | 문서 |
 |------|------|------|
 | **Agent Skills** | Claude Code, Cursor, Gemini CLI, Codex CLI에서 쓰는 17종 AI DevOps Skills | [상세](docs/SKILLS.md) |
-| **버전 자동화** | 릴리스(develop→main PR) 시 patch 버전 자동 증가 + Git 태그 | [상세](docs/VERSION-CONTROL.md) |
+| **버전 자동화** | 릴리스 시 커밋 제목으로 major/minor/patch 판정 + Git 태그 | [상세](docs/VERSION-CONTROL.md) |
 | **AI 체인지로그** | provider 사다리(CodeRabbit/GitHub Models/OpenAI 계열/commit) 기반 CHANGELOG 자동 생성 | [상세](docs/CHANGELOG-AUTOMATION.md) |
 | **PR Preview** | 댓글 한 줄로 임시 서버 배포, 닫으면 자동 삭제 | [상세](docs/PR-PREVIEW.md) |
 | **이슈 자동화** | 브랜치명/커밋 메시지 자동 제안, QA 이슈 생성 | [상세](docs/ISSUE-AUTOMATION.md) |

package/package.json

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

package/src/commands/full.js

@@ -15,6 +15,7 @@ import {
 import { copyUtilModules } from "../core/copy/util.js";
 import { copyCoderabbit } from "../core/copy/coderabbit.js";
 import { ensureGitignore } from "../core/copy/gitignore.js";
+import { verifyInstall } from "../core/verify.js";
 
 // context: { version, types, paths:Map, branch, versionCode, deployTarget, publishTargets, includeSecretBackup,
 //            force, repoName, resolvers, now, today }
@@ -64,5 +65,14 @@ export function runFull(context, tempDir, targetRoot = ".", hooks = {}) {
   ensureGitignore(targetRoot);
   copySetupGuide(tempDir, targetRoot);
 
-  return { workflows: wfCounters };
+  // 9. 설치 후 검증 (#549) — 디스크에 쓰인 최종 결과물을 다시 읽는다.
+  //    치환은 파일 단위로 흩어져 일어나고 auto 토큰은 resolver 결과에 의존하므로,
+  //    최종 내용을 보는 것이 실제 배포될 것과 같은 것을 보는 유일한 방법이다.
+  const verification = verifyInstall(targetRoot);
+  hooks.trace?.emit?.("verify", "scan", {
+    unresolved: verification.unresolved.length,
+    secrets: verification.secrets.size,
+  });
+
+  return { workflows: wfCounters, verification };
 }

package/src/commands/workflows.js

@@ -8,6 +8,7 @@ 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 { verifyInstall } from "../core/verify.js";
 
 export function runWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   const { types = [], force = true } = context;
@@ -31,7 +32,15 @@ export function runWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   copyConfigFolder(tempDir, targetRoot);
   for (const t of types) copyUtilModules(tempDir, t, { force }, targetRoot);
   copySetupGuide(tempDir, targetRoot);
-  return { workflows: wf };
+
+  // 설치 후 검증 (#549) — 워크플로우만 설치하는 모드라 오히려 더 필요하다.
+  const verification = verifyInstall(targetRoot);
+  hooks.trace?.emit?.("verify", "scan", {
+    unresolved: verification.unresolved.length,
+    secrets: verification.secrets.size,
+  });
+
+  return { workflows: wf, verification };
 }
 
 // 기존 version.yml에서 deploy: 블록을 제거하고 새로 append (.sh update_version_yml_deploy 멱등).

package/src/core/copy/simple.js

@@ -16,6 +16,8 @@ export function copyScripts(tempDir, targetRoot = ".") {
     "changelog_manager.py",
     "truncate_release_notes.sh", "truncate_release_notes.py",
     "issue_helper.py",
+    // 릴리스 워크플로우가 PAT 없이 머지한 뒤 후속 워크플로우를 깨울 때 호출 (#551).
+    "dispatch_downstream.py",
     "changelog_providers/_common.py", "changelog_providers/ladder.py",
     "changelog_providers/commit.py", "changelog_providers/github_ai.py",
     "changelog_providers/openai_compatible.py",

package/src/core/verify.js

@@ -0,0 +1,109 @@
+// 설치 후 검증 (#549) — 설치된 워크플로우를 다시 읽어 "이대로 돌아가는가"를 본다.
+//
+// 왜 설치 전이 아니라 후인가: 치환은 파일 단위로 흩어져 일어나고 auto 토큰은 resolver 결과에
+// 의존한다. 최종 디스크 내용을 보는 것이 실제로 배포될 것과 같은 것을 보는 유일한 방법이다.
+import { join } from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { PATHS } from "./paths.js";
+
+// 치환 대상이 아닌 토큰 — 워크플로우 스크립트 안의 heredoc 구분자다. 값이 아니라 문법이므로
+// 미치환 검사에서 제외한다. (예: cat <<'__SUH_FILE_CONTENT_EOF__')
+const SENTINEL_RE = /^__SUH_[A-Z0-9_]*__$/;
+const PLACEHOLDER_RE = /__[A-Z][A-Z0-9_]*__/g;
+
+// 주석으로 죽어 있는 줄 — 실행되지 않으므로 검사 대상이 아니다.
+// 템플릿에는 "[선택] ..." 예시 스텝이 통째로 주석 처리돼 들어 있는데, 이걸 세면
+// 쓰지도 않는 Secret을 "등록하세요"라고 안내하게 된다.
+const isCommented = (line) => /^\s*#/.test(line);
+
+// 검사 대상 파일 목록. 호출부가 명시하지 않으면 설치된 워크플로우 전체를 스캔한다
+// (복사 결과 목록을 조합해 넘기는 것보다, 최종 디스크 상태를 그대로 보는 쪽이 목적에 맞다).
+function listWorkflowFiles(workflowsDir, filenames) {
+  if (filenames && filenames.length) return filenames;
+  if (!existsSync(workflowsDir)) return [];
+  try {
+    return readdirSync(workflowsDir, { withFileTypes: true })
+      .filter((e) => e.isFile() && /\.ya?ml$/.test(e.name))
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function readLines(workflowsDir, filename) {
+  const p = join(workflowsDir, filename);
+  if (!existsSync(p)) return null;
+  try {
+    return readFileSync(p, "utf8").split(/\r?\n/);
+  } catch {
+    return null;
+  }
+}
+
+// 미치환 플레이스홀더 스캔.
+// auto 토큰 계산이 실패해도(예: application.yaml을 못 찾아 경로가 빈 문자열) 그 줄을 건드리지
+// 않고 넘어가므로, __APPLICATION_YML_DIR__ 이 그대로 남은 워크플로우가 "설치 성공"으로 끝난다.
+// 문제는 배포 시점에야 그 이름의 디렉터리가 만들어지며 드러난다.
+//
+// 반환: [{ filename, line, token, text }] — 사람이 바로 고칠 수 있게 줄 번호까지 준다.
+export function scanUnsubstituted(workflowsDir, filenames = []) {
+  const found = [];
+  for (const filename of listWorkflowFiles(workflowsDir, filenames)) {
+    const lines = readLines(workflowsDir, filename);
+    if (!lines) continue;
+    lines.forEach((text, i) => {
+      if (isCommented(text)) return;
+      for (const token of text.match(PLACEHOLDER_RE) || []) {
+        if (SENTINEL_RE.test(token)) continue;
+        found.push({ filename, line: i + 1, token, text: text.trim() });
+      }
+    });
+  }
+  return found;
+}
+
+// GITHUB_TOKEN은 Actions가 자동 주입하므로 사용자가 등록할 대상이 아니다.
+const AUTO_SECRETS = new Set(["GITHUB_TOKEN"]);
+
+// 없어도 워크플로우가 도는 secret — 폴백이 문서화돼 있다. 필수와 섞어 "등록해야 동작합니다"라고
+// 하면 안내 자체를 못 믿게 되므로 분리한다.
+//   MODEL_API_KEY      → 없으면 GitHub Models(무료) → commit 규칙 fallback (#455 provider 사다리)
+//   _GITHUB_PAT_TOKEN  → 없으면 GITHUB_TOKEN으로 머지하고 후속 워크플로우를 직접 깨운다 (#551)
+export const OPTIONAL_SECRETS = new Set(["MODEL_API_KEY", "_GITHUB_PAT_TOKEN"]);
+
+const SECRET_RE = /secrets\.([A-Z_][A-Z0-9_]*)/g;
+
+// 설치된 워크플로우가 요구하는 GitHub Secret 목록.
+// 완료 화면이 아무것도 안내하지 않는 바람에, 배포 워크플로우가 실제로 필요로 하는
+// SERVER_HOST·SSH_KEY 같은 값이 드러나지 않았다. 설치 직후 상태로는 배포가 돌지 않는데
+// 그 사실을 알 방법이 없다.
+//
+// 반환: Map<secretName, string[] 그 secret을 쓰는 파일명> (이름 오름차순)
+export function collectRequiredSecrets(workflowsDir, filenames = []) {
+  const out = new Map();
+  for (const filename of listWorkflowFiles(workflowsDir, filenames)) {
+    const lines = readLines(workflowsDir, filename);
+    if (!lines) continue;
+    for (const line of lines) {
+      if (isCommented(line)) continue;
+      for (const m of line.matchAll(SECRET_RE)) {
+        const name = m[1];
+        if (AUTO_SECRETS.has(name) || OPTIONAL_SECRETS.has(name)) continue;
+        if (!out.has(name)) out.set(name, []);
+        const users = out.get(name);
+        if (!users.includes(filename)) users.push(filename);
+      }
+    }
+  }
+  return new Map([...out.entries()].sort(([a], [b]) => a.localeCompare(b)));
+}
+
+// 설치 직후 한 번에 돌리는 진입점. targetRoot 기준으로 워크플로우 폴더를 찾는다.
+// 반환: { unresolved: [...], secrets: Map, ok: boolean }
+export function verifyInstall(targetRoot = ".", filenames = []) {
+  const workflowsDir = join(targetRoot, PATHS.workflowsDir);
+  const unresolved = scanUnsubstituted(workflowsDir, filenames);
+  const secrets = collectRequiredSecrets(workflowsDir, filenames);
+  return { unresolved, secrets, ok: unresolved.length === 0 };
+}

package/src/core/version-yml.js

@@ -16,9 +16,14 @@ const HEADER = `# ==============================================================
 # 4. project_paths: 타입별 프로젝트 폴더 (레포 루트 기준 상대경로, 모노레포용)
 #
 # 자동 버전 업데이트:
-# - patch: 자동으로 세 번째 자리 증가 (x.x.x -> x.x.x+1)
-# - version_code: 매 빌드마다 자동으로 1씩 증가
-# - minor/major: 수동으로 직접 수정 필요
+# - version_code: 매 빌드마다 자동으로 1씩 증가 (아래 판정과 무관)
+# - 버전 승격 폭은 metadata.template.options.semver_auto 가 정합니다
+#   semver_auto: true  -> 릴리스 구간 커밋 제목으로 판정
+#                         "제목 : feat! : 내용" 또는 "feat!:" -> major (x+1.0.0)
+#                         "제목 : feat : 내용"  또는 "feat:"  -> minor (x.y+1.0)
+#                         그 외(fix/docs/chore/refactor/test) -> patch (x.y.z+1)
+#   키 없음 / false     -> 항상 patch +1
+# - 위 판정과 무관하게 version 값을 직접 수정해도 됩니다
 #
 # 프로젝트 타입별 동기화 파일:
 # - spring: build.gradle (version = "x.y.z")

package/src/index.js

@@ -221,6 +221,7 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
   printSummary({
     mode: opts.mode, types, version, deployBranch: context.deployBranch, migrationGuidePath,
     counters: { workflows: result?.workflows?.copied ?? 0, workflowFiles: result?.workflows?.copiedFiles ?? [], utilModules: 0 },
+    verification: result?.verification,   // #549 설치 후 검증 결과 (full/workflows 모드에서만 존재)
   }, cwd);
   return 0;
 }

package/src/ui/summary.js

@@ -138,15 +138,55 @@ export function printSummary(ctx, targetRoot = ".") {
   }
   err("");
 
+  // 설치 후 검증 결과 (#549) — 문제가 있을 때만 펼치고, 정상이면 한 줄로 압축한다.
+  const verification = ctx?.verification;
+  if (verification) {
+    const unresolved = verification.unresolved || [];
+    err(SEPARATOR);
+    err("");
+    if (unresolved.length === 0) {
+      err("✅ 설치 검증: 치환되지 않은 값 없음");
+    } else {
+      err(`${YELLOW}⚠️  설치 검증: 치환되지 않은 값 ${unresolved.length}건${NC}`);
+      err("");
+      err("   아래 위치에 템플릿 값이 그대로 남아 있습니다. 그대로 두면 배포 시점에 실패합니다.");
+      err("   (프로젝트 구조를 자동으로 찾지 못한 경우입니다 — 직접 값을 채워주세요)");
+      err("");
+      for (const u of unresolved.slice(0, 10)) {
+        err(`   ${u.filename}:${u.line}  ${u.token}`);
+      }
+      if (unresolved.length > 10) err(`   … 외 ${unresolved.length - 10}건`);
+    }
+    err("");
+
+    // 필요한 Secret 목록 — 설치된 워크플로우 기준이라 "이 레포에 실제로 필요한 것"만 나온다.
+    const secrets = verification.secrets;
+    if (secrets && secrets.size > 0) {
+      err(`${CYAN}🔑 등록이 필요한 GitHub Secret (${secrets.size}개)${NC}`);
+      err("   → Repository Settings > Secrets and variables > Actions");
+      err("");
+      for (const [name, users] of secrets) {
+        const where = users.length > 2 ? `${users.slice(0, 2).join(", ")} 외 ${users.length - 2}개` : users.join(", ");
+        err(`   ${name}`);
+        err(`     └ ${where}`);
+      }
+      err("");
+      err("   💡 등록 전까지 해당 워크플로우는 실패합니다. 쓰지 않는 워크플로우라면 무시해도 됩니다.");
+      err("");
+    }
+  }
+
   // 필수 3가지 작업 안내 (.sh L5605~5625 — 원문 유지)
   err(SEPARATOR);
   err("");
-  err(`${YELLOW}⚠️  다음 3가지 작업을 완료해주세요:${NC}`);
+  err(`${YELLOW}⚠️  다음 작업을 확인해주세요:${NC}`);
   err("");
-  err("  1️⃣  GitHub Personal Access Token 설정");
+  // #551 — PAT는 없어도 릴리스가 완주한다. 있으면 후속 자동화가 더 매끄러워질 뿐이다.
+  err("  1️⃣  (선택) GitHub Personal Access Token 설정");
+  err("     → 없어도 릴리스는 정상 동작합니다. 등록하면 릴리스 후 후속 워크플로우가");
+  err("        더 확실하게 이어지고, 브랜치 보호 규칙이 있어도 자동 머지가 가능합니다.");
   err("     → Repository Settings > Secrets > Actions");
-  err("     → Secret Name: _GITHUB_PAT_TOKEN");
-  err("     → Scopes: repo, workflow");
+  err("     → Secret Name: _GITHUB_PAT_TOKEN / Scopes: repo, workflow");
   err("");
   // #490 — 마법사가 브랜치를 직접 생성(또는 존재 확인)했으면 같은 작업을 재지시하지 않는다
   if (deployBranchReady) {