project-auto-wizard 0.13.3 → 0.14.0

package/src/core/baseline.js

@@ -1,19 +1,19 @@
-// 설치 시점 baseline — 업데이트에서 "누가 바꿨는지"를 가르는 기준점.
+// Install-time baseline - the reference point that tells an update "who changed this".
 //
-// 왜 필요한가: isUnchanged()는 payload(theirs)와 설치본(ours)을 2-way로 비교한다.
-// base가 없으니 업스트림이 한 글자만 고쳐도 사용자가 손대지 않은 파일이 changed로 떨어지고,
-// 결국 "전부 skip(업데이트 못 받음)" 아니면 "전부 backup(사용자 수정 전멸)" 둘 중 하나만
-// 고를 수 있게 된다.
+// Why it is needed: isUnchanged() compares the payload (theirs) and the installed copy (ours) 2-way.
+// Without a base, upstream changing a single character drops a file the user never touched into
+// "changed", so the only choices are "skip everything (no updates)" or "back up everything
+// (all user edits lost)".
 //
-// 파일 사본이 아니라 해시만 남긴다 — 분류가 목적이지 자동 병합이 목적이 아니다.
+// Only hashes are kept, not file copies - the goal is classification, not automatic merging.
 //
-// 해시를 두 개 두는 이유: env 치환으로 사용자 값이 들어간 파일은
-// 디스크 내용과 "기본값으로 렌더한 결과"가 애초에 다르다. 하나로는 두 질문에 동시에 답할 수 없다.
-//   - installed : 설치 시점 우리가 디스크에 쓴 내용     → "사용자가 그 뒤에 손댔는가"
-//   - rendered  : 그 시점 payload를 기본값 치환한 결과  → "업스트림이 그 뒤에 바뀌었는가"
+// Why two hashes: for files with user values substituted from env, the disk content and the
+// "payload rendered with defaults" differ from the start, so one hash cannot answer both questions.
+//   - installed : what we wrote to disk at install time        -> "did the user touch it since"
+//   - rendered  : the payload rendered with defaults at that time -> "did upstream change it since"
 //
-// installed는 우리가 실제로 쓴 파일에만 채운다. 사용자 수정본을 installed로 기록하면
-// "우리가 쓴 것"이라고 거짓말하는 셈이고, 다음 업데이트에서 그 파일이 조용히 덮인다.
+// installed is filled only for files we actually wrote. Recording a user-edited file as installed
+// would claim "we wrote this", and the next update would silently overwrite it.
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
@@ -26,14 +26,14 @@ export function sha256(text) {
   return "sha256:" + createHash("sha256").update(String(text), "utf8").digest("hex");
 }
 
-// Flutter 앱 파일(Fastfile·ExportOptions.plist) 해시 — 체크아웃 줄바꿈(autocrlf)만 달라진 파일을
-// "사용자가 수정했다"로 보지 않도록 LF로 맞춘 뒤 해시한다.
+// Hash of Flutter app files (Fastfile, ExportOptions.plist) - normalized to LF first so a file that
+// differs only by checkout line endings (autocrlf) is not treated as "modified by the user".
 export function appFileHash(text) {
   return sha256(String(text).replace(/\r\n/g, "\n"));
 }
 
-// 없거나 깨졌으면 null — 호출부는 "base 미상"으로 폴백한다(조용히 빈 baseline을 쓰지 않는다.
-// 빈 baseline은 "기록이 없다"가 아니라 "전부 삭제됐다"로 오해될 수 있다).
+// null when missing or corrupt - callers fall back to "base unknown" (we never silently use an empty
+// baseline, which could be misread as "everything was deleted" rather than "no record").
 export function readBaseline(targetRoot = ".") {
   const p = join(targetRoot, BASELINE_PATH);
   if (!existsSync(p)) return null;
@@ -42,27 +42,27 @@ export function readBaseline(targetRoot = ".") {
     if (!data || typeof data !== "object" || typeof data.files !== "object" || data.files === null) return null;
     return data;
   } catch {
-    return null; // 손상된 baseline은 없는 것으로 취급 — 업데이트를 막지 않는다
+    return null; // A corrupt baseline is treated as missing - it must not block the update
   }
 }
 
 // entries: Map<filename, {installed?:string|null, rendered?:string|null}>
-// appFiles: Map<레포 기준 상대경로, appFileHash> — 이번에 새로 만든 Flutter 앱 파일. 완전 삭제가
-//   "마법사가 만들었고 사용자가 손대지 않은 파일"만 지우는 근거다. files는 워크플로우 파일명 키라 섞지 않는다.
-// 기존 baseline은 병합 대상이다 — 이번 실행에서 건드리지 않은 파일의 기준점을 잃지 않는다.
+// appFiles: Map<repo-relative path, appFileHash> - Flutter app files newly created this run. It is what lets a
+//   full removal delete only "files the wizard created and the user did not touch". files is keyed by workflow filename, so they are not mixed.
+// The existing baseline is merged in - files not touched this run keep their reference point.
 export function writeBaseline(targetRoot, { templateVersion, installedAt, entries, previous = null, appFiles = new Map() }) {
   const files = { ...(previous?.files || {}) };
   for (const [filename, entry] of entries) {
     const prev = files[filename] || {};
     files[filename] = {
-      // installed는 이번에 실제로 쓴 경우에만 갱신. 유지(skip)한 파일은 예전 기준점을 지킨다.
+      // installed is updated only when actually written this run. Files kept (skipped) retain the old reference point.
       installed: entry.installed ?? prev.installed ?? null,
-      // rendered가 없으면(충돌로 업스트림 변경을 받지 않은 파일) 예전 기준점을 지킨다.
+      // Without rendered (a file that did not take the upstream change due to a conflict) the old reference point is kept.
       rendered: entry.rendered ?? prev.rendered ?? null,
     };
   }
   const apps = { ...(previous?.appFiles || {}), ...Object.fromEntries(appFiles) };
-  // 기준점이 하나도 바뀌지 않은 재실행은 설치 시각도 그대로 둔다 — 매 실행마다 파일이 바뀌면 멱등이 아니다.
+  // A re-run that changes no reference point keeps the install time too - a file that changes on every run is not idempotent.
   const unchanged = previous && previous.templateVersion === (templateVersion || "unknown")
     && JSON.stringify(previous.files) === JSON.stringify(files)
     && JSON.stringify(previous.appFiles || {}) === JSON.stringify(apps);
@@ -76,14 +76,14 @@ export function writeBaseline(targetRoot, { templateVersion, installedAt, entrie
   return out;
 }
 
-// baseline에는 있는데 디스크에 없는 파일 = 사용자가 지운 것.
-// 별도의 삭제 이력 파일이 필요 없다는 것이 이 설계의 부산물이다.
-// candidates: payload가 이번에 설치하려는 파일명 목록 (그 밖의 baseline 항목은 관심 없다)
+// In the baseline but missing on disk = deleted by the user.
+// A side benefit of this design is that no separate deletion-history file is needed.
+// candidates: filenames the payload intends to install this run (other baseline entries are ignored)
 export function detectRemoved(baseline, candidates, workflowsDir) {
   if (!baseline) return [];
   const removed = [];
   for (const filename of candidates) {
-    if (!baseline.files[filename]) continue;      // 우리가 설치한 적 없는 파일 — 판단 근거 없음
+    if (!baseline.files[filename]) continue;      // A file we never installed - no basis for a judgement
     if (existsSync(join(workflowsDir, filename))) continue;
     removed.push(filename);
   }

package/src/core/branches.js

@@ -1,10 +1,11 @@
-// 브랜치 구성 — main/develop 브랜치와 pr-flow·trunk-based 모드.
-// on: push: branches: 는 YAML 정적 값 — 마법사가 릴리스/개발 브랜치를 물어(또는 플래그로 받아)
-// {{MAIN_BRANCH}}/{{DEVELOP_BRANCH}} 플레이스홀더를 치환한다 (치환 자체는 branding.js).
-// main === develop 이면 trunk-based 모드 → RELEASE-PUBLISH 단독 설치.
+// Branch configuration: main/develop branches and the pr-flow / trunk-based modes.
+// on: push: branches: is a static YAML value, so the wizard asks for (or takes via flags) the release/develop
+// branches and substitutes the {{MAIN_BRANCH}}/{{DEVELOP_BRANCH}} placeholders (the substitution itself lives in branding.js).
+// When main === develop it is trunk-based mode, and RELEASE-PUBLISH is installed alone.
 import { execFile } from "node:child_process";
+import { t } from "../i18n/index.js";
 
-// 기본 exec — git 명령 실행. 반환 {code, stdout, stderr}. 테스트는 mock 주입.
+// Default exec: runs a git command. Returns {code, stdout, stderr}. Tests inject a mock.
 export function defaultExec(cmd, args, { cwd } = {}) {
   return new Promise((resolve) => {
     execFile(cmd, args, { cwd, windowsHide: true }, (err, stdout, stderr) => {
@@ -13,22 +14,23 @@ export function defaultExec(cmd, args, { cwd } = {}) {
   });
 }
 
-// 감지: 로컬 git에서 원격 브랜치 목록 (네트워크 없이 — 로컬이 아는 origin/* 기준).
-// git이 없거나 레포가 아니면 빈 목록 (질문 기본값 경로로 폴백).
+// Detection: remote branch list from local git (no network, based on the origin/* refs local knows).
+// Empty list when git is missing or this is not a repo (falls back to the prompt-default path).
 export async function detectRemoteBranches(cwd, exec = defaultExec) {
   const r = await exec("git", ["branch", "-r", "--format=%(refname:short)"], { cwd });
   if (r.code !== 0) return [];
   return r.stdout
     .split(/\r?\n/)
     .map((s) => s.trim())
-    .filter((s) => s && !s.includes("->")) // "origin/HEAD -> origin/main" 제외
+    .filter((s) => s && !s.includes("->")) // exclude "origin/HEAD -> origin/main"
     .map((s) => s.replace(/^origin\//, ""))
     .filter((s, i, a) => a.indexOf(s) === i);
 }
 
-// 브랜치 이름 검증 — git check-ref-format --branch 규칙에 더해, 워크플로우 YAML·셸 명령에 그대로
-// 치환되는 값이라 공백·괄호·따옴표 같은 셸 특수문자도 거부한다. 빈 원격이 돌려주는 "(unknown)" 같은
-// 감지 실패 값이나 공백만 입력한 값이 트리거에 기록되면 워크플로우가 영영 돌지 않는다.
+// Branch name validation: on top of the git check-ref-format --branch rules, shell special characters such as
+// whitespace, parentheses and quotes are rejected because the value is substituted verbatim into workflow YAML and
+// shell commands. If a detection-failure value like "(unknown)" from an empty remote, or a whitespace-only input,
+// were written into the trigger, the workflow would never run.
 export function isValidBranchName(name) {
   if (typeof name !== "string" || name === "") return false;
   if (/[\s~^:?*[\\\x00-\x1f\x7f()"'`$;&|<>!{}]/.test(name)) return false;
@@ -38,23 +40,23 @@ export function isValidBranchName(name) {
   return !name.split("/").some((part) => part.startsWith("."));
 }
 
-// 원격에 브랜치가 하나도 없거나(빈 원격·origin 없음) develop 생성을 건너뛴 경우의 안내.
-// develop이 없으면 pr-flow 워크플로우가 트리거되지 않으므로 조용히 넘어가면 안 된다.
+// Notice for when the remote has no branches at all (empty remote, no origin) or develop creation was skipped.
+// Without develop the pr-flow workflows are never triggered, so this must not pass silently.
 export function developMissingNotice({ main, develop }) {
-  return `원격에 '${develop}' 브랜치가 없습니다 — 설치 파일을 커밋해 '${main}'을 push한 뒤 만들어 주세요: git push origin ${main}:${develop}`;
+  return t("core.branches.developMissing", { main, develop });
 }
 
-// 결정 (순수 함수): 플래그/답변 → 최종 구성.
-// 우선순위: 명시값(mainBranch/developBranch) → 감지 default → 하드 폴백(main/develop).
+// Decision (pure function): flags/answers to the final configuration.
+// Priority: explicit values (mainBranch/developBranch), then detected default, then hard fallback (main/develop).
 export function resolveBranchConfig({ mainBranch = "", developBranch = "", defaultBranch = "" } = {}) {
   const main = mainBranch || defaultBranch || "main";
   const develop = developBranch || "develop";
   return { main, develop, mode: main === develop ? "trunk-based" : "pr-flow" };
 }
 
-// 브랜치 선택 프롬프트용 정렬. def를 최우선으로, 그다음 priority(main/develop)
-// 순서로 목록 앞에 배치한다. 나머지는 remoteBranches의 원래 순서(git이 준 알파벳순)를 유지한다.
-// 순수 함수 — remoteBranches 원본은 변경하지 않는다.
+// Ordering for the branch selection prompt. def goes first, then priority (main/develop) in that order, at the
+// front of the list. The rest keep remoteBranches' original order (alphabetical as given by git).
+// Pure function: the remoteBranches original is not modified.
 export function sortBranchesForSelection(remoteBranches, def, priority = ["main", "develop"]) {
   const priorityOrder = [def, ...priority].filter((b, i, arr) => arr.indexOf(b) === i);
   const inPriority = priorityOrder.filter((b) => remoteBranches.includes(b));
@@ -62,27 +64,27 @@ export function sortBranchesForSelection(remoteBranches, def, priority = ["main"
   return [...inPriority, ...rest];
 }
 
-// 생성: develop이 원격에 없으면 현 HEAD 기준으로 생성 + push.
-// confirm: async(message)→bool — 대화형 확인 질문. null이면(--force) 질문 없이 자동 생성.
-// exec 주입 가능 (테스트 mock). 반환 { created, pushed?, skipped? }.
+// Creation: when develop is missing on the remote, create it from the current HEAD and push.
+// confirm: async(message)->bool, the interactive confirmation. When null (--force) it is created without asking.
+// exec is injectable (test mock). Returns { created, pushed?, skipped? }.
 export async function ensureDevelopBranch({ develop, remoteBranches = [], confirm = null, cwd, exec = defaultExec, log = null }) {
   if (remoteBranches.includes(develop)) return { created: false };
 
   if (confirm) {
-    const ok = await confirm(`원격에 '${develop}' 브랜치가 없습니다. 현재 HEAD 기준으로 생성하고 push할까요?`);
+    const ok = await confirm(t("core.branches.confirmCreate", { develop }));
     if (ok !== true) return { created: false, skipped: true };
   }
 
   const br = await exec("git", ["branch", develop], { cwd });
   if (br.code !== 0) {
-    // 이미 로컬에 존재하는 경우 등 — push만 시도
-    log?.(`'${develop}' 로컬 브랜치 생성 생략 (${(br.stderr || "").trim() || "이미 존재"})`);
+    // e.g. it already exists locally: just try the push
+    log?.(t("core.branches.localSkipped", { develop, reason: (br.stderr || "").trim() || t("core.branches.alreadyExists") }));
   }
   const push = await exec("git", ["push", "-u", "origin", develop], { cwd });
   if (push.code !== 0) {
-    log?.(`⚠️  '${develop}' 브랜치 push 실패 — 원격 설정을 확인한 뒤 수동으로 push하세요 (git push -u origin ${develop})`);
+    log?.(t("core.branches.pushFailed", { develop }));
     return { created: true, pushed: false };
   }
-  log?.(`'${develop}' 브랜치를 생성하고 push했습니다.`);
+  log?.(t("core.branches.created", { develop }));
   return { created: true, pushed: true };
 }

package/src/core/branding.js

@@ -1,15 +1,16 @@
-// 브랜치 플레이스홀더 치환 파이프라인.
-// payload 워크플로우의 {{MAIN_BRANCH}}/{{DEVELOP_BRANCH}}를 설치 시 실제 브랜치명으로 바꾼다.
-// ⚠️ GitHub Actions 표현식 `${{ ... }}`은 우리 토큰이 아니다 — `$` 선행 시 제외(lookbehind).
-// 치환 후 알 수 없는 {{TOKEN}}이 남으면 throw — 복사 무결성 가드 (오타·누락 조기 검출).
+// Branch placeholder substitution pipeline.
+// Replaces {{MAIN_BRANCH}}/{{DEVELOP_BRANCH}} in payload workflows with the real branch names at install time.
+// WARNING: the GitHub Actions expression `${{ ... }}` is not our token, so a leading `$` excludes it (lookbehind).
+// Throws when an unknown {{TOKEN}} remains after substitution: a copy-integrity guard (catches typos and omissions early).
+import { t } from "../i18n/index.js";
 
 const TOKEN_RE = /(?<!\$)\{\{([A-Z][A-Z0-9_]*)\}\}/g;
 
-// substitute(text, {main, develop}) — 브랜치 토큰 치환. 미지 토큰 발견 시 throw.
+// substitute(text, {main, develop}): substitutes branch tokens. Throws when an unknown token is found.
 export function substitute(text, { main, develop }) {
   const map = { MAIN_BRANCH: main, DEVELOP_BRANCH: develop };
   return String(text).replace(TOKEN_RE, (_, name) => {
     if (name in map) return map[name];
-    throw new Error(`알 수 없는 플레이스홀더가 남았습니다: {{${name}}}`);
+    throw new Error(t("core.branding.unknownPlaceholder", { name }));
   });
 }

package/src/core/breaking-check.js

@@ -1,32 +1,33 @@
-// breaking-changes 확인 흐름 배선.
-// collectBreaking(순수 비교)은 breaking.js — 이 모듈은 로드(패키지 번들본)·표시·확인 게이트.
+// Wiring for the breaking-changes confirmation flow.
+// collectBreaking (pure comparison) is in breaking.js - this module handles loading (bundled copy), display and the confirmation gate.
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { collectBreaking } from "./breaking.js";
+import { collectBreaking, localizedField } from "./breaking.js";
 import { parseExisting } from "./version-yml.js";
+import { t } from "../i18n/index.js";
 
-// 패키지에 동봉된 payload/config 번들본만 읽는다. 원격(main)을 읽으면 같은 패키지 버전이라도
-// 실행 시점마다 결과가 달라지고 설치 중 네트워크 요청이 생긴다. 읽기 실패 시 null(조용히 스킵).
+// Reads only the payload/config copy bundled with the package. Reading remote (main) would make results
+// differ per run even for the same package version, and add a network request during install. null on read failure (silent skip).
 export function loadBreakingJson(payloadRoot) {
   try {
     const p = join(payloadRoot, "config", "breaking-changes.json");
     if (existsSync(p)) return JSON.parse(readFileSync(p, "utf8"));
-  } catch { /* 번들 읽기 실패 — 스킵 */ }
+  } catch { /* bundle read failed - skip */ }
   return null;
 }
 
-// 반환: true=진행, false=사용자 취소.
+// Returns: true = proceed, false = user cancelled.
 // opts:
-//   cwd             - 통합 대상 루트 (기존 version.yml에서 현재 템플릿 버전 읽음)
-//   payloadRoot     - 패키지 payload/ 루트 (번들 breaking-changes.json 위치)
-//   templateVersion - 설치하려는 템플릿 버전 (고정값이 아니라 실제 패키지 버전)
-//   askYesNo        - async(message, defaultYes)→bool. null이면 비대화형: 경고만 출력 후 진행
-//   loader          - 테스트 주입용 (기본 loadBreakingJson)
+//   cwd             - integration target root (current template version is read from the existing version.yml)
+//   payloadRoot     - package payload/ root (where the bundled breaking-changes.json lives)
+//   templateVersion - template version being installed (the actual package version, not a fixed value)
+//   askYesNo        - async(message, defaultYes)->bool. null = non-interactive: print the warning and proceed
+//   loader          - injected by tests (default loadBreakingJson)
 export async function runBreakingCheck({ cwd, payloadRoot, templateVersion, askYesNo = null, loader = loadBreakingJson }) {
   const vy = join(cwd, "version.yml");
-  if (!existsSync(vy)) return true; // 신규 통합 — 비교 기준 없음
+  if (!existsSync(vy)) return true; // New integration - nothing to compare against
   const { templateVersion: current, types } = parseExisting(readFileSync(vy, "utf8"));
-  if (!current) return true; // 템플릿 메타 없음(unknown) — 비교 기준이 없어 스킵
+  if (!current) return true; // No template metadata (unknown) - nothing to compare against, skip
 
   const json = await loader(payloadRoot);
   if (!json) return true;
@@ -34,26 +35,26 @@ export async function runBreakingCheck({ cwd, payloadRoot, templateVersion, askY
   const { critical, warnings } = collectBreaking(json, current, templateVersion, types);
   if (critical.length === 0 && warnings.length === 0) return true;
 
-  // 박스 표시
+  // Box display
   const e = (s = "") => process.stderr.write(s + "\n");
   e("");
   e("╔══════════════════════════════════════════════════════════════════╗");
   e(`║  ⚠️  BREAKING CHANGES (v${current} → v${templateVersion})`);
   e("╠══════════════════════════════════════════════════════════════════╣");
-  for (const c of critical) { e("║"); e(`║  [CRITICAL] ${c.version} - ${c.title || ""}`); e(`║  → ${c.message || ""}`); }
-  for (const w of warnings) { e("║"); e(`║  [WARNING] ${w.version} - ${w.title || ""}`); e(`║  → ${w.message || ""}`); }
+  for (const c of critical) { e("║"); e(`║  [CRITICAL] ${c.version} - ${localizedField(c, "title")}`); e(`║  → ${localizedField(c, "message")}`); }
+  for (const w of warnings) { e("║"); e(`║  [WARNING] ${w.version} - ${localizedField(w, "title")}`); e(`║  → ${localizedField(w, "message")}`); }
   e("║");
   e("╚══════════════════════════════════════════════════════════════════╝");
   e("");
 
   if (critical.length > 0) {
     if (askYesNo) {
-      // 대화형: 명시 확인 없으면 중단 (기본 N)
-      const ok = await askYesNo("위 호환성 변경을 확인했고 계속 진행할까요?", false);
+      // Interactive: abort without explicit confirmation (default N)
+      const ok = await askYesNo(t("core.breakingCheck.confirm"), false);
       if (ok !== true) return false;
     } else {
-      // 비대화형(--force): 게이트로 CI를 죽이지 않고 경고 후 진행 (CI 친화)
-      e("⚠️  CRITICAL 호환성 변경이 있습니다 — 비대화형 실행이라 계속 진행합니다. 위 내용을 꼭 확인하세요.");
+      // Non-interactive (--force): do not kill CI with a gate, warn and proceed (CI friendly)
+      e(t("core.breakingCheck.nonInteractive"));
     }
   }
   return true;

package/src/core/breaking.js

@@ -1,4 +1,6 @@
-// 버전 비교: v 접두 제거, 3자리 숫자 비교, 누락 자리=0
+import { getLanguage } from "../i18n/index.js";
+
+// Version comparison: strips the v prefix, compares 3 numeric parts, missing part = 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);
@@ -10,19 +12,24 @@ export function compareVersions(a, b) {
   return 0;
 }
 
-// breaking-changes.json에서 current < ver <= target 범위 항목 수집.
-// target은 고정값이 아니라 실제 templateVersion을 넘긴다 — 그래야 설치하려는 버전까지의 고지가 모두 잡힌다.
-// _ 로 시작하는 키(메타) 제외. severity critical / 그 외(warning).
-// 버전 키의 값은 항목 객체 또는 항목 객체의 배열(같은 릴리스에 고지가 여러 건일 때).
-// types: 설치된 프로젝트 타입. 항목에 types가 있으면 겹치는 타입이 있을 때만 보여준다 — spring 레포에
-// Flutter 전용 경고가 뜨면 진짜 알려야 할 고지가 묻힌다. types를 모르면(빈 배열) 전부 보여준다.
+// Text of an entry in the given language: `title_ko` / `message_ko` when present, otherwise the plain (English) field.
+export function localizedField(entry, field, lang = getLanguage()) {
+  return entry?.[`${field}_${lang}`] || entry?.[field] || "";
+}
+
+// Collect entries from breaking-changes.json with current < ver <= target.
+// target is the actual templateVersion, not a fixed value - so every notice up to the version being installed is caught.
+// Keys starting with _ (metadata) are skipped. severity critical / anything else (warning).
+// A version key's value is an entry object or an array of entry objects (several notices in one release).
+// types: installed project types. When an entry has types it is shown only if one overlaps - a
+// Flutter-only warning on a spring repo would bury the notices that really matter. Unknown types (empty array) shows everything.
 export function collectBreaking(json, current, target, types = []) {
   const critical = [], warnings = [];
   const relevant = (entry) => !Array.isArray(entry?.types) || !types.length || entry.types.some((t) => types.includes(t));
   for (const [ver, value] of Object.entries(json || {})) {
     if (ver.startsWith("_")) continue;
     if (compareVersions(current, ver) < 0 && compareVersions(ver, target) <= 0) {
-      // 한 릴리스에 고지가 여러 건이면 배열로 등록한다 — JSON 키(버전)는 유일해서 객체로는 한 건만 담긴다.
+      // Several notices in one release are registered as an array - JSON keys (versions) are unique, so an object holds only one.
       for (const entry of Array.isArray(value) ? value : [value]) {
         if (!relevant(entry)) continue;
         const rec = { version: ver, ...entry };

package/src/core/copy/app-files.js

@@ -1,8 +1,9 @@
-// 타입 전용 앱 파일(사용자 소유, 없을 때만 생성) 설치 — 타입 훅(planAppFiles/copyAppFiles)을 돌려 합친다.
-// 어떤 파일이 대상인지는 훅이 정하므로 여기서는 타입 이름을 알지 못한다.
+// Installs type-specific app files (user-owned, created only when missing) by running the type hooks
+// (planAppFiles/copyAppFiles) and merging their results.
+// Which files are targeted is decided by the hooks, so this module knows no type names.
 import { hooksFor, typeInfo } from "../types.js";
 
-// 읽기 전용 — dry-run이 쓴다. 반환: { created:[], kept:[] }
+// Read-only, used by dry-run. Returns { created:[], kept:[] }
 export function planTypeAppFiles(context, payloadRoot, targetRoot = ".") {
   const result = { created: [], kept: [] };
   for (const { hook } of hooksFor(context.types || [], "planAppFiles")) {
@@ -13,7 +14,7 @@ export function planTypeAppFiles(context, payloadRoot, targetRoot = ".") {
   return result;
 }
 
-// onFile(tag, action, relPath): 파일마다 호출되는 로그 콜백. 반환: { created:[], kept:[] }
+// onFile(tag, action, relPath): log callback invoked per file. Returns { created:[], kept:[] }
 export function copyTypeAppFiles(context, payloadRoot, targetRoot = ".", onFile = () => {}) {
   const result = { created: [], kept: [] };
   for (const { id, hook } of hooksFor(context.types || [], "copyAppFiles")) {

package/src/core/copy/flutter-app.js

@@ -1,7 +1,7 @@
-// Flutter 앱 소유 파일(fastlane·ExportOptions.plist) 설치.
-// 워크플로우와 달리 사용자가 값을 채워 넣는 파일이라 "없을 때만 생성"한다 — 덮어쓰지 않고 baseline
-// 3-way도 적용하지 않는다(기존 사용자 파일을 덮어쓰지 않는 규약). 원본 갱신을 기존 사용자에게
-// 전파하는 것은 범위 밖이다.
+// Installs Flutter app-owned files (fastlane, ExportOptions.plist).
+// Unlike workflows these are files the user fills in, so they are created only when missing: never
+// overwritten and no baseline 3-way applied (existing user files are not overwritten by convention).
+// Propagating upstream changes to existing users is out of scope.
 import { join, posix } from "node:path";
 import { existsSync } from "node:fs";
 import { copyFileSync } from "../fsutil.js";
@@ -9,8 +9,8 @@ import { storeAppFilesFor } from "../flutter-options.js";
 
 const FLUTTER_APP_DIR = "flutter-app"; // payload/flutter-app/
 
-// 이번 실행에서 다룰 파일의 (보고용 상대경로, 원본, 목적지) 목록.
-// 대상은 Flutter 타입이 있을 때만이고, 선택된 플랫폼(context.flutterStore, null이면 둘 다)의 파일로 한정한다.
+// List of (reported relative path, source, destination) for the files handled in this run.
+// Only when the Flutter type is present, limited to the selected platforms (context.flutterStore, null = both).
 function flutterAppTargets(context, payloadRoot, targetRoot) {
   const { types = [], paths = new Map(), flutterStore = null } = context;
   if (!types.includes("flutter")) return [];
@@ -22,7 +22,7 @@ function flutterAppTargets(context, payloadRoot, targetRoot) {
   }));
 }
 
-// 읽기 전용 — status/dry-run이 쓴다. 원본 payload는 읽지 않는다.
+// Read-only, used by status/dry-run. Does not read the source payload.
 export function planFlutterAppFiles(context, payloadRoot, targetRoot = ".") {
   const result = { created: [], kept: [] };
   for (const { reported, dst } of flutterAppTargets(context, payloadRoot, targetRoot)) {
@@ -35,7 +35,7 @@ export function copyFlutterAppFiles(context, payloadRoot, targetRoot = ".") {
   const result = { created: [], kept: [] };
   for (const { reported, src, dst } of flutterAppTargets(context, payloadRoot, targetRoot)) {
     if (existsSync(dst)) { result.kept.push(reported); continue; }
-    copyFileSync(src, dst); // 부모 디렉토리 생성 + 바이트 그대로(CRLF 보존)
+    copyFileSync(src, dst); // creates parent directories and copies bytes as-is (preserves CRLF)
     result.created.push(reported);
   }
   return result;