projectops 4.36.4 → 4.38.0

package/src/core/copy/workflows.js

@@ -6,10 +6,30 @@ 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, resolveGlobalTokens } from "../wizard-env.js";
+import { isUnchanged, substituteEnv, resolveGlobalTokens, extractEnvValues } from "../wizard-env.js";
 import { isUserModified, readBaseline, writeBaseline, sha256 } from "../baseline.js";
 import { substituteBranches } from "../branch-sub.js";
 import { saveIncoming, lineDiffCounts } from "../incoming.js";
+import { branchStatus } from "../git-branch.js";
+import { PUBLISH_TARGETS } from "../constants.js";
+
+// on: 블록의 브랜치 필터가 전부 develop 뿐인가 (#810).
+// 개발 브랜치가 없는 레포에 깔면 영영 실행되지 않는 워크플로우를 가린다.
+// workflow_dispatch 외의 다른 이벤트(schedule·issues 등)가 있으면 그것만으로도 돌 수 있으니 false.
+export function onlyTriggersOnDevelop(content) {
+  const m = String(content).match(/^on:\s*\n((?:[ \t]+.*\n|\s*\n)+)/m);
+  if (!m) return false;
+  const block = m[1];
+  const events = [...block.matchAll(/^ {2}([a-z_]+):/gm)].map((x) => x[1]);
+  if (!events.length || events.some((e) => !["push", "pull_request", "workflow_dispatch"].includes(e))) return false;
+  const branches = [];
+  for (const b of block.matchAll(/^\s+branches:\s*\[([^\]]*)\]/gm)) branches.push(...b[1].split(",").map((s) => s.trim().replace(/["']/g, "")).filter(Boolean));
+  for (const b of block.matchAll(/^\s+branches:\s*\n((?:\s+-\s*.*\n)+)/gm)) branches.push(...[...b[1].matchAll(/-\s*["']?([^"'\s#]+)/g)].map((x) => x[1]));
+  // push/pull_request 마다 branches 필터가 있어야 한다 — 필터 없는 push 는 모든 브랜치에서 돈다
+  const filtered = (block.match(/^\s+branches:/gm) || []).length;
+  const needFilter = events.filter((e) => e !== "workflow_dispatch").length;
+  return branches.length > 0 && filtered >= needFilter && branches.every((b) => b === "develop");
+}
 
 // 한 파일에 env 치환을 적용해 대상 파일을 갱신 (.sh configure_workflow_env 등가).
 // values/useDefaults: env 계획(promptEnvPlan) 결과 — 미지정이면 기본값 경로(현행 force 동작).
@@ -90,6 +110,43 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   // values/useDefaults는 치환 경로에서만 의미 (isUnchanged는 내부에서 useDefaults:true 강제 — 가상 비교 무손상)
   const envOptsFor = (type) => ({ type, projectPath: paths.get(type) || ".", repoName, resolvers, values: envValues, useDefaults: envUseDefaults, branches });
 
+  // 설치하지 않을 새 파일 (#810) — 깔 때마다 다시 생기던 것들.
+  //   excluded        : version.yml options.excluded_workflows 에 사용자가 적은 파일
+  //   deleted-by-user : 우리가 깐 기록(baseline)이 있는데 지금 없다 = 사용자가 지웠다 (.bak 은 우리가 치운 것이라 제외)
+  //   no-dev-branch   : 개발 브랜치가 원격에 확실히 없는데 그 브랜치에서만 도는 워크플로우
+  const notInstalled = [];
+  Object.defineProperty(counters, "notInstalled", { value: notInstalled, enumerable: false });
+  const excludedSet = new Set(context.excludedWorkflows || []);
+  const devName = branches.deployBranch;
+  let devMissing = null; // 필요할 때 한 번만 원격을 조회한다
+  const isDevMissing = () => {
+    if (devMissing === null) {
+      const st = devName === branches.defaultBranch ? null : branchStatus(targetRoot, devName);
+      devMissing = !!(st && st.isRepo && !st.local && st.remote === false);
+    }
+    return devMissing;
+  };
+  const skipNew = (srcDir, filename, group) => {
+    const dst = join(workflowsDir, filename);
+    if (existsSync(dst)) return false;
+    let reason = null;
+    if (excludedSet.has(filename)) reason = "excluded";
+    else if (baseline?.files?.[filename] && !existsSync(dst + ".bak")) reason = "deleted-by-user";
+    else if (onlyTriggersOnDevelop(readFileSync(join(srcDir, filename), "utf8")) && isDevMissing()) reason = "no-dev-branch";
+    if (!reason) return false;
+    const info = { filename, reason, incoming: "" };
+    try {
+      // 마음이 바뀌면 cp 한 번으로 되살릴 수 있게 렌더본을 incoming 에 남긴다
+      const rendered = substituteBranches(substituteEnv(readFileSync(join(srcDir, filename), "utf8"),
+        { ...envOptsFor(group.split("/")[0]), useDefaults: true }), branches);
+      info.incoming = saveIncoming(targetRoot, filename, rendered);
+    } catch { /* 안내만 빠진다 */ }
+    notInstalled.push(info);
+    trace?.event("copy", "not-installed", filename, { group, reason });
+    return true;
+  };
+  Object.defineProperty(counters, "skipNew", { value: skipNew, enumerable: false });
+
   // 사용자 수정본을 유지할 때 새 템플릿 사본을 incoming에 남긴다 (#654).
   // 실패는 경고 한 줄로 흡수한다 — 병합 안내 때문에 복사 전체가 죽으면 안 된다.
   const onSkip = (srcDir, filename, type) => {
@@ -133,6 +190,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
         continue;
       }
       // 사용자가 손댄 적 없고 템플릿만 바뀐 파일 — 물어볼 것 없이 최신으로 올린다(종전과 동일).
+      if (commonClass.newFiles.includes(filename) && skipNew(commonDir, filename, "common")) continue;
       if (commonClass.newFiles.includes(filename) || commonClass.upstream.includes(filename)) {
         copyFileSync(join(commonDir, filename), join(workflowsDir, filename));
         counters.copied++;
@@ -179,6 +237,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
         trace?.event("copy", "skipped-unchanged", filename, { group: "common-deploy" });
         continue;
       }
+      if (skipNew(commonDeployDir, filename, "common-deploy")) continue;
       const backedUp = existsSync(dst);
       if (backedUp) renameSync(dst, dst + ".bak");
       copyFileSync(src, dst);
@@ -207,6 +266,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
         trace?.event("copy", "skipped-unchanged", filename, { group: groupName });
         continue;
       }
+      if (skipNew(prSummaryDir, filename, groupName)) continue;
       const backedUp = existsSync(dst);
       if (backedUp) renameSync(dst, dst + ".bak");
       copyFileSync(src, dst);
@@ -225,6 +285,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
     for (const filename of listYamlFiles(secretDir)) {
       const dst = join(workflowsDir, filename);
       if (existsSync(dst)) continue; // 이미 존재하면 스킵
+      if (skipNew(secretDir, filename, "secret-backup")) continue;
       copyFileSync(join(secretDir, filename), dst);
       // PROJECT_NAME 이 고정값이면 모든 프로젝트가 서버의 같은 폴더에 Secret 을 덮어쓴다 (#729) —
       // 다른 배포 워크플로처럼 레포 이름으로 채운다. 이름을 알 수 없으면 기존 기본값을 쓴다.
@@ -370,22 +431,31 @@ export async function copyWorkflowsInteractive(context, tempDir, targetRoot = ".
   return copyWorkflows(context, tempDir, targetRoot, { decisions });
 }
 
-const PUBLISH_TARGETS = ["nexus", "npm", "github-packages"];
 
 function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters) {
   const { deployTarget = "docker-ssh", publishTargets = [], force = false, paths = new Map(), repoName = "", resolvers = {}, envOptsFor, collectAsks = null, decisions = new Map(), trace = null, baseline = null } = ctx;
   const typeDir = join(projectTypesDir, type);
   const envOpts = envOptsFor(type);
   let unchangedNames = [];
+  // upstream 갱신 전 설치본의 env 실값 (#810 조사 중 발견). 템플릿만 바뀐 파일을 새로 깔 때
+  // 기본값으로 다시 치환해, 사용자가 고른 값(JAVA_VERSION 17 등)이 조용히 21로 돌아갔다.
+  const carried = new Map(); // Map<filename, Map<key,value>>
+  const upstreamCopy = (srcDir, f, group) => {
+    const dst = join(workflowsDir, f);
+    try { carried.set(f, extractEnvValues(readFileSync(dst, "utf8"))); } catch { /* 읽기 실패 — 기본값으로 */ }
+    copyFileSync(join(srcDir, f), dst);
+    counters.copied++; counters.copiedFiles.push(f);
+    trace?.event("copy", "upstream-updated", f, { group, reason: "baseline-match", carried: carried.get(f)?.size ?? 0 });
+  };
 
   // 타입별 워크플로우 (직하위)
   if (exists(typeDir)) {
     const { newFiles, unchanged, changed, upstream } = classify(typeDir, workflowsDir, envOpts, baseline);
     unchangedNames = unchanged.slice();
     for (const f of unchanged) { counters.skipped++; trace?.event("copy", "skipped-unchanged", f, { group: type }); }
-    for (const f of newFiles) { copyFileSync(join(typeDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "copied", f, { group: type }); }
+    for (const f of newFiles) { if (counters.skipNew(typeDir, f, type)) continue; copyFileSync(join(typeDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "copied", f, { group: type }); }
     // upstream(#557): 사용자가 손대지 않았고 템플릿만 바뀐 파일 — 물어볼 것 없이 최신으로 올린다.
-    for (const f of upstream) { copyFileSync(join(typeDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "upstream-updated", f, { group: type, reason: "baseline-match" }); }
+    for (const f of upstream) upstreamCopy(typeDir, f, type);
     // changed: 결정 Map에 따라 처리 (미지정=skip → 현행 force 동작과 동일)
     for (const f of changed) applyDecision(decisions.get(f), typeDir, workflowsDir, f, counters, trace, type);
   }
@@ -395,8 +465,8 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
   if (exists(serverDeployDir) && (deployTarget || "docker-ssh") === "docker-ssh") {
     const { newFiles, unchanged, changed, upstream } = classify(serverDeployDir, workflowsDir, envOpts, baseline);
     for (const f of unchanged) { counters.skipped++; trace?.event("copy", "skipped-unchanged", f, { group: `${type}/server-deploy` }); }
-    for (const f of newFiles) { copyFileSync(join(serverDeployDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "copied", f, { group: `${type}/server-deploy` }); }
-    for (const f of upstream) { copyFileSync(join(serverDeployDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "upstream-updated", f, { group: `${type}/server-deploy`, reason: "baseline-match" }); }
+    for (const f of newFiles) { if (counters.skipNew(serverDeployDir, f, `${type}/server-deploy`)) continue; copyFileSync(join(serverDeployDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "copied", f, { group: `${type}/server-deploy` }); }
+    for (const f of upstream) upstreamCopy(serverDeployDir, f, `${type}/server-deploy`);
     for (const f of changed) applyDecision(decisions.get(f), serverDeployDir, workflowsDir, f, counters, trace, type);
   }
 
@@ -414,6 +484,7 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
         trace?.event("copy", "skipped-unchanged", filename, { group: `${type}/publish/${target}` });
         continue;
       }
+      if (counters.skipNew(pubDir, filename, `${type}/publish/${target}`)) continue;
       const backedUp = existsSync(dst);
       if (backedUp) renameSync(dst, dst + ".bak");
       copyFileSync(src, dst);
@@ -432,7 +503,14 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
       const target = join(workflowsDir, filename);
       if (!existsSync(target)) continue;            // 건너뛴 파일 제외
       if (unchangedNames.includes(filename)) continue; // unchanged 제외
-      configureEnv(target, filename, { ...envOpts, collectAsks, trace }); // env 계획 values/useDefaults 포함
+      const prev = carried.get(filename);
+      if (prev && prev.size) {
+        // 이월값 위에 이번 실행에서 명시로 고른 값을 덮는다 (명시 선택이 이긴다)
+        const values = new Map([...prev, ...(envOpts.useDefaults ? [] : envOpts.values)]);
+        configureEnv(target, filename, { ...envOpts, values, useDefaults: false, collectAsks, trace });
+      } else {
+        configureEnv(target, filename, { ...envOpts, collectAsks, trace }); // env 계획 values/useDefaults 포함
+      }
     }
   }
 }

package/src/core/exclusions.js

@@ -5,10 +5,12 @@
 export const DOCS_TO_REMOVE = [
   "CONTRIBUTING.md",
   "SECURITY.md",
+  "CODE_OF_CONDUCT.md",
   "ARCHITECTURE.md",
   "CLAUDE.md",
   "AGENTS.md",
   "GEMINI.md",
+  "llms.txt",
   "gemini-extension.json",
   // 릴리스마다 changelog-deploy 파이프라인이 재생성하는 이 레포 전용 작업 산출물.
   // 사용자 프로젝트에는 의미가 없으므로 복사하지 않는다.

package/src/core/fsutil.js

@@ -20,9 +20,9 @@ export function copyFileSync(src, dst) {
 }
 
 // 디렉토리 재귀 복사 (내용을 dst 하위로)
-export function copyDirSync(src, dst) {
+export function copyDirSync(src, dst, { filter } = {}) {
   mkdirSync(dst, { recursive: true });
-  cpSync(src, dst, { recursive: true });
+  cpSync(src, dst, { recursive: true, ...(filter ? { filter } : {}) });
 }
 
 // 파일/폴더 삭제 (없어도 무해)

package/src/core/migrations/index.js

@@ -48,8 +48,9 @@ export function applySafeMigrations(targetRoot, entries) {
 // 마법사 배선 진입점.
 //   askYesNo - async(msg, defaultYes)→bool. null이면 비대화형(--force): safe 자동 적용
 //   log      - 한 줄 출력 함수 (기본 console.log)
+//   removeLegacy - true면 confirm 티어(구세대 배포 워크플로우)도 .bak 무해화 (--remove-legacy, #809)
 // 반환: { applied: [결과], confirmPending: [entry], askPending: [entry] }
-export async function runMigrations({ targetRoot = ".", askYesNo = null, log = console.log } = {}) {
+export async function runMigrations({ targetRoot = ".", askYesNo = null, log = console.log, removeLegacy = false } = {}) {
   const { safe, confirm, ask } = detectMigrations(targetRoot);
   if (safe.length === 0 && confirm.length === 0 && ask.length === 0) {
     return { applied: [], confirmPending: [], askPending: [] };
@@ -110,7 +111,21 @@ export async function runMigrations({ targetRoot = ".", askYesNo = null, log = c
       const arrow = e.replacedBy ? t("migrate.confirm.newer", { name: e.replacedBy }) : "";
       log(`   • ${e.file}${arrow}: ${reasonOf(e)}`);
     }
-    log(t("migrate.confirm.hint"));
+    // 신·구 세대가 함께 돌면 같은 이벤트에 두 번 반응한다 (#809 — PR 닫힘마다 PREVIEW 두 벌).
+    // 현역 배포일 수 있어 기본은 손대지 않되, 명시 플래그나 대화형 확인이 있으면 .bak 으로 치운다(복원 가능).
+    const yes = removeLegacy
+      ? true
+      : askYesNo ? await askYesNo(t("migrate.confirm.ask", { n: confirm.length }), false) : false;
+    if (yes === true) {
+      const results = applySafeMigrations(targetRoot, confirm);
+      applied = applied.concat(results);
+      const failed = results.filter((r) => r.action === "error");
+      log(t("migrate.confirm.done", { n: results.length - failed.length }));
+      for (const f of failed) log(`   ⚠️ ${f.from}: ${f.error}`);
+      const failedIds = new Set(failed.map((f) => f.id));
+      return { applied, confirmPending: confirm.filter((e) => failedIds.has(e.id)), askPending };
+    }
+    log(t(askYesNo ? "migrate.confirm.hint" : "migrate.confirm.hintForce"));
   }
 
   return { applied, confirmPending: confirm, askPending };

package/src/core/options-ask.js

@@ -13,6 +13,7 @@ import { PATHS } from "./paths.js";
 import { t as msg } from "../i18n/index.js";
 import { parseTemplateOptions, inferIntent } from "./version-yml.js";
 import { branchStatus, createBranch, pushBranch } from "./git-branch.js";
+import { DEPLOY_TARGETS, PUBLISH_TARGETS, CHANGELOG_PROVIDERS } from "./constants.js";
 
 // 개발(배포) 브랜치 존재 확인 + 생성 제안 (#477) — 대화형 전용.
 // 로컬에 없고 원격에도 없(거나 불명이)면 기본 브랜치에서 생성을 제안하고, 생성 후 push 여부도 묻는다.
@@ -55,8 +56,8 @@ export async function ensureDeployBranch({ targetRoot = ".", deployBranch = "",
 // 재노출 — 파서 본체는 version-yml.js에 있다 (순환 import 방지: options-ask → version-yml 방향만 허용)
 export { parseTemplateOptions };
 
-export const DEPLOY_TARGETS = ["docker-ssh", "vercel", "none"];
-export const PUBLISH_TARGETS = ["nexus", "npm", "github-packages"];
+// 값 목록은 core/constants.js 가 정본이다. 기존 import 경로를 깨지 않도록 다시 내보낸다.
+export { DEPLOY_TARGETS, PUBLISH_TARGETS, CHANGELOG_PROVIDERS };
 
 // #498 — 타입별 적용 가능 deploy/publish 타겟 선언.
 // 빈 배열 = 그 축이 개념상 성립하지 않는 타입. 모바일 앱(flutter/react-native/expo)은 스토어 배포
@@ -95,9 +96,9 @@ export function applicableTargets(types = []) {
 }
 // changelog 생성기 provider (#455, #566에서 재정비).
 // 기본값은 commit — 외부 의존이 없어 어떤 환경에서도 결과가 나온다. AI를 쓰려면
-// MODEL_API_KEY를 등록하면 사다리가 자동으로 집어 쓴다(마법사는 묻지 않는다).
+// 서비스별 키(GEMINI_API_KEY 등)를 등록하면 사다리가 자동으로 집어 쓴다(마법사는 묻지 않는다).
+// MODEL_API_KEY 는 구 이름이라 하위호환으로만 읽는다.
 // github-ai는 GitHub Models 종료(2026-07-30)로 제외됐다.
-export const CHANGELOG_PROVIDERS = ["copilot", "coderabbit", "openai", "gemini", "claude", "groq", "mistral", "ollama", "commit"];
 
 // 더 이상 동작하지 않는 저장값을 살아있는 값으로 옮긴다 (#566).
 // 기존 저장소가 업데이트만 돌려도 죽은 설정에서 벗어나게 하는 유일한 경로다.

package/src/core/options-schema.js

@@ -0,0 +1,150 @@
+// projectops 옵션 정본 (AI agent·사람·문서가 같은 표를 본다).
+//
+// 왜 필요한가: 옵션 설명이 문서 6곳(NPX-WIZARD, VERSION-CONTROL, ISSUE-AUTOMATION ...)에 흩어져 있어
+// agent가 "이 옵션이 있나, 기본값이 뭔가"를 확인하려면 문서를 뒤져야 했다. 이제 한 호출로 읽는다:
+//   npx projectops --mode options --json
+//
+// 이 표는 손으로 쓰되, test/options-schema.test.js 가 실제 코드와 대조한다.
+//   - args.js 의 모든 CLI 플래그가 flags 에 있어야 한다
+//   - parseTemplateOptions 가 읽는 모든 키가 versionYml 에 있어야 한다
+// 새 플래그·옵션을 추가하고 여기에 안 쓰면 테스트가 실패한다.
+//
+// 설명은 영문이다 — 기계가 읽는 표이고, 화면 언어(i18n)와 무관하게 같아야 한다.
+
+import { DEPLOY_TARGETS, PUBLISH_TARGETS, INTENT_VALUES, LABEL_STYLES, CHANGELOG_PROVIDERS } from "./constants.js";
+import { REPO_LANGUAGES } from "./repo-language.js";
+import { VALID_TYPES } from "../context.js";
+import { SUPPORTED_LANGS } from "../i18n/index.js";
+
+export const SCHEMA_VERSION = 1;
+
+export const MODES = [
+  { name: "interactive", description: "Default. Asks questions in the terminal. Do not use from an agent or CI." },
+  { name: "full", description: "Install everything: version.yml, workflows, scripts, templates, setup guide." },
+  { name: "version", description: "Only version.yml, README version section and version scripts." },
+  { name: "workflows", description: "Only GitHub Actions workflows (+ scripts, config, util). Existing version.yml is kept." },
+  { name: "issues", description: "Only issue and discussion templates." },
+  { name: "skills", description: "Install or update agent skills for supported IDEs." },
+  { name: "doctor", description: "Read-only diagnosis of the install and repository settings. Safe to run any time." },
+  { name: "options", description: "Print this option table (add --json for machine-readable output). Read-only, no network." },
+];
+
+// 프로젝트 타입은 context.js 의 VALID_TYPES 와 같아야 한다 (테스트가 대조).
+export const FLAGS = [
+  { flag: "--mode", alias: "-m", value: "MODE", values: MODES.map((m) => m.name), default: "interactive",
+    description: "What to do. Agents and CI should always pass an explicit non-interactive mode together with --force." },
+  { flag: "--type", alias: "-t", value: "CSV", default: "auto-detected",
+    description: "Project types, comma separated. The first one is the primary type.",
+    values: [...VALID_TYPES] },
+  { flag: "--project-version", value: "VERSION", default: "auto-detected",
+    description: "Initial version of the target project (x.y.z)." },
+  { flag: "--paths", value: "type=path,...", default: "repo root",
+    description: "Per-type project folders for monorepos, e.g. flutter=app,react=client.", versionYml: "project_paths" },
+  { flag: "--intent", value: "KIND", values: [...INTENT_VALUES], default: "inferred from --deploy/--publish",
+    description: "Project kind. Decides whether deploy and publish questions are asked.", versionYml: "metadata.template.options.intent" },
+  { flag: "--deploy", value: "TARGET", values: [...DEPLOY_TARGETS], default: "docker-ssh",
+    description: "Where the app is deployed. Pick one.", versionYml: "metadata.template.options.deploy" },
+  { flag: "--publish", value: "CSV", values: [...PUBLISH_TARGETS], default: "none",
+    description: "Registries a library is published to. Several allowed.", versionYml: "metadata.template.options.publish" },
+  { flag: "--deploy-branch", value: "NAME", default: "develop",
+    description: "Development branch: the head of the release PR. Not the repository default branch.", versionYml: "metadata.deploy_branch" },
+  { flag: "--language", value: "LANG", values: [...REPO_LANGUAGES], default: "en for new installs, ko for existing installs",
+    description: "Language of issue/PR templates and bot messages written into the repo.", versionYml: "metadata.template.options.language" },
+  { flag: "--label-style", value: "STYLE", values: [...LABEL_STYLES], default: "en for new installs, ko for existing installs",
+    description: "Status label names: en = 'status: todo', ko = legacy Korean names.", versionYml: "metadata.template.options.label_style" },
+  { flag: "--secret-backup", negation: "--no-secret-backup",
+    description: "Include / exclude the workflow that uploads GitHub Secrets to a server over SSH.", default: "excluded",
+    versionYml: "metadata.template.options.secret_backup" },
+  { flag: "--ai-summary", negation: "--no-ai-summary",
+    description: "Include / exclude the workflow that comments an AI summary on work PRs.", default: "included",
+    versionYml: "metadata.template.options.code_review.ai_summary" },
+  { flag: "--projects-sync", negation: "--no-projects-sync",
+    description: "Include / exclude the GitHub Projects status sync workflow. Needs a PAT secret and PROJECT_URL variable.",
+    default: "excluded for new installs; kept if already installed", versionYml: "metadata.template.options.projects_sync" },
+  { flag: "--remove-legacy",
+    description: "Rename retired old-generation workflows to .bak. Without it they are only listed in the summary and in doctor.", default: "off" },
+  { flag: "--force", alias: "-y", aliases: ["-y", "--yes"], description: "Skip every confirmation and use non-interactive defaults. Required for agents and CI.", default: "off" },
+  { flag: "--lang", value: "LANG", values: [...SUPPORTED_LANGS], default: "system language; pinned to en in CI and with --force",
+    description: "Language of the CLI screen. Not the language written into the repo (that is --language)." },
+  { flag: "--json", description: "With --mode options: print machine-readable JSON instead of a table.", default: "off" },
+  { flag: "--version", alias: "-v", description: "Print the projectops package version and exit." },
+  { flag: "--help", alias: "-h", description: "Print the human-readable help and exit." },
+  // 지원 종료 예정 — 새 설정에는 쓰지 않는다
+  { flag: "--nexus", negation: "--no-nexus", deprecated: "Use --publish nexus. Also implies --deploy none." },
+  { flag: "--npm-publish", negation: "--no-npm-publish", deprecated: "Use --publish npm." },
+];
+
+// version.yml 의 키. path 는 파일 안의 위치, parserKey 는 parseTemplateOptions 가 돌려주는 이름.
+export const VERSION_YML = [
+  { path: "version", type: "string", description: "Project version (x.y.z). The single source of truth; workflows sync it into build files.", edit: "workflow-managed" },
+  { path: "version_code", type: "integer", description: "App build number. +1 on every release. Android release only; iOS and test builds use build_number.py.", edit: "workflow-managed" },
+  { path: "project_types", type: "string[]", description: "Project types; the first is primary. Do not change after setup.", edit: "wizard" },
+  { path: "project_paths", type: "map", description: "Per-type project folder relative to the repo root (monorepo).", edit: "wizard (--paths)" },
+  { path: "metadata.default_branch", type: "string", default: "main", description: "Repository default (production) branch. Pushes here deploy.", edit: "wizard" },
+  { path: "metadata.deploy_branch", parserKey: "deployBranch", type: "string", default: "develop",
+    description: "Development branch: head of the release PR. Despite the name it is NOT where deploys run.", edit: "wizard (--deploy-branch)" },
+  { path: "metadata.template.options.intent", parserKey: "intent", type: "enum", values: [...INTENT_VALUES],
+    description: "Project kind; derives the deploy and publish questions.", edit: "wizard (--intent)" },
+  { path: "metadata.template.options.deploy", parserKey: "deploy", type: "enum", values: [...DEPLOY_TARGETS], default: "docker-ssh",
+    description: "Where the app is deployed.", edit: "wizard (--deploy)" },
+  { path: "metadata.template.options.publish", parserKey: "publish", type: "enum[]", values: [...PUBLISH_TARGETS], default: [],
+    description: "Library registries.", edit: "wizard (--publish)" },
+  { path: "metadata.template.options.secret_backup", parserKey: "secretBackup", type: "boolean", default: false,
+    description: "Secret-to-server upload workflow installed.", edit: "wizard (--secret-backup)" },
+  { path: "metadata.template.options.semver_auto", parserKey: "semverAuto", type: "boolean",
+    default: true,
+    description: "Decide the release bump from commit titles: 'type!:' = major, 'feat:' = minor, anything else = patch. Applies both to the release PR and to direct pushes to the default branch.",
+    edit: "by hand" },
+  { path: "metadata.template.options.close_on_release", parserKey: "closeOnRelease", type: "boolean", default: "true for new installs; missing for existing installs",
+    description: "A release merge closes issues that carry the done label and are referenced by a release commit.", edit: "by hand" },
+  { path: "metadata.template.options.language", parserKey: "language", type: "enum", values: [...REPO_LANGUAGES], description: "Issue/PR template and bot message language.", edit: "wizard (--language)" },
+  { path: "metadata.template.options.label_style", parserKey: "labelStyle", type: "enum", values: [...LABEL_STYLES], description: "Status label names.", edit: "wizard (--label-style)" },
+  { path: "metadata.template.options.projects_sync", parserKey: "projectsSync", type: "boolean", description: "Projects status sync workflow installed.", edit: "wizard (--projects-sync)" },
+  { path: "metadata.template.options.app_release", parserKey: "appRelease", type: "boolean",
+    description: "Releases go through App Store / Play Store review. Release notes get a review warning banner. Never auto-enabled.", edit: "by hand" },
+  { path: "metadata.template.options.excluded_workflows", parserKey: "excludedWorkflows", type: "string[]",
+    description: "Workflow file names the update must never install. Deleted files are also not restored; a copy is kept in .github/.projectops/incoming/.",
+    edit: "by hand" },
+  { path: "metadata.template.options.code_review.coderabbit", parserKey: "codeReviewCoderabbit", type: "boolean", description: "CodeRabbit config installed.", edit: "wizard" },
+  { path: "metadata.template.options.code_review.ai_summary", parserKey: "aiPrSummary", type: "boolean", default: true, description: "AI PR summary workflow installed.", edit: "wizard (--ai-summary)" },
+  { path: "metadata.template.options.changelog.provider", parserKey: "changelogProvider", type: "enum",
+    values: [...CHANGELOG_PROVIDERS], default: "commit",
+    description: "Release note generator. 'commit' is free and always works; AI keys are picked up automatically when registered as secrets.", edit: "by hand" },
+  { path: "metadata.template.options.changelog.base_url", parserKey: "changelogBaseUrl", type: "string", description: "Only for provider ollama.", edit: "by hand" },
+];
+
+export function buildSchema(packageVersion = "") {
+  return {
+    tool: "projectops",
+    packageVersion,
+    schemaVersion: SCHEMA_VERSION,
+    usage: "npx projectops --mode <mode> [--type csv] [--force] ...   (agents: always pass --force and an explicit --mode)",
+    modes: MODES,
+    flags: FLAGS,
+    versionYml: VERSION_YML,
+    related: {
+      diagnose: "npx projectops --mode doctor",
+      optionsJson: "npx projectops --mode options --json",
+      docs: "https://cassiiopeia.github.io/projectops/",
+    },
+  };
+}
+
+// 사람이 읽는 표 — JSON 이 아닐 때 출력한다.
+export function renderText(schema) {
+  const lines = [`projectops ${schema.packageVersion} — options (schema v${schema.schemaVersion})`, "", schema.usage, "", "MODES"];
+  for (const m of schema.modes) lines.push(`  ${m.name.padEnd(12)} ${m.description}`);
+  lines.push("", "FLAGS");
+  for (const f of schema.flags) {
+    const name = [...(f.aliases ?? [f.alias]), f.flag + (f.value ? ` ${f.value}` : ""), f.negation].filter(Boolean).join(", ");
+    const desc = f.deprecated ? `(deprecated) ${f.deprecated}` : f.description;
+    const extra = [f.values ? `values: ${f.values.join("|")}` : "", f.default !== undefined ? `default: ${f.default}` : ""].filter(Boolean).join("; ");
+    lines.push(`  ${name}`, `      ${desc}${extra ? `  [${extra}]` : ""}`);
+  }
+  lines.push("", "VERSION.YML KEYS");
+  for (const k of schema.versionYml) {
+    const extra = [k.type, k.values ? k.values.join("|") : "", k.default !== undefined ? `default: ${JSON.stringify(k.default)}` : ""].filter(Boolean).join("; ");
+    lines.push(`  ${k.path}  [${extra}]`, `      ${k.description}`);
+  }
+  return lines.join("\n");
+}