project-auto-wizard 0.13.2 → 0.14.0

package/src/core/removal-plan.js

@@ -1,20 +1,20 @@
-// 제거 대상 판별기 — 마법사가 설치한 파일이 무엇인지 가려낸다.
-// uninstall(항목 체크리스트)과 purge(숨김 개발 모드)의 공통 기반이며, 아무것도 지우지 않는다.
+// Removal-target detector - works out which files the wizard installed.
+// Shared base of uninstall (item checklist) and purge (hidden dev mode); it deletes nothing.
 //
-// 원칙: (a) 현재 payload에 존재하는 파일명과 정확히 일치하는 것, (b) 설치된 워크플로우 파일 중
-// 마법사 관리 마커(MANAGED_WORKFLOW_MARKER)로 시작하는 것 — 이 둘의 합집합을 제거 대상으로 삼는다.
-// (a)만으로는 과거 버전에서 설치된 뒤 이후 릴리스에서 payload 파일명이 바뀌거나 삭제된 파일을
-// 인식하지 못했다 (원래 버그). 반대로 (b)만으로는 이 수정 이전에 설치되어 마커가
-// 없는(그러나 파일명은 여전히 현재 payload와 일치하는) 기존 설치 전체를 인식하지 못하는 회귀가
-// 생긴다 — 그래서 두 방식을 합집합으로 병행한다. 마커는 이 수정 이후 배포되는 payload 템플릿부터
-// 포함되므로, (b) 경로가 실제로 새로 잡아내는 것은 "이름이 바뀌거나 삭제된, 마커가 있는" 파일뿐이다.
-// 단, 마커는 사용자가 워크플로우를 복사해 이름만 바꾼 파일에도 그대로 따라간다. 그래서 (b)는
-// baseline에 설치 기록이 있는 파일명만 인정하고, baseline이 없는 구버전 설치에서만 PROJECT-* 접두로 대신 판단한다.
-// 사용자가 직접 만든 워크플로우·version.yml·README·.gitignore는 대상이 아니다
-// (version.yml은 사용자 버전 데이터 — 제거 대상이 아니라 산출물이다).
+// Principle: the union of (a) files whose name exactly matches one in the current payload and (b) installed
+// workflow files that start with the wizard-managed marker (MANAGED_WORKFLOW_MARKER) is the removal target.
+// (a) alone missed files installed by an older version whose payload filename was later renamed or deleted
+// (the original bug). (b) alone would regress by missing every existing install made before the marker
+// existed (whose filenames still match the current payload) - so both are used together as a union. The marker
+// ships only in payload templates released after that fix, so what path (b) newly catches is only
+// "renamed or deleted files that carry the marker".
+// However, the marker follows a workflow the user copied and merely renamed. So (b) accepts only filenames
+// recorded in the baseline, and only for old installs without a baseline falls back to the PROJECT-* prefix.
+// User-made workflows, version.yml, README and .gitignore are not targets
+// (version.yml is the user's version data - an artifact, not a removal target).
 //
-// 이 파일은 원래 src/commands/revert.js였다. revert 모드는 uninstall의 부분집합이라 제거됐고
-//, 판별 로직만 남아 commands가 아닌 core로 옮겨졌다.
+// This file used to be src/commands/revert.js. The revert mode was removed as a subset of uninstall,
+// and only the detection logic remained, moved to core rather than commands.
 import { join, isAbsolute } from "node:path";
 import { existsSync, readFileSync, readdirSync, renameSync, rmSync } from "node:fs";
 import { PATHS } from "./paths.js";
@@ -23,12 +23,12 @@ import { LOG_DIR } from "./logger.js";
 import { payloadWorkflowNames } from "./deploy-style.js";
 import { SCRIPT_NAMES } from "./copy/simple.js";
 
-// payload/workflows/**/*.yaml 첫 줄에 심어둔 고정 마커 — 이 값이 바뀌면 과거 설치분과의 매칭이 끊긴다.
+// Fixed marker planted on the first line of payload/workflows/**/*.yaml - changing this value breaks matching with past installs.
 export const MANAGED_WORKFLOW_MARKER = "# project-auto-wizard:managed-workflow";
 
-// 설치된 워크플로우 디렉토리(평면 구조)에서 관리 마커로 시작하는 파일명 집합.
-// .bak/.template.yaml 백업본도 원본 텍스트를 그대로 복사한 것이라 마커를 그대로 갖고 있어
-// 확장자나 파일명 유추 없이 동일한 방식으로 인식된다.
+// Set of filenames starting with the managed marker in the installed workflows directory (flat layout).
+// .bak/.template.yaml backups are verbatim copies of the original text and keep the marker,
+// so they are recognized the same way without inferring from extension or filename.
 function markedWorkflowNames(wfDir) {
   const names = new Set();
   if (!existsSync(wfDir)) return names;
@@ -40,8 +40,8 @@ function markedWorkflowNames(wfDir) {
   return names;
 }
 
-// 마커가 있는 파일이 마법사가 설치한 것인지 — .bak/.template.yaml 백업본은 원본 파일명으로 따진다.
-// recorded: baseline의 파일명 집합, baseline이 없으면 null.
+// Whether a marked file was installed by the wizard - .bak/.template.yaml backups are judged by the original filename.
+// recorded: set of filenames in the baseline, null when there is no baseline.
 function isInstalledName(name, recorded) {
   if (!recorded) return name.startsWith("PROJECT-");
   const stem = name.endsWith(".bak") ? name.slice(0, -".bak".length) : name;
@@ -53,18 +53,18 @@ function isInstalledName(name, recorded) {
   return candidates.some((c) => recorded.has(c));
 }
 
-// 충돌 처리·정리로 생긴 백업 파생 파일(.bak/.template.yaml) — .gitignore 자동 추가 항목이 가리는 대상이다.
-// 워크플로우를 남기는 삭제에서 이 파일들이 남으면 .gitignore 항목도 남겨야 git 상태에 드러나지 않는다.
+// Backup-derived files created by conflict handling/cleanup (.bak/.template.yaml) - what the auto-added .gitignore entries hide.
+// If these files remain after a removal that keeps the workflows, the .gitignore entries must stay too, or they show up in git status.
 export const backupArtifacts = (names) => names.filter((n) => n.endsWith(".bak") || n.endsWith(".template.yaml"));
 
-// 아무것도 지우지 않는 순수 함수 — uninstall/purge/--dry-run이 공유한다.
+// Pure function that deletes nothing - shared by uninstall/purge/--dry-run.
 export function planRemoval(payloadRoot, targetRoot = ".") {
   const removedWf = new Set();
   const removedScripts = [];
   const wfDir = join(targetRoot, PATHS.workflowsDir);
   const baseline = readBaseline(targetRoot);
   if (existsSync(wfDir)) {
-    // (a) 현재 payload와 파일명이 일치하는 것 — 마커 유무 무관(기존 설치 회귀 방지).
+    // (a) Files whose name matches the current payload - marker or not (prevents regressing existing installs).
     for (const name of payloadWorkflowNames(payloadRoot)) {
       const p = join(wfDir, name);
       if (existsSync(p)) removedWf.add(name);
@@ -72,7 +72,7 @@ export function planRemoval(payloadRoot, targetRoot = ".") {
       if (existsSync(join(wfDir, templateName))) removedWf.add(templateName);
       if (existsSync(p + ".bak")) removedWf.add(name + ".bak");
     }
-    // (b) 관리 마커로 시작하는 것 — payload에서 이름이 바뀌거나 삭제된 파일도 인식.
+    // (b) Files starting with the managed marker - also recognizes files renamed or deleted in the payload.
     const recorded = baseline ? new Set(Object.keys(baseline.files)) : null;
     for (const name of markedWorkflowNames(wfDir)) {
       if (isInstalledName(name, recorded)) removedWf.add(name);
@@ -81,24 +81,24 @@ export function planRemoval(payloadRoot, targetRoot = ".") {
   for (const s of SCRIPT_NAMES) {
     if (existsSync(join(targetRoot, PATHS.scriptsDir, s))) removedScripts.push(s);
   }
-  // Flutter 앱 파일(Fastfile 등)은 마법사가 새로 만들었고 내용이 그대로인 것만 — 값을 채워 넣은 파일은 사용자 것이다.
+  // Flutter app files (Fastfile etc.) only if the wizard newly created them and the content is unchanged - a file with filled-in values belongs to the user.
   const appFiles = [];
   for (const [rel, hash] of Object.entries(baseline?.appFiles || {})) {
-    if (rel.split(/[\\/]/).includes("..") || isAbsolute(rel)) continue; // 레포 밖 경로는 신뢰하지 않는다
+    if (rel.split(/[\\/]/).includes("..") || isAbsolute(rel)) continue; // paths outside the repo are not trusted
     const p = join(targetRoot, rel);
     if (existsSync(p) && appFileHash(readFileSync(p, "utf8")) === hash) appFiles.push(rel);
   }
-  // baseline은 마법사가 만든 내부 상태 파일이다 — 설치물을 지우면 함께 사라져야 한다.
-  // 남겨두면 다음 설치가 "예전에 깔았다가 사용자가 지운 파일"로 오인해 전부 removed로 분류한다.
-  // 실행 로그(.wizard/logs)만 남은 경우도 같은 폴더째 지운다 — 설치물을 다 지운 뒤 로그 폴더만 남으면
-  // "완전 삭제"가 아니다.
+  // The baseline is an internal state file made by the wizard - it must disappear along with the installed files.
+  // If left, the next install would mistake everything for "files installed before and deleted by the user" and classify all as removed.
+  // If only the run logs (.wizard/logs) remain, the whole folder goes too - a log folder left after all
+  // installed files are gone is not a "complete removal".
   const baselineDirs = existsSync(join(targetRoot, BASELINE_PATH)) || existsSync(join(targetRoot, LOG_DIR)) ? [BASELINE_DIR] : [];
   return { workflows: [...removedWf], scripts: removedScripts, appFiles, baseline: baselineDirs };
 }
 
-// 업데이트 때 정리할 옛 워크플로우 — 마법사가 설치했지만(baseline 기록 + 관리 마커) 지금 payload에는 없는 파일.
-// payload에서 이름이 바뀌거나 빠진 파일이라, 남겨두면 옛 트리거·옛 절차로 계속 돈다.
-// baseline에 없는 파일은 대상이 아니다 — 사용자가 마법사 파일을 복사해 만든 워크플로우일 수 있다.
+// Old workflows to clean up on update - files the wizard installed (baseline record + managed marker) that are not in the payload now.
+// They were renamed or dropped in the payload, so leaving them keeps running with the old triggers and procedure.
+// Files not in the baseline are not targets - they may be workflows the user made by copying a wizard file.
 export function findStaleWorkflows(payloadRoot, targetRoot = ".", baseline = null) {
   if (!baseline?.files) return [];
   const current = payloadWorkflowNames(payloadRoot);
@@ -107,8 +107,8 @@ export function findStaleWorkflows(payloadRoot, targetRoot = ".", baseline = nul
     .sort();
 }
 
-// 배포 방식 정리와 같은 규칙 — 손대지 않은 파일(installed 해시 일치)은 삭제, 손댄 파일은 .bak으로 옮겨
-// 내용은 지키고 트리거만 끈다. dryRun이면 판정만 하고 파일은 건드리지 않는다 (--dry-run 미리보기용).
+// Same rule as deploy-style cleanup - untouched files (installed hash matches) are deleted, touched files are moved to .bak
+// to keep the content while switching off the trigger. With dryRun only the verdict is made and no file is touched (for the --dry-run preview).
 export function cleanupStaleWorkflows(targetRoot, names, baseline, { dryRun = false } = {}) {
   const wfDir = join(targetRoot, PATHS.workflowsDir);
   const removed = [];

package/src/core/types.js

@@ -1,40 +1,40 @@
 import { flutterHooks } from "./flutter-hooks.js";
 
-// 프로젝트 타입 레지스트리 — 타입별 지식(감지 마커, 감지 순서, 버전·빌드 번호 파일)을 한 곳에 둔다.
-// 타입 목록·마커 맵·감지 체인은 모두 이 표에서 만들어지므로, 새 타입은 여기에 한 줄을 더하는 것에서 시작한다.
-// (릴리스 시점의 버전 파일 쓰기는 payload/scripts/version_manager.py가 따로 담당한다.)
+// Project type registry: keeps per-type knowledge (detection markers, detection order, version and build-number files) in one place.
+// The type list, marker map and detection chain are all built from this table, so a new type starts with one more line here.
+// (Writing version files at release time is handled separately by payload/scripts/version_manager.py.)
 //
-// 필드:
-//   id                 CLI·version.yml에 쓰이는 타입 이름. 배열 순서가 곧 --help·대화형 선택지 표시 순서다.
-//   markers            그 타입의 근거 파일. [0]이 대표 파일이고, 모노레포 경로 탐색은 이 순서로 우선순위를 둔다.
-//   detectBy           자동 감지 방식 — "markers": markers 중 하나라도 있으면 감지
-//                      "package": package.json 의존성 키(packageDep)로 감지
-//                      "package-fallback": package.json은 있지만 위 어느 것도 아닐 때
-//                      없음: 자동 감지하지 않는다(basic은 아무것도 감지되지 않았을 때의 결과).
-//   detectOrder        같은 detectBy 안에서의 판정 순서. 앞선 규칙이 이긴다(expo 앱은 react-native 의존성도 가짐).
-//   versionSources     설치 시 버전을 읽을 파일 키(detect.js의 sources) — 주 타입일 때 이 순서로 먼저 읽는다.
-//   buildNumberSource  모바일 빌드 번호를 읽을 파일 키(detect.js의 detectBuildNumberFromFiles).
-//   singleServerCd     배포 방식 변형 없이 서버 배포 CD가 하나뿐일 때 그 워크플로우 파일명.
-//   hooks              타입 전용 동작. 없는 훅은 "할 일 없음"이라 공통 코드는 hooksFor()로 있는 것만 호출한다.
-//     workflowFilter(context)                         타입 루트 워크플로우 파일 필터(filename → bool) 또는 null
+// Fields:
+//   id                 Type name used in the CLI and version.yml. Array order is also the display order of --help and interactive choices.
+//   markers            Evidence files for the type. [0] is the representative file, and monorepo path search prioritizes in this order.
+//   detectBy           Auto-detection method - "markers": detected when any of markers exists
+//                      "package": detected by a package.json dependency key (packageDep)
+//                      "package-fallback": package.json exists but none of the above matched
+//                      absent: not auto-detected (basic is the result when nothing was detected).
+//   detectOrder        Evaluation order within the same detectBy. The earlier rule wins (an expo app also has a react-native dependency).
+//   versionSources     File keys to read the version from at install (sources in detect.js); read first in this order for the primary type.
+//   buildNumberSource  File key to read the mobile build number from (detectBuildNumberFromFiles in detect.js).
+//   singleServerCd     The workflow file name when there is exactly one server-deploy CD with no deploy-style variants.
+//   hooks              Type-specific behavior. A missing hook means "nothing to do", so common code calls only the existing ones through hooksFor().
+//     workflowFilter(context)                         Filter for the type's root workflow files (filename -> bool) or null
 //     cleanupWorkflows(dir, installed, context, baseline, opts)
-//                                                     선택에서 빠진 워크플로우 정리 → { removed, backedUp }
+//                                                     Cleanup of workflows dropped from the selection -> { removed, backedUp }
 //     planAppFiles / copyAppFiles(context, payloadRoot, targetRoot)
-//                                                     사용자 소유 앱 파일(없을 때만 생성) 계획/복사 → { created, kept }
-//     appFilesTag                                     앱 파일 복사 로그의 분류 이름
-//     statusLabels(options)                           status 옵션 줄에 덧붙일 문자열
-//     doctorChecks(cwd, existing, { docs })           doctor 진단 행 배열
-//     resolveOptions({ opts, existing, workflowsDir }) CLI 옵션 → 저장값 → 기본값 순으로 확정한 타입 옵션 객체
-//                                                     (workflowsDir는 설치된 워크플로우로 추론할 때만 넘긴다)
-//     contextDefaults                                 createContext의 미결정 기본 필드
+//                                                     Plan/copy of user-owned app files (created only when missing) -> { created, kept }
+//     appFilesTag                                     Category name in the app-file copy log
+//     statusLabels(options)                           String appended to the status options line
+//     doctorChecks(cwd, existing, { docs })           Array of doctor diagnostic rows
+//     resolveOptions({ opts, existing, workflowsDir }) Type option object decided as CLI options, then saved values, then defaults
+//                                                     (workflowsDir is passed only when inferring from installed workflows)
+//     contextDefaults                                 Undecided default fields of createContext
 //     contextFields(options) / optionsFromContext(context)
-//                                                     옵션 객체 ↔ 설치 컨텍스트 필드 변환
-//     versionOptionsBlock(options)                    version.yml options 아래에 덧붙일 블록(6칸 들여쓰기)
-//     savedOptionKeys                                 version.yml 저장 키 → parseExisting 옵션 필드
-//     cliFlags[{ flag, field, initial, parse(v) }]    타입 전용 CLI 플래그(파싱 결과 opts[field]에 담긴다)
-//     installNotices(options)                         설치 직후 알릴 경고 배열(빈 값은 무시)
-//     logChoices(context)                             설치 로그에 남길 선택값 [이름, 값] 배열
-// (타입 전용 대화형 질문 흐름은 아직 interactive.js에 남아 있다.)
+//                                                     Conversion between the option object and install-context fields
+//     versionOptionsBlock(options)                    Block appended under version.yml options (6-space indent)
+//     savedOptionKeys                                 Saved version.yml key to parseExisting option field
+//     cliFlags[{ flag, field, initial, parse(v) }]    Type-specific CLI flags (the parsed result goes into opts[field])
+//     installNotices(options)                         Array of warnings shown right after install (empty values ignored)
+//     logChoices(context)                             Array of selected [name, value] pairs to record in the install log
+// (The type-specific interactive question flow still lives in interactive.js.)
 export const TYPES = [
   {
     id: "spring",
@@ -68,13 +68,13 @@ export const TYPES = [
     id: "react-native",
     markers: ["package.json"],
     detectBy: "package", packageDep: "react-native", detectOrder: 2,
-    // 릴리스 때 동기화하는 네이티브 파일이 기준이고, 거기서 못 읽을 때만 package.json을 본다.
+    // The native files synced at release time are the reference; package.json is consulted only when they cannot be read.
     versionSources: ["reactNative", "packageJson"],
     buildNumberSource: "androidGradle",
   },
   {
-    // Expo는 최신 create-expo-app 템플릿처럼 app.json 없이 app.config.ts/js만 쓸 수 있다.
-    // 구성 파일이 아예 없어도 expo 의존성이 있는 package.json이 곧 근거다.
+    // Expo may use only app.config.ts/js without app.json, as in the latest create-expo-app template.
+    // Even with no config file at all, a package.json with an expo dependency is the evidence.
     id: "react-native-expo",
     markers: ["app.json", "app.config.ts", "app.config.js", "package.json"],
     detectBy: "package", packageDep: "expo", detectOrder: 1,
@@ -94,7 +94,7 @@ export const TYPES = [
     versionSources: ["pyproject", "setupPy"],
   },
   {
-    // 마커 파일이 없는 타입 — 아무것도 감지되지 않았을 때의 결과이자 경로가 필요 없는 타입.
+    // A type with no marker files: the result when nothing was detected, and a type that needs no path.
     id: "basic",
     markers: [],
   },
@@ -106,15 +106,15 @@ export const TYPES = [
   },
 ];
 
-// 감지 결과가 하나도 없을 때의 타입
+// Type used when nothing was detected
 export const FALLBACK_TYPE = "basic";
 
 const BY_ID = new Map(TYPES.map((t) => [t.id, t]));
 
-// 알 수 없는 타입은 undefined — 호출부가 각자의 기본값을 정한다.
+// Unknown types give undefined; callers decide their own defaults.
 export const typeInfo = (id) => BY_ID.get(id);
 
-// types 중 훅 name을 가진 것만 [{ id, hook }]으로 — 주어진 타입 순서를 유지한다.
+// Only those of types that have hook `name`, as [{ id, hook }], keeping the given type order.
 export function hooksFor(types, name) {
   const found = [];
   for (const id of types) {
@@ -124,31 +124,31 @@ export function hooksFor(types, name) {
   return found;
 }
 
-// types 중 훅 name을 가진 타입들의 반환값(객체)을 하나로 합친다 — 옵션·컨텍스트 필드처럼 타입마다 다른 키를 낼 때 쓴다.
+// Merges into one object the return values of the hook `name` from the types that have it; used when each type contributes different keys, such as options and context fields.
 export function mergeHookResults(types, name, ...args) {
   return Object.assign({}, ...hooksFor(types, name).map(({ hook }) => hook(...args)));
 }
 
-// 모든 타입이 선언한 훅 상수(contextDefaults·savedOptionKeys 등)를 하나로 합친다 — 타입이 정해지기 전에 필요한 기본 형태용.
+// Merges the hook constants declared by all types (contextDefaults, savedOptionKeys, etc.) into one; for the default shape needed before the types are decided.
 export const allHookValues = (name) => Object.assign({}, ...TYPES.map((t) => t.hooks?.[name]));
 
-// 표시 순서 그대로의 타입 이름 목록
-// VALID_TYPES·ALL_TYPES가 같은 배열을 공유하므로 한쪽에서 바꿔 다른 쪽이 오염되지 않게 고정한다.
+// Type names in display order.
+// VALID_TYPES and ALL_TYPES share the same array, so it is frozen to keep a change on one side from polluting the other.
 export const TYPE_IDS = Object.freeze(TYPES.map((t) => t.id));
 
 const byDetectOrder = (a, b) => a.detectOrder - b.detectOrder;
 
-// 파일 존재만으로 감지하는 타입 (감지 순서대로)
+// Types detected by file existence alone (in detection order)
 export const MARKER_DETECTED_TYPES = TYPES.filter((t) => t.detectBy === "markers").sort(byDetectOrder);
 
-// package.json 의존성으로 가르는 타입 (판정 순서대로)
+// Types told apart by package.json dependencies (in evaluation order)
 export const PACKAGE_DETECTED_TYPES = TYPES.filter((t) => t.detectBy === "package").sort(byDetectOrder);
 
-// package.json이 있지만 알려진 프레임워크 의존성이 없을 때의 타입
+// Type used when package.json exists but has no known framework dependency
 export const PACKAGE_FALLBACK_TYPE = TYPES.find((t) => t.detectBy === "package-fallback").id;
 
-// 모바일 빌드 번호(version_code)를 가진 타입
+// Types that have a mobile build number (version_code)
 export const BUILD_NUMBER_TYPES = new Set(TYPES.filter((t) => t.buildNumberSource).map((t) => t.id));
 
-// 배포 방식 변형 없이 서버 배포 CD가 하나뿐인 워크플로우 파일명
+// Workflow file names for which there is exactly one server-deploy CD, with no deploy-style variants
 export const SINGLE_SERVER_CD_FILES = new Set(TYPES.filter((t) => t.singleServerCd).map((t) => t.singleServerCd));

package/src/core/verify.js

@@ -1,26 +1,28 @@
-// 설치 후 검증 — 설치된 워크플로우를 다시 읽어 "이대로 돌아가는가"를 본다.
+// Post-install verification - re-reads the installed workflows to check "will this run as-is".
 //
-// 왜 설치 전이 아니라 후인가: 치환은 파일 단위로 흩어져 일어나고 auto 토큰은 resolver 결과에
-// 의존한다. 최종 디스크 내용을 보는 것이 실제로 배포될 것과 같은 것을 보는 유일한 방법이다.
+// Why after install rather than before: substitution happens scattered per file and auto tokens
+// depend on resolver results. Looking at the final disk content is the only way to see the same
+// thing that will actually be deployed.
 import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
+import { t } from "../i18n/index.js";
 
-// 치환 대상이 아닌 토큰 — 워크플로우 스크립트 안의 heredoc 구분자다. 값이 아니라 문법이므로
-// 미치환 검사에서 제외한다. (예: cat <<'__WIZARD_FILE_CONTENT_EOF__')
+// Tokens that are not substitution targets - heredoc delimiters inside workflow scripts. They are
+// syntax, not values, so they are excluded from the unsubstituted check. (e.g. cat <<'__WIZARD_FILE_CONTENT_EOF__')
 const SENTINEL_RE = /^__WIZARD_[A-Z0-9_]*__$/;
 const PLACEHOLDER_RE = /__[A-Z][A-Z0-9_]*__/g;
 
-// 주석으로 죽어 있는 줄 — 실행되지 않으므로 검사 대상이 아니다.
-// 템플릿에는 "[선택] ..." 예시 스텝이 통째로 주석 처리돼 들어 있는데, 이걸 세면
-// 쓰지도 않는 Secret을 "등록하세요"라고 안내하게 된다.
+// Lines dead as comments - they never run, so they are not checked.
+// The template contains whole optional example steps commented out; counting them
+// would tell the user to "register" secrets that are never used.
 const isCommented = (line) => /^\s*#/.test(line);
 
-// 미치환 플레이스홀더 스캔.
-// 종전에는 auto 토큰 계산이 실패해도(예: application.yaml을 못 찾아 경로가 빈 문자열) 그 줄을
-// 건드리지 않고 넘어가, __APPLICATION_YML_DIR__ 이 그대로 남은 워크플로우가 "설치 성공"으로
-// 끝났다. 배포 시점에야 그 이름의 디렉토리가 만들어지며 문제가 드러난다.
+// Scan for unsubstituted placeholders.
+// Previously, even when an auto token computation failed (e.g. application.yaml not found, so the path was an empty string),
+// the line was left untouched, and a workflow still containing __APPLICATION_YML_DIR__ ended as an
+// "install success". The problem only surfaced at deploy time, when a directory with that name got created.
 //
-// 반환: [{ filename, line, token, text }] — 사람이 바로 고칠 수 있게 줄 번호까지 준다.
+// Returns: [{ filename, line, token, text }] - with the line number so a person can fix it right away.
 export function scanUnsubstituted(workflowsDir, filenames = []) {
   const found = [];
   for (const filename of filenames) {
@@ -39,25 +41,29 @@ export function scanUnsubstituted(workflowsDir, filenames = []) {
   return found;
 }
 
-// GITHUB_TOKEN은 Actions가 자동 주입하므로 사용자가 등록할 대상이 아니다.
+// GITHUB_TOKEN is injected by Actions automatically, so it is not something the user registers.
 const AUTO_SECRETS = new Set(["GITHUB_TOKEN"]);
-// 없어도 워크플로우가 도는 secret — 폴백이 문서화돼 있다. 필수와 섞어 "등록해야 동작합니다"라고
-// 하면 안내 자체를 못 믿게 되므로 분리한다.
-//   AI_API_KEY   → 없으면 Copilot(opt-in, copilot_ai) → 규칙 fallback
-//   WORKFLOW_PAT → 없으면 GITHUB_TOKEN
+// Secrets the workflow runs without - the fallback is documented. Mixing them with required ones under
+// "must be registered to work" would make the guidance itself untrustworthy, so they are kept apart.
+//   AI_API_KEY   -> if absent: Copilot (opt-in, copilot_ai) -> rule-based fallback
+//   WORKFLOW_PAT -> if absent: GITHUB_TOKEN
 export const OPTIONAL_SECRETS = new Set(["AI_API_KEY", "WORKFLOW_PAT"]);
 const SECRET_RE = /secrets\.([A-Z][A-Z0-9_]*)/g;
 
-// 워크플로우 머리 주석의 "NAME (선택)" 표기 — 워크플로우가 비어 있어도 동작하도록 작성된 secret이다.
-const OPTIONAL_NOTE_RE = /^\s*#\s*-?\s*([A-Z][A-Z0-9_]*)\s*\(선택/;
-// `secrets.A || secrets.B` — 둘 중 하나만 있으면 된다.
+// The "NAME (optional)" note in a workflow header comment - a secret the workflow is written to work without.
+// The payload uses "(optional)"; the legacy Korean marker ("\uC120\uD0DD") is still accepted so workflows installed
+// by older versions keep being classified correctly.
+const OPTIONAL_NOTE_RE = /^\s*#\s*-?\s*([A-Z][A-Z0-9_]*)\s*\((?:\uC120\uD0DD|optional)/i;
+// `secrets.A || secrets.B` - only one of the two is needed.
 const EITHER_RE = /^\s*\|\|\s*secrets\.([A-Z][A-Z0-9_]*)/;
-// `secrets.A || '3000'`, `secrets.A || vars.A` — 기본값·대체값이 있다.
+// `secrets.A || '3000'`, `secrets.A || vars.A` - there is a default/alternative value.
 const FALLBACK_AFTER_RE = /^\s*\|\|/;
 const FALLBACK_BEFORE_RE = /\|\|\s*$/;
-export const EITHER_SEP = " 또는 ";
+// Separator of a "A or B" secret pair. It is shown to the user and also used to split keys, so it follows
+// the current language; evaluated lazily (via toString) because it must not be fixed at import time.
+export const EITHER_SEP = { toString: () => t("core.verify.eitherSep") };
 
-// 한 파일 안의 secret 참조를 필수 / 둘 중 하나 / 선택으로 가른다.
+// Sorts the secret references in one file into required / either-of-two / optional.
 function classifyFile(content) {
   const lines = content.split(/\r?\n/);
   const noted = new Set();
@@ -78,7 +84,7 @@ function classifyFile(content) {
       const either = rest.match(EITHER_RE);
       if (either) {
         pairs.push([name, either[1]]);
-        i++; // 짝의 오른쪽은 이미 묶었다
+        i++; // the right side of the pair is already bound
       } else if (FALLBACK_AFTER_RE.test(rest) || FALLBACK_BEFORE_RE.test(line.slice(0, m.index))) {
         optional.add(name);
       } else {
@@ -96,10 +102,10 @@ function classifyFile(content) {
   return out;
 }
 
-// 설치된 워크플로우의 secret을 필수와 선택으로 나눈다.
-// 참조한 이름을 전부 필수로 세면 기본값이 있는 것·둘 중 하나면 되는 폴백 쌍까지 "등록해야 동작합니다"에
-// 섞여 개수가 부풀고, 처음 쓰는 사용자가 필요 없는 secret까지 등록하게 된다.
-// 반환: { required: Map<이름|"A 또는 B", 파일명[]>, optional: Map<같은 형식> }
+// Splits the secrets of the installed workflows into required and optional.
+// Counting every referenced name as required would mix ones with defaults and either-of-two fallback pairs into
+// "must be registered to work", inflating the count and making first-time users register secrets they do not need.
+// Returns: { required: Map<name|"A or B", filenames[]>, optional: Map<same format> }
 export function classifySecrets(workflowsDir, filenames = []) {
   const required = new Map();
   const optional = new Map();
@@ -117,7 +123,7 @@ export function classifySecrets(workflowsDir, filenames = []) {
     for (const k of r.required) if (!skip(k)) add(required, k, filename);
     for (const k of r.optional) if (!skip(k)) add(optional, k, filename);
   }
-  // 한 파일에서라도 단독으로 필수인 이름은 필수다 — 그 이름이 든 폴백 쌍·선택 항목은 이미 충족되므로 뺀다.
+  // A name that is required on its own in even one file is required - fallback pairs/optional entries containing it are already satisfied, so drop them.
   const requiredNames = new Set([...required.keys()].filter((k) => !k.includes(EITHER_SEP)));
   const coveredByRequired = (k) => k.split(EITHER_SEP).some((n) => requiredNames.has(n));
   for (const k of [...required.keys()]) if (k.includes(EITHER_SEP) && coveredByRequired(k)) required.delete(k);
@@ -126,23 +132,23 @@ export function classifySecrets(workflowsDir, filenames = []) {
   return { required: sorted(required), optional: sorted(optional) };
 }
 
-// 설치된 워크플로우가 요구하는 GitHub Secret 목록.
-// 완료 화면이 WORKFLOW_PAT와 권한만 안내하는 바람에, 배포 워크플로우가 실제로 필요로 하는
-// SERVER_HOST·SSH_KEY 같은 값이 하나도 안내되지 않았다. 설치 직후 상태로는 배포가 돌지 않는데
-// 그 사실이 어디에도 드러나지 않는다.
+// List of GitHub Secrets the installed workflows require.
+// The completion screen only mentioned WORKFLOW_PAT and permissions, so values the deploy workflow really needs
+// (SERVER_HOST, SSH_KEY, ...) were never announced. Right after install the deploy does not run,
+// and that fact was shown nowhere.
 //
-// 반환: Map<secretName 또는 "A 또는 B", string[] 그 secret을 쓰는 파일명>
+// Returns: Map<secretName or "A or B", string[] filenames that use the secret>
 export function collectRequiredSecrets(workflowsDir, filenames = []) {
   return classifySecrets(workflowsDir, filenames).required;
 }
 
-// 없어도 워크플로우가 도는 secret(기본값·대체값이 있거나 머리 주석에 "(선택)"으로 적힌 것).
+// Secrets the workflow runs without (having a default/alternative value, or marked optional in the header comment).
 export function collectOptionalSecrets(workflowsDir, filenames = []) {
   return classifySecrets(workflowsDir, filenames).optional;
 }
 
-// SSH 인증 방식에 따라 둘 중 하나만 필요한 secret — 사용자가 이미 답한 값으로 목록을 좁힌다.
-// 안 쓸 secret까지 "등록하세요"라고 하면 안내 자체를 신뢰하지 않게 된다.
+// Secrets where only one of two is needed depending on the SSH auth method - narrows the list using the answer the user already gave.
+// Telling the user to "register" secrets that will not be used makes the guidance itself untrusted.
 export function narrowSecretsBySshAuth(secrets, sshAuthMethod) {
   if (!sshAuthMethod) return secrets;
   const drop = sshAuthMethod === "key" ? "SERVER_PASSWORD" : "SSH_KEY";