projectops 3.0.192 → 3.0.194

package/src/core/copy/gitignore.js

@@ -0,0 +1,55 @@
+// .gitignore 보장 (.sh ensure_gitignore + normalize/check 등가) — template_integrator.sh 3996~4111.
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+const REQUIRED_ENTRIES = ["/.idea", "/.claude/settings.local.json"];
+
+// .sh normalize_gitignore_entry: 주석 제거·트림·앞 / 제거·앞 ./ 제거·뒤 / 제거. 빈값이면 원본.
+export function normalizeGitignoreEntry(entry) {
+  let e = String(entry);
+  e = e.replace(/#.*$/, "");        // 주석 제거
+  e = e.trim();                      // 앞뒤 공백
+  e = e.replace(/^\//, "");         // 앞 /
+  e = e.replace(/^\.\//, "");       // 앞 ./
+  e = e.replace(/\/$/, "");         // 뒤 /
+  return e === "" ? String(entry) : e;
+}
+
+function entryExists(target, content) {
+  const nt = normalizeGitignoreEntry(target);
+  for (const line of content.split("\n")) {
+    if (/^\s*#/.test(line)) continue;
+    if (/^\s*$/.test(line)) continue;
+    if (normalizeGitignoreEntry(line) === nt) return true;
+  }
+  return false;
+}
+
+const NEW_FILE_CONTENT =
+  "# IDE Settings\n" +
+  "/.idea\n" +
+  "\n" +
+  "# Claude AI Settings\n" +
+  "/.claude/settings.local.json\n";
+
+// 반환: {created, added:[...]}
+export function ensureGitignore(targetRoot = ".") {
+  const p = join(targetRoot, ".gitignore");
+  if (!existsSync(p)) {
+    writeFileSync(p, NEW_FILE_CONTENT);
+    return { created: true, added: REQUIRED_ENTRIES.slice() };
+  }
+  let content = readFileSync(p, "utf8");
+  const toAdd = REQUIRED_ENTRIES.filter((e) => !entryExists(e, content));
+  if (toAdd.length === 0) return { created: false, added: [] };
+
+  // 파일 끝에 개행 없으면 추가 (.sh: tail -c 1 이 non-empty면 echo "")
+  if (content.length > 0 && !content.endsWith("\n")) content += "\n";
+  content += "\n";
+  content += "# ====================================================================\n";
+  content += "# projectops: Auto-added entries\n";
+  content += "# ====================================================================\n";
+  for (const e of toAdd) content += e + "\n";
+  writeFileSync(p, content);
+  return { created: false, added: toAdd };
+}

package/src/core/copy/readme.js

@@ -0,0 +1,30 @@
+// README 버전 섹션 추가 (.sh add_version_section_to_readme 등가) — template_integrator.sh 2145~2181.
+import { join } from "node:path";
+import { existsSync, readFileSync, appendFileSync } from "node:fs";
+
+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;
+
+// README.md 없으면 스킵. 마커 또는 버전 라인 있으면 스킵. 없으면 파일 끝에 append.
+// 반환: 'skip-no-readme' | 'skip-marker' | 'skip-version-line' | 'added'
+export function addVersionSectionToReadme(version, targetRoot = ".") {
+  const p = join(targetRoot, "README.md");
+  if (!existsSync(p)) return "skip-no-readme";
+  const content = readFileSync(p, "utf8");
+  if (content.includes(MARKER)) return "skip-marker";
+  if (VERSION_LINE_RE.test(content)) return "skip-version-line";
+
+  // .sh: cat >> README.md << EOF — EOF 다음 첫 줄이 빈 줄이므로 append 본문은 "\n---\n..."로 시작.
+  // (원본 파일이 개행으로 끝난다는 전제는 .sh와 동일 — heredoc은 원본 끝에 그대로 붙는다.)
+  const section =
+    "\n" +
+    "---\n" +
+    "\n" +
+    "<!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->\n" +
+    `## 최신 버전 : v${version}\n` +
+    "\n" +
+    "[전체 버전 기록 보기](CHANGELOG.md)\n";
+  appendFileSync(p, section);
+  return "added";
+}

package/src/core/copy/simple.js

@@ -0,0 +1,55 @@
+// 단순 복사 함수 (무조건 덮어쓰기류) — .sh copy_scripts/config/issue/discussion/setup_guide 등가.
+// 실측: template_integrator.sh 3818, 3845, 3872, 3895, 4114.
+import { join } from "node:path";
+import { chmodSync } from "node:fs";
+import { PATHS } from "../paths.js";
+import { exists, copyFileSync, copyDirSync } from "../fsutil.js";
+
+// version_manager.sh, changelog_manager.py 2개만 무조건 덮어쓰기 + chmod +x.
+export function copyScripts(tempDir, targetRoot = ".") {
+  const scripts = ["version_manager.sh", "changelog_manager.py"];
+  let copied = 0;
+  for (const s of scripts) {
+    const src = join(tempDir, PATHS.scriptsDir, s);
+    if (exists(src)) {
+      const dst = join(targetRoot, PATHS.scriptsDir, s);
+      copyFileSync(src, dst);
+      try { chmodSync(dst, 0o755); } catch { /* Windows 등 chmod 무의미 */ }
+      copied++;
+    }
+  }
+  return copied;
+}
+
+// .github/config 폴더 전체 덮어쓰기. 없으면 스킵.
+export function copyConfigFolder(tempDir, targetRoot = ".") {
+  const src = join(tempDir, ".github", "config");
+  if (!exists(src)) return false;
+  copyDirSync(src, join(targetRoot, ".github", "config"));
+  return true;
+}
+
+// .github/ISSUE_TEMPLATE/ 전체 + PULL_REQUEST_TEMPLATE.md 덮어쓰기.
+export function copyIssueTemplates(tempDir, targetRoot = ".") {
+  const srcIssue = join(tempDir, ".github", "ISSUE_TEMPLATE");
+  if (exists(srcIssue)) copyDirSync(srcIssue, join(targetRoot, ".github", "ISSUE_TEMPLATE"));
+  const srcPr = join(tempDir, ".github", "PULL_REQUEST_TEMPLATE.md");
+  if (exists(srcPr)) copyFileSync(srcPr, join(targetRoot, ".github", "PULL_REQUEST_TEMPLATE.md"));
+}
+
+// .github/DISCUSSION_TEMPLATE/ 전체. 없으면 스킵.
+export function copyDiscussionTemplates(tempDir, targetRoot = ".") {
+  const src = join(tempDir, ".github", "DISCUSSION_TEMPLATE");
+  if (!exists(src)) return false;
+  copyDirSync(src, join(targetRoot, ".github", "DISCUSSION_TEMPLATE"));
+  return true;
+}
+
+// SUH-DEVOPS-TEMPLATE-SETUP-GUIDE.md 루트로 덮어쓰기. 없으면 스킵.
+export const SETUP_GUIDE_NAME = "SUH-DEVOPS-TEMPLATE-SETUP-GUIDE.md";
+export function copySetupGuide(tempDir, targetRoot = ".") {
+  const src = join(tempDir, SETUP_GUIDE_NAME);
+  if (!exists(src)) return false;
+  copyFileSync(src, join(targetRoot, SETUP_GUIDE_NAME));
+  return true;
+}

package/src/core/copy/util.js

@@ -0,0 +1,22 @@
+// util 모듈 복사 (.sh copy_util_modules 등가, force 경로) — template_integrator.sh 4203~.
+// tempDir/.github/util/<type>/ 있으면 (force) .github/util/<type>/로 전체 복사, 모듈 수 카운트.
+import { join } from "node:path";
+import { readdirSync } from "node:fs";
+import { exists, copyDirSync } from "../fsutil.js";
+
+// 반환: {copied:bool, moduleCount:number}. force가 아니면(비TTY) 스킵.
+export function copyUtilModules(tempDir, type, { force = false } = {}, targetRoot = ".") {
+  const src = join(tempDir, ".github", "util", type);
+  if (!exists(src)) return { copied: false, moduleCount: 0 };
+  if (!force) return { copied: false, moduleCount: 0 }; // SP2-B: force 경로만
+
+  const dst = join(targetRoot, ".github", "util", type);
+  copyDirSync(src, dst);
+
+  // 하위 디렉토리 개수 = 모듈 수 (.sh: for dir in "$util_dst"/*/)
+  let moduleCount = 0;
+  for (const e of readdirSync(dst, { withFileTypes: true })) {
+    if (e.isDirectory()) moduleCount++;
+  }
+  return { copied: true, moduleCount };
+}

package/src/core/copy/workflows.js

@@ -0,0 +1,145 @@
+// 워크플로우 복사 엔진 (.sh copy_workflows + _copy_workflows_for_type 등가).
+// 실측: template_integrator.sh 3398~3815. SP2-B는 --force 경로만 구현.
+// (대화형 3지선 메뉴·env 계획 질문은 SP2-C. force/비TTY의 기본 선택은 "건너뛰기"이므로 등가.)
+import { join, basename } from "node:path";
+import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { PATHS } from "../paths.js";
+import { exists, copyFileSync, listYamlFiles } from "../fsutil.js";
+import { isUnchanged, substituteEnv } from "../wizard-env.js";
+
+// 한 파일에 env 치환(기본값)을 적용해 대상 파일을 갱신 (.sh configure_workflow_env 등가).
+function configureEnv(targetPath, { type, projectPath = ".", repoName = "", resolvers = {}, collectAsks = null }) {
+  const content = readFileSync(targetPath, "utf8");
+  if (!content.includes("@wizard")) return;
+  const out = substituteEnv(content, { type, useDefaults: true, projectPath, repoName, resolvers, collectAsks });
+  writeFileSync(targetPath, out);
+}
+
+// 3분류 (신규/unchanged/changed) — 대상 워크플로우 디렉토리 기준.
+function classify(srcDir, workflowsDir, envOpts) {
+  const result = { newFiles: [], unchanged: [], changed: [] };
+  for (const filename of listYamlFiles(srcDir)) {
+    const src = join(srcDir, filename);
+    const dst = join(workflowsDir, filename);
+    if (existsSync(dst)) {
+      const tpl = readFileSync(src, "utf8");
+      const inst = readFileSync(dst, "utf8");
+      if (isUnchanged(tpl, inst, envOpts)) result.unchanged.push(filename);
+      else result.changed.push(filename);
+    } else {
+      result.newFiles.push(filename);
+    }
+  }
+  return result;
+}
+
+// copy_workflows 본체.
+// context: { types:[], paths:Map, includeNexus, includeSecretBackup, force, repoName, resolvers }
+// tempDir: 다운로드 원본. targetRoot: 통합 대상 루트.
+// 반환: {copied, skipped, templateAdded, optionalCopied}
+export function copyWorkflows(context, tempDir, targetRoot = ".") {
+  const { types = [], paths = new Map(), includeNexus = false, includeSecretBackup = false, repoName = "", resolvers = {} } = context;
+  const workflowsDir = join(targetRoot, PATHS.workflowsDir);
+  const projectTypesDir = join(tempDir, PATHS.workflowsDir, PATHS.projectTypesDir);
+  if (!exists(projectTypesDir)) throw new Error("템플릿 저장소 구조 오류 — project-types 폴더를 찾지 못했습니다.");
+
+  const counters = { copied: 0, skipped: 0, templateAdded: 0, optionalCopied: 0 };
+  const deployValues = new Map(); // Map<type, Map<key,value>> — deploy 블록용 ask 값
+  counters.deployValues = deployValues;
+  const envOptsFor = (type) => ({ type, projectPath: paths.get(type) || ".", repoName, resolvers });
+
+  // (1) common — unchanged면 스킵, 아니면 무조건 덮어쓰기
+  const commonDir = join(projectTypesDir, "common");
+  if (exists(commonDir)) {
+    for (const filename of listYamlFiles(commonDir)) {
+      const src = join(commonDir, filename);
+      const dst = join(workflowsDir, filename);
+      if (existsSync(dst) && isUnchanged(readFileSync(src, "utf8"), readFileSync(dst, "utf8"), envOptsFor("common"))) {
+        counters.skipped++;
+        continue;
+      }
+      copyFileSync(src, dst);
+      counters.copied++;
+    }
+  }
+
+  // (2~4) 타입별
+  for (const type of types) {
+    const asks = new Map();
+    copyWorkflowsForType(type, projectTypesDir, workflowsDir, { includeNexus, ...context, envOptsFor, collectAsks: asks }, counters);
+    if (asks.size) deployValues.set(type, asks);
+  }
+
+  // (5) common/secret-backup — 있으면 무조건 스킵/신규만 복사
+  const secretDir = join(commonDir, "secret-backup");
+  if (exists(secretDir) && includeSecretBackup) {
+    for (const filename of listYamlFiles(secretDir)) {
+      const dst = join(workflowsDir, filename);
+      if (existsSync(dst)) continue; // 이미 존재하면 스킵
+      copyFileSync(join(secretDir, filename), dst);
+      counters.optionalCopied++;
+      counters.copied++;
+    }
+  }
+
+  return counters;
+}
+
+function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters) {
+  const { includeNexus, force = false, paths = new Map(), repoName = "", resolvers = {}, envOptsFor, collectAsks = null } = ctx;
+  const typeDir = join(projectTypesDir, type);
+  const envOpts = envOptsFor(type);
+  let unchangedNames = [];
+
+  // 타입별 워크플로우 (직하위)
+  if (exists(typeDir)) {
+    const { newFiles, unchanged, changed } = classify(typeDir, workflowsDir, envOpts);
+    unchangedNames = unchanged.slice();
+    for (const f of unchanged) counters.skipped++;
+    for (const f of newFiles) { copyFileSync(join(typeDir, f), join(workflowsDir, f)); counters.copied++; }
+    // changed: force/비TTY 기본은 "건너뛰기"(기존 유지)
+    if (!force) { /* 대화형 메뉴는 SP2-C */ }
+    for (const f of changed) counters.skipped++; // force 경로 = skip
+  }
+
+  // server-deploy
+  const serverDeployDir = join(typeDir, "server-deploy");
+  if (exists(serverDeployDir)) {
+    if (includeNexus) {
+      // Nexus 프로젝트 → 폴더째 제외 (복사 안 함)
+    } else {
+      const { newFiles, unchanged, changed } = classify(serverDeployDir, workflowsDir, envOpts);
+      for (const f of unchanged) counters.skipped++;
+      for (const f of newFiles) { copyFileSync(join(serverDeployDir, f), join(workflowsDir, f)); counters.copied++; }
+      for (const f of changed) counters.skipped++; // force = skip
+    }
+  }
+
+  // nexus (opt-in)
+  const nexusDir = join(typeDir, "nexus");
+  if (exists(nexusDir) && includeNexus) {
+    for (const filename of listYamlFiles(nexusDir)) {
+      const src = join(nexusDir, filename);
+      const dst = join(workflowsDir, filename);
+      if (existsSync(dst) && isUnchanged(readFileSync(src, "utf8"), readFileSync(dst, "utf8"), envOpts)) {
+        counters.skipped++;
+        continue;
+      }
+      if (existsSync(dst)) renameSync(dst, dst + ".bak");
+      copyFileSync(src, dst);
+      counters.optionalCopied++;
+      counters.copied++;
+    }
+  }
+
+  // env 치환 — 이 타입의 원본 디렉토리들에서 복사돼 존재하고 unchanged 아닌 파일만
+  for (const srcDir of [typeDir, serverDeployDir, nexusDir]) {
+    if (!exists(srcDir)) continue;
+    for (const filename of listYamlFiles(srcDir)) {
+      const target = join(workflowsDir, filename);
+      if (!existsSync(target)) continue;            // 건너뛴 파일 제외
+      if (unchangedNames.includes(filename)) continue; // unchanged 제외
+      configureEnv(target, { type, projectPath: paths.get(type) || ".", repoName, resolvers, collectAsks });
+    }
+  }
+}

package/src/core/detect-fs.js

@@ -0,0 +1,64 @@
+// 실 파일시스템 프로젝트 감지 (.sh detect_* 실행부 등가).
+// SP2-A detect.js 순수 함수를 fs/git으로 구동한다.
+import { existsSync, readFileSync } from "node:fs";
+import { join, basename } from "node:path";
+import { execFileSync } from "node:child_process";
+import { detectTypesFromMarkers, detectVersionFromFiles } from "./detect.js";
+import { parseExisting } from "./version-yml.js";
+
+const hasFile = (root) => (rel) => existsSync(join(root, rel));
+const readFile = (root) => (rel) => {
+  try { return readFileSync(join(root, rel), "utf8"); } catch { return null; }
+};
+
+function gitOut(root, args) {
+  try {
+    return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch { return ""; }
+}
+
+// 타입 감지 — version.yml의 project_types 최우선(source of truth), 없으면 마커 스캔.
+export function detectTypes(root) {
+  const vy = join(root, "version.yml");
+  if (existsSync(vy)) {
+    const { types } = parseExisting(readFileSync(vy, "utf8"));
+    if (types.length) return types; // basic 포함, 명시돼 있으면 그대로
+  }
+  return detectTypesFromMarkers({ has: hasFile(root), read: readFile(root) });
+}
+
+// 버전 감지 — .sh detect_version 순서. jq 유무는 command 존재로 판정.
+export function detectVersion(root, { hasJq } = {}) {
+  const read = readFile(root);
+  const readJson = (rel) => { const c = read(rel); try { return c ? JSON.parse(c) : null; } catch { return null; } };
+  const jq = hasJq ?? hasCommand("jq");
+  const gitTag = gitOut(root, ["describe", "--tags", "--abbrev=0"]);
+  return detectVersionFromFiles({ read, readJson, hasJq: jq, gitTag });
+}
+
+// 기본 브랜치 감지 — symbolic-ref → remote show → main.
+export function detectDefaultBranch(root) {
+  let b = gitOut(root, ["symbolic-ref", "refs/remotes/origin/HEAD"]);
+  if (b) return b.replace(/^refs\/remotes\/origin\//, "");
+  const show = gitOut(root, ["remote", "show", "origin"]);
+  const m = show.match(/HEAD branch:\s*(\S+)/);
+  if (m) return m[1];
+  return "main";
+}
+
+// 레포명 — git remote get-url origin 마지막 세그먼트, 실패 시 폴더명.
+export function detectRepoName(root) {
+  const url = gitOut(root, ["remote", "get-url", "origin"]);
+  if (url) {
+    const seg = url.replace(/\.git$/, "").split(/[/:]/).pop();
+    if (seg) return seg;
+  }
+  return basename(root);
+}
+
+function hasCommand(cmd) {
+  try {
+    execFileSync(process.platform === "win32" ? "where" : "which", [cmd], { stdio: "ignore" });
+    return true;
+  } catch { return false; }
+}

package/src/core/detect.js

@@ -0,0 +1,62 @@
+// package.json 내용 분류 (.sh classify_package_json 등가) — 원본 파일 텍스트에 대한
+// grep 부분문자열 매칭. dependencies 파싱이 아니라 raw 텍스트 검사여야 등가.
+// 입력은 package.json의 원문 문자열(raw). 순서 중요.
+export function classifyPackageText(raw) {
+  const s = String(raw || "");
+  if (s.includes("@react-native") || s.includes("react-native")) {
+    return s.includes("expo") ? "react-native-expo" : "react-native";
+  }
+  if (s.includes('"next"')) return "next";
+  if (s.includes('"react"')) return "react";
+  return "node";
+}
+
+// 편의: 파싱된 객체를 받는 경우 원문으로 재직렬화해 위 규칙 적용
+export function classifyPackageJson(pkgOrRaw) {
+  const raw = typeof pkgOrRaw === "string" ? pkgOrRaw : JSON.stringify(pkgOrRaw || {});
+  return classifyPackageText(raw);
+}
+
+// 마커 스캔 (동작명세 §3.1). has(relpath)=>bool 주입. node는 다른 타입 있으면 미추가.
+// read(relpath)=>string|null 로 package.json 원문을 받아 classifyPackageText에 넘긴다.
+export function detectTypesFromMarkers({ has, read }) {
+  const types = [];
+  if (has("pubspec.yaml")) types.push("flutter");
+  if (has("build.gradle") || has("build.gradle.kts") || has("pom.xml")) types.push("spring");
+  if (has("pyproject.toml") || has("setup.py") || has("requirements.txt")) types.push("python");
+  if (has("package.json")) {
+    const cls = classifyPackageText(read ? read("package.json") : "");
+    if (cls === "node") { if (types.length === 0) types.push("node"); }
+    else types.push(cls);
+  }
+  return types.length ? [...new Set(types)] : ["basic"];
+}
+
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
+
+// 버전 감지 (동작명세 §3.3) — 순서대로 첫 성공. read(relpath)=>string|null 주입.
+export function detectVersionFromFiles({ read, readJson, hasJq, gitTag }) {
+  const pkg = readJson?.("package.json");
+  if (hasJq && pkg?.version && VERSION_RE.test(pkg.version)) return pkg.version;
+  const grab = (content, re) => {
+    for (const line of (content || "").split("\n")) {
+      const m = line.match(re);
+      if (m && VERSION_RE.test(m[1])) return m[1];
+    }
+    return null;
+  };
+  let v;
+  if ((v = grab(read("build.gradle"), /version\s*=\s*["']?(\d+\.\d+\.\d+)/))) return v;
+  if ((v = grab(read("pubspec.yaml"), /^version:\s*(\d+\.\d+\.\d+)/))) return v;
+  if ((v = grab(read("pyproject.toml"), /version\s*=\s*["']?(\d+\.\d+\.\d+)/))) return v;
+  if (gitTag) { const t = String(gitTag).replace(/^v/, ""); if (VERSION_RE.test(t)) return t; }
+  return "0.0.1";
+}
+
+export function markerForType(type) {
+  return { flutter: "pubspec.yaml", "react-native-expo": "app.json", python: "pyproject.toml", spring: "build.gradle" }[type] || "package.json";
+}
+
+export function extraMarkers(type) {
+  return { python: ["setup.py", "requirements.txt"], spring: ["build.gradle.kts", "pom.xml"] }[type] || [];
+}

package/src/core/exclusions.js

@@ -0,0 +1,25 @@
+// 템플릿 다운로드 후 제거하는 항목 — .sh download_template 내부 배열과 동기화
+// ⚠️ CLAUDE.md "3곳 동시 수정" 규칙의 4번째 동기화 지점:
+//    template_initializer.sh / template_integrator.sh / .ps1 / 이 파일
+export const DOCS_TO_REMOVE = [
+  "CONTRIBUTING.md",
+  "CLAUDE.md",
+  "AGENTS.md",
+  "GEMINI.md",
+  "gemini-extension.json",
+];
+
+export const PLUGIN_ITEMS_TO_REMOVE = [
+  ".claude-plugin",
+  ".codex-plugin",
+  ".agents",
+  ".cursor",
+  "scripts",
+  "package.json",
+  "harness",
+  "bin",
+  "src",
+  ".github/workflows/PROJECT-TEMPLATE-PLUGIN-VERSION-SYNC.yaml",
+  ".github/workflows/PROJECT-TEMPLATE-NPM-PUBLISH.yaml",
+];
+// ⚠️ skills/ 는 제외하지 않는다 (Cursor 설치 소스로 보존)

package/src/core/fsutil.js

@@ -0,0 +1,40 @@
+// 파일시스템 공용 유틸 (LF 보존 바이트 복사). 텍스트는 그대로 복사해 원본 줄바꿈 유지.
+import {
+  cpSync, existsSync, readFileSync, writeFileSync, mkdirSync,
+  readdirSync, rmSync,
+} from "node:fs";
+import { dirname } from "node:path";
+
+export const exists = (p) => existsSync(p);
+export const readText = (p) => readFileSync(p, "utf8");
+
+export function writeText(p, s) {
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, s);
+}
+
+// 단일 파일 복사 (부모 디렉토리 자동 생성, 바이트 그대로)
+export function copyFileSync(src, dst) {
+  mkdirSync(dirname(dst), { recursive: true });
+  cpSync(src, dst);
+}
+
+// 디렉토리 재귀 복사 (내용을 dst 하위로)
+export function copyDirSync(src, dst) {
+  mkdirSync(dst, { recursive: true });
+  cpSync(src, dst, { recursive: true });
+}
+
+// 파일/폴더 삭제 (없어도 무해)
+export function remove(p) {
+  rmSync(p, { recursive: true, force: true });
+}
+
+// 디렉토리 직하위 .yaml/.yml 파일명 목록 (정렬). 하위 폴더 제외.
+export function listYamlFiles(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && /\.(ya?ml)$/.test(e.name))
+    .map((e) => e.name)
+    .sort();
+}

package/src/core/paths.js

@@ -0,0 +1,14 @@
+// 경로 상수 (.sh readonly 상수군 등가) — template_integrator.sh 113~137
+export const PATHS = {
+  tempDir: ".template_download_temp",
+  versionFile: "version.yml",
+  workflowsDir: ".github/workflows",
+  scriptsDir: ".github/scripts",
+  projectTypesDir: "project-types",
+};
+
+export const TEMPLATE_RAW_URL = "https://raw.githubusercontent.com/Cassiiopeia/projectops/main";
+export const TEMPLATE_REPO = "https://github.com/Cassiiopeia/projectops.git";
+export const WORKFLOW_PREFIX = "PROJECT";
+export const WORKFLOW_COMMON_PREFIX = "PROJECT-COMMON";
+export const WORKFLOW_TEMPLATE_INIT = "PROJECT-TEMPLATE-INITIALIZER.yaml";

package/src/core/version-yml.js

@@ -0,0 +1,146 @@
+// version.yml 파싱·생성 (.sh create_version_yml 등가, 전체 재생성 전략 D4).
+// ⚠️ YAML 재직렬화 금지 — 주석이 데이터. .sh heredoc과 바이트 동일한 템플릿 문자열.
+// 실측 기준: template_integrator.sh 2184~2354.
+
+const HEADER = `# ===================================================================
+# 프로젝트 버전 관리 파일
+# ===================================================================
+#
+# 이 파일은 다양한 프로젝트 타입에서 버전 정보를 중앙 관리하기 위한 파일입니다.
+# GitHub Actions 워크플로우가 이 파일을 읽어 자동으로 버전을 관리합니다.
+#
+# 사용법:
+# 1. version: "1.0.0" - 사용자에게 표시되는 버전
+# 2. version_code: 1 - Play Store/App Store 빌드 번호 (1부터 자동 증가)
+# 3. project_type: 프로젝트 타입 지정
+# 4. project_paths: 타입별 프로젝트 폴더 (레포 루트 기준 상대경로, 모노레포용)
+#
+# 자동 버전 업데이트:
+# - patch: 자동으로 세 번째 자리 증가 (x.x.x -> x.x.x+1)
+# - version_code: 매 빌드마다 자동으로 1씩 증가
+# - minor/major: 수동으로 직접 수정 필요
+#
+# 프로젝트 타입별 동기화 파일:
+# - spring: build.gradle (version = "x.y.z")
+# - flutter: pubspec.yaml (version: x.y.z+i, buildNumber 포함)
+# - react/node: package.json ("version": "x.y.z")
+# - react-native: iOS Info.plist 또는 Android build.gradle
+# - react-native-expo: app.json (expo.version)
+# - python: pyproject.toml (version = "x.y.z")
+# - basic/기타: version.yml 파일만 사용
+#
+# 연관된 워크플로우:
+# - .github/workflows/PROJECT-VERSION-CONTROL.yaml
+# - .github/workflows/PROJECT-README-VERSION-UPDATE.yaml
+# - .github/workflows/PROJECT-AUTO-CHANGELOG-CONTROL.yaml
+#
+# 주의사항:
+# - project_type은 최초 설정 후 변경하지 마세요
+# - 버전은 항상 높은 버전으로 자동 동기화됩니다
+# ===================================================================
+`;
+
+// 기존 version.yml에서 값 추출 (.sh grep/sed 등가, 주석 라인 오탐 방지).
+export function parseExisting(content) {
+  const text = String(content || "");
+  const line = (re) => {
+    for (const l of text.split("\n")) {
+      if (l.startsWith("#")) continue; // 주석 제외
+      const m = l.match(re);
+      if (m) return m[1];
+    }
+    return null;
+  };
+  // version: "x.y.z" (숫자.숫자.숫자 형태만)
+  const version = line(/^version:\s*["']?([0-9][0-9.]*)["']?/) || "";
+  // version_code: N (양의 정수, 아니면 1)
+  let versionCode = parseInt(line(/^version_code:\s*([0-9]+)/) || "", 10);
+  if (!Number.isInteger(versionCode) || versionCode <= 0) versionCode = 1;
+  // project_types: ["a","b"]
+  const typesRaw = line(/^project_types:\s*(\[[^\]]*\])/);
+  let types = [];
+  if (typesRaw) types = [...typesRaw.matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+  // project_paths 블록: "  type: "path""
+  const paths = new Map();
+  let inPaths = false;
+  for (const l of text.split("\n")) {
+    if (/^project_paths:/.test(l)) { inPaths = true; continue; }
+    if (inPaths) {
+      const m = l.match(/^\s+([a-z-]+):\s*"([^"]*)"/);
+      if (m) paths.set(m[1], m[2]);
+      else if (/^\S/.test(l)) inPaths = false; // 들여쓰기 끝 → 블록 종료
+    }
+  }
+  // template: 블록 내 version
+  let templateVersion = "";
+  let inTemplate = false;
+  for (const l of text.split("\n")) {
+    if (/^\s*template:/.test(l)) { inTemplate = true; continue; }
+    if (inTemplate) {
+      const m = l.match(/^\s*version:\s*"([0-9][0-9.]*)"/);
+      if (m) { templateVersion = m[1]; break; }
+      if (/^\S/.test(l)) break;
+    }
+  }
+  return { version, versionCode, types, paths, templateVersion };
+}
+
+// version.yml 전체 생성 (.sh create_version_yml + save_template_options 신규 케이스 등가).
+// opts: { version, types:[], primaryType?, paths:Map, pathMarkers?:Map, branch, versionCode, now, today, templateOptions? }
+//   now   = "YYYY-MM-DD HH:MM:SS" (UTC) — 결정성 위해 주입
+//   today = "YYYY-MM-DD" (UTC)
+//   pathMarkers = Map<type, markerFilename> (project_paths 주석용)
+//   templateOptions = { templateVersion, includeNexus, includeSecretBackup, optionsDate } (template 블록)
+export function buildVersionYml({ version, types = [], primaryType, paths = new Map(), pathMarkers = new Map(), branch = "main", versionCode = 1, now, today, templateOptions = null, deployValues = new Map() }) {
+  const typesJson = types.length ? `[${types.map((t) => `"${t}"`).join(",")}]` : `["basic"]`;
+  const primary = primaryType || types[0] || "basic";
+
+  let out = HEADER + "\n";
+  out += `version: "${version}"\n`;
+  out += `version_code: ${versionCode}  # app build number\n`;
+  out += `project_types: ${typesJson}   # 멀티타입 배열 — 첫 항목이 primary, 직접 편집 가능\n`;
+  out += `project_type: "${primary}"  # project_types[0] 자동 미러 — 직접 수정 금지 (spring, flutter, next, react, react-native, react-native-expo, node, python, basic)\n`;
+
+  // project_paths 블록. pathMarkers: Map<type, markerFilename> (있으면 "  type: "path"   # path/marker" 주석).
+  if (paths.size) {
+    out += `project_paths:                # 타입별 프로젝트 폴더 (레포 루트 기준 상대경로)\n`;
+    for (const [t, p] of paths) {
+      const marker = pathMarkers.get(t) || "";
+      const pf = p === "." ? marker : (marker ? `${p}/${marker}` : p);
+      out += marker ? `  ${t}: "${p}"   # ${pf}\n` : `  ${t}: "${p}"\n`;
+    }
+  }
+
+  out += `metadata:\n`;
+  out += `  last_updated: "${now}"\n`;
+  out += `  last_updated_by: "template_integrator"\n`;
+  out += `  default_branch: "${branch}"\n`;
+  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", includeNexus = false, includeSecretBackup = false, optionsDate = today } = templateOptions;
+    out += `  template:\n`;
+    out += `    source: "projectops"\n`;
+    out += `    version: "${templateVersion}"\n`;
+    out += `    integrated_date: "${optionsDate}"\n`;
+    out += `    last_update_date: "${optionsDate}"\n`;
+    out += `    options:\n`;
+    out += `      nexus: ${includeNexus}\n`;
+    out += `      secret_backup: ${includeSecretBackup}\n`;
+  }
+  return out;
+}