projectops 3.0.193 → 3.0.195

package/src/core/breaking.js

@@ -0,0 +1,26 @@
+// .sh compare_versions 등가: v 접두 제거, 3자리 숫자 비교, 누락 자리=0
+export function compareVersions(a, b) {
+  const parse = (v) => String(v).replace(/^v/, "").split(".").map((n) => parseInt(n, 10) || 0);
+  const pa = parse(a), pb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] ?? 0, y = pb[i] ?? 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+// breaking-changes.json에서 current < ver <= target 범위 항목 수집.
+// ⚠️ .sh 버그 수정: target은 하드코딩 1.3.14가 아니라 실제 templateVersion을 넘긴다 (D2).
+// _ 로 시작하는 키(메타) 제외. severity critical / 그 외(warning).
+export function collectBreaking(json, current, target) {
+  const critical = [], warnings = [];
+  for (const [ver, entry] of Object.entries(json || {})) {
+    if (ver.startsWith("_")) continue;
+    if (compareVersions(current, ver) < 0 && compareVersions(ver, target) <= 0) {
+      const rec = { version: ver, ...entry };
+      (entry?.severity === "critical" ? critical : warnings).push(rec);
+    }
+  }
+  return { critical, warnings };
+}

package/src/core/copy/coderabbit.js

@@ -0,0 +1,25 @@
+// .coderabbit.yaml 복사 (.sh copy_coderabbit_config 등가, force 경로) — template_integrator.sh 3938~3990.
+// SP2-B는 force/비대화형 경로만 구현. 대화형 덮어쓰기/건너뛰기 메뉴는 SP2-C.
+import { join } from "node:path";
+import { exists, copyFileSync } from "../fsutil.js";
+
+// 반환: 'skip-no-src' | 'copied-new' | 'overwritten-backup' | 'skip-non-tty'
+// opts: { force, tty }  — SP2-B 검증은 force:true 경로.
+export function copyCoderabbit(tempDir, { force = false, tty = false } = {}, targetRoot = ".") {
+  const src = join(tempDir, ".coderabbit.yaml");
+  if (!exists(src)) return "skip-no-src";
+  const dst = join(targetRoot, ".coderabbit.yaml");
+
+  if (exists(dst)) {
+    if (force) {
+      copyFileSync(dst, dst + ".bak"); // 백업 후 덮어쓰기
+      copyFileSync(src, dst);
+      return "overwritten-backup";
+    }
+    if (!tty) return "skip-non-tty"; // 비TTY & !force → 유지
+    // 대화형 메뉴는 SP2-C — 여기서는 force가 아니면 유지
+    return "skip-non-tty";
+  }
+  copyFileSync(src, dst); // 신규
+  return "copied-new";
+}

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/ide/adapter.js

@@ -0,0 +1,36 @@
+// IDE 어댑터 공통 계약 (확장 포인트의 핵심).
+//
+// 새 IDE(에디터/에이전트 CLI)를 지원하려면 이 shape을 만족하는 객체 하나를
+// src/core/ide/adapters/<name>.js 에 만들고 registry.js 배열에 추가하기만 하면 된다.
+// 오케스트레이터(commands/skills.js)는 어댑터의 필드만 알고, 개별 IDE 로직은 전혀 모른다.
+//
+// @typedef {Object} IdeStatus
+//   installed: boolean       설치돼 있는가
+//   version:   string|null   설치 버전(알 수 있으면)
+//   cliMissing: boolean      전용 CLI가 없어 설치 불가한 상태인가 (안내만 가능)
+//   note:      string        상태 표시줄에 덧붙일 짧은 메모(선택)
+//
+// @typedef {Object} IdeAdapter
+//   id:      string   내부 고유키 (예: "claude"). 라우팅·preselect에 사용
+//   label:   string   사람에게 보이는 이름 (예: "Claude Code")
+//   order:   number   상태·메뉴 표시 순서 (작을수록 먼저)
+//   detect(io): IdeStatus                     현재 설치 상태
+//   apply(io, ctx): boolean                   설치 또는 업데이트(멱등). 성공 true
+//   remove(io, ctx): boolean                  제거(미설치면 no-op, true)
+//   manualHint(io): string                    CLI 없을 때 보여줄 수동 설치 명령(선택)
+//
+// io = runner.defaultIo() 또는 테스트 stub: { which, run, home, log }
+// ctx = { templateVersion, sourceSkillsDir } — 버전 표기·Cursor 복사 소스 등 공용 컨텍스트
+//
+// 규칙:
+//  - apply/remove/detect는 예외를 던지지 않는다(내부에서 흡수). 실패는 log + false로 표현.
+//  - CLI 미존재는 에러가 아니라 cliMissing 상태 + manualHint로 안내한다.
+//  - 어댑터는 io를 통해서만 외부와 상호작용한다(직접 spawnSync/console 금지) — 테스트 가능성.
+
+// 어댑터가 최소 계약을 지키는지 개발 중 검증하는 헬퍼(런타임 방어).
+export function assertAdapter(a) {
+  for (const k of ["id", "label", "detect", "apply", "remove"]) {
+    if (a[k] == null) throw new Error(`IDE 어댑터 '${a?.id || "?"}'에 필수 필드 '${k}'가 없습니다`);
+  }
+  return a;
+}