projectops 4.0.2 → 4.0.4

package/src/index.js

@@ -1,13 +1,20 @@
 // projectops CLI 진입 파이프라인 (.sh main + execute_integration 등가).
 // 감지 → 다운로드 → 모드 라우팅 → 통합 실행 → 정리. 비대화형(--force) 우선.
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, existsSync } from "node:fs";
 import { parseArgs, parsePathsCsv, CliError } from "./cli/args.js";
 import { HELP_TEXT } from "./cli/help.js";
 import { createContext } from "./context.js";
 import { PATHS } from "./core/paths.js";
 import { remove } from "./core/fsutil.js";
 import { acquireTemplate, readTemplateVersion } from "./core/assets.js";
-import { detectTypes, detectVersion, detectDefaultBranch, detectRepoName } from "./core/detect-fs.js";
+import { detectTypes, detectVersion, detectDefaultBranch, detectRepoName, makeResolvers } from "./core/detect-fs.js";
+import { parseExisting } from "./core/version-yml.js";
+import { runBreakingCheck } from "./core/breaking-check.js";
+import { resolveProjectPaths } from "./core/paths-resolve.js";
+import { printBannerCompact } from "./ui/banner.js";
+import { printSummary } from "./ui/summary.js";
 import { runFull } from "./commands/full.js";
 import { runVersion } from "./commands/version.js";
 import { runWorkflows } from "./commands/workflows.js";
@@ -15,6 +22,17 @@ import { runIssues } from "./commands/issues.js";
 import { runInteractive } from "./commands/interactive.js";
 import { runSkills } from "./commands/skills.js";
 
+// projectops 패키지 버전 읽기 (-v/--version 출력용). src/../package.json.
+function readPkgVersion() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+    return pkg.version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 // 결정적 UTC 타임스탬프 (주입 가능 — 테스트/골든용)
 function utcNow(date = new Date()) {
   const p = (n) => String(n).padStart(2, "0");
@@ -34,6 +52,7 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
     if (e instanceof CliError) { console.error(e.message); return 1; }
     throw e;
   }
+  if (opts.showVersion) { console.log(readPkgVersion()); return 0; }
   if (opts.help) { console.log(HELP_TEXT); return 0; }
 
   // skills 모드 — IDE 스킬 설치/업데이트/제거 (템플릿 통합 없음).
@@ -63,40 +82,55 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
     return 1;
   }
 
+  // 기존 version.yml 로드 — version/version_code/project_paths 보존의 단일 진실 (.sh L2208~2239 SSoT)
+  const vyPath = join(cwd, "version.yml");
+  const existing = existsSync(vyPath) ? parseExisting(readFileSync(vyPath, "utf8")) : null;
+
   // 감지 (CLI 인자 우선, 없으면 자동 감지 — version.yml 우선 규칙은 detectTypes/detectVersion 내부)
   const types = opts.types.length ? opts.types : detectTypes(cwd);
-  const version = opts.version || detectVersion(cwd);
+  // version: 기존 version.yml 최우선(SSoT — 재실행 시 덮어쓰기 방지) → CLI 지정 → 파일 감지
+  const version = (existing?.version) || opts.version || detectVersion(cwd);
+  const versionCode = existing?.versionCode ?? 1; // 기존 빌드번호 보존 (.sh L2208~2221)
   const branch = detectDefaultBranch(cwd);
   const repoName = detectRepoName(cwd);
-  const paths = parsePathsCsv(opts.pathsCsv);
-  // paths 미지정 타입은 루트(".") — basic 제외
-  for (const t of types) if (t !== "basic" && !paths.has(t)) paths.set(t, ".");
+  // 경로 확정 (.sh resolve_project_paths 비대화형 경로 — --paths 우선 → 저장값 → 후보 1개 자동 → 루트 폴백)
+  const paths = await resolveProjectPaths({
+    root: cwd, types, paths: parsePathsCsv(opts.pathsCsv),
+    existingPaths: existing?.paths ?? new Map(), force: true, tty: false, io: {},
+  });
 
   const { now, today } = clock || utcNow();
   const tempDir = join(cwd, PATHS.tempDir);
 
   const context = createContext({
-    mode: opts.mode, force: true, types, version, branch,
-    paths, includeNexus: opts.includeNexus === true, includeSecretBackup: opts.includeSecretBackup === true,
+    mode: opts.mode, force: true, types, version, versionCode, branch,
+    paths,
+    // 옵션 워크플로우: CLI 플래그 최우선 → version.yml 저장 옵션(.sh read_template_options 등가) → false
+    includeNexus: opts.includeNexus ?? existing?.options?.nexus ?? false,
+    includeSecretBackup: opts.includeSecretBackup ?? existing?.options?.secretBackup ?? false,
     repoName,
-    resolvers: {
-      repo: () => repoName,
-      "spring-app-yml-dir": () => "",
-      "spring-app-yml-path": () => "",
-      "flutter-root": () => paths.get("flutter") || ".",
-    },
+    // 실 resolver 4종 (.sh resolve_token 등가 — spring-app-yml 스텁 제거)
+    resolvers: makeResolvers(cwd, repoName, paths),
     now, today,
   });
 
+  let result = null;
   try {
     acquireTemplate({ tempDir, source });
     context.templateVersion = readTemplateVersion(tempDir);
 
+    // 비대화형 축약 배너 (#446 확정 — 1줄, 로그 오염 최소)
+    printBannerCompact({ version: context.templateVersion, mode: opts.mode });
+
+    // Breaking Changes 게이트 (.sh execute_integration L4415~4420 등가 — 비대화형은 경고 후 진행)
+    const proceed = await runBreakingCheck({ cwd, tempDir, templateVersion: context.templateVersion });
+    if (!proceed) return 0;
+
     switch (opts.mode) {
-      case "full": runFull(context, tempDir, cwd); break;
-      case "version": runVersion(context, tempDir, cwd); break;
-      case "workflows": runWorkflows(context, tempDir, cwd); break;
-      case "issues": runIssues(context, tempDir, cwd); break;
+      case "full": result = runFull(context, tempDir, cwd); break;
+      case "version": result = runVersion(context, tempDir, cwd); break;
+      case "workflows": result = runWorkflows(context, tempDir, cwd); break;
+      case "issues": result = runIssues(context, tempDir, cwd); break;
       default:
         // 알 수 없는 모드 → .sh와 동일하게 복사 0건, 에러 아님
         break;
@@ -104,5 +138,11 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
   } finally {
     remove(tempDir);
   }
+
+  // 완료 요약 (.sh print_summary — CLI 모드에서도 출력)
+  printSummary({
+    mode: opts.mode, types, version,
+    counters: { workflows: result?.workflows?.copied ?? 0, utilModules: 0 },
+  }, cwd);
   return 0;
 }

package/src/ui/ansi.js

@@ -0,0 +1,26 @@
+// 공용 ANSI 헬퍼 — banner/status-cards가 공유 (readline-engine 내부 헬퍼와 독립, 의존성 0)
+const E = "\x1b[";
+export const A = {
+  reset: `${E}0m`,
+  bold: `${E}1m`,
+  dim: `${E}2m`,
+  cyan: `${E}36m`,
+  green: `${E}32m`,
+  yellow: `${E}33m`,
+  magenta: `${E}35m`,
+  gray: `${E}90m`,
+};
+export const paint = (s, color) => `${color}${s}${A.reset}`;
+
+// 대략적 표시 폭 (CJK 2칸 · ANSI 시퀀스 0칸) — 박스 우변 정렬용
+export function visualWidth(s) {
+  const plain = String(s).replace(/\x1b\[[0-9;]*m/g, "");
+  let w = 0;
+  for (const ch of plain) {
+    const cp = ch.codePointAt(0);
+    // 한글·CJK·이모지 대략 2칸 (터미널 관례)
+    w += (cp >= 0x1100 && (cp <= 0x115f || (cp >= 0x2e80 && cp <= 0xa4cf) || (cp >= 0xac00 && cp <= 0xd7a3)
+      || (cp >= 0xf900 && cp <= 0xfaff) || (cp >= 0xff00 && cp <= 0xff60) || cp >= 0x1f300)) ? 2 : 1;
+  }
+  return w;
+}

package/src/ui/banner.js

@@ -0,0 +1,30 @@
+// 첫 화면 배너 (#446 층1) — 클래식 박스형 (사용자 확정 시안 A)
+// .ps1 Print-Banner 계승 + 브랜딩을 projectops로 갱신.
+import { A, paint, visualWidth } from "./ansi.js";
+
+const INNER = 56; // 박스 내부 폭
+
+function boxLine(out, content = "") {
+  const pad = Math.max(0, INNER - visualWidth(content));
+  out(paint("║", A.cyan) + content + " ".repeat(pad) + paint("║", A.cyan) + "\n");
+}
+
+// 대화형 첫 화면 배너 — 박스 타이틀 + 메타 4줄 (.ps1 Print-Banner 등가, #446 확정 시안 A)
+export function printBanner({ version, modeLabel }, out = (s) => process.stdout.write(s)) {
+  out("\n");
+  out(paint(`╔${"═".repeat(INNER)}╗`, A.cyan) + "\n");
+  boxLine(out);
+  boxLine(out, `      ${paint("✦", A.yellow)}  ${paint("P R O J E C T O P S", A.bold)}  ${paint("✦", A.yellow)}`);
+  boxLine(out);
+  out(paint(`╚${"═".repeat(INNER)}╝`, A.cyan) + "\n");
+  out(`     🌙 Version : ${paint(`v${version}`, A.green)}\n`);
+  out(`     🐵 Author  : Cassiiopeia\n`);
+  out(`     🪐 Mode    : ${modeLabel}\n`);
+  out(`     📦 Repo    : ${paint("github.com/Cassiiopeia/projectops", A.dim)}\n`);
+  out("\n");
+}
+
+// 비대화형(--force/CI) 축약 배너 — 1줄 (사용자 확정: 로그 오염 최소 + 버전 추적)
+export function printBannerCompact({ version, mode }, out = (s) => process.stdout.write(s)) {
+  out(`${paint("✦", A.yellow)} ${paint("projectops", A.bold)} v${version} — ${mode} 모드 (--force)\n`);
+}

package/src/ui/env-plan.js

@@ -0,0 +1,207 @@
+// @wizard env 계획 질문 UI (.sh wf_scope_string/wf_collect_asks/_wf_print_field_card/
+// _wf_prefill_all/_wf_prefill_interactive/wf_prompt_env_plan 등가).
+// 실측 기준: template_integrator.sh 3059~3085(scope), 3087~3143(collect), 3152~3169(card),
+//           3220~3280(prompt 본체 wf_prompt_env_plan).
+// io 주입식 — 테스트는 {select, multiselect, text} 스텁을 넘긴다. 기본은 readline-engine 실물.
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { stdin, stderr } from "node:process";
+import { PATHS } from "../core/paths.js";
+import { exists, listYamlFiles } from "../core/fsutil.js";
+import { parseWizardLine, resolveToken } from "../core/wizard-env.js";
+import { loadWizardPrompts, wfField, workflowDisplayName } from "../core/wizard-labels.js";
+import * as engine from "./readline-engine.js";
+
+const CANCEL = engine.CANCEL;
+
+// 진행 안내는 stderr로 출력 (.sh print_to_user가 >&2인 것과 동일 — stdout 파이프 오염 방지).
+const defaultLog = (s = "") => stderr.write(s + "\n");
+
+// 사용처 문자열 조립 (.sh wf_scope_string 등가).
+// usages: [{type, workflowName}] — 타입이 여러 개면 타입만 "t1·t2", 하나면 "타입 name1·name2".
+export function scopeString(usages = []) {
+  const types = []; const names = [];
+  for (const { type, workflowName } of usages) {
+    if (!types.includes(type)) types.push(type);
+    if (!names.includes(workflowName)) names.push(workflowName);
+  }
+  if (types.length > 1) return types.join("·");
+  return `${types.join("·")} ${names.join("·")}`.trim();
+}
+
+// ask KEY 수집 (.sh wf_collect_asks 등가) — 실제 설치되는 워크플로우와 같은 소스를 스캔한다.
+// tempDir: 다운로드 원본 루트. types: 설치 대상 타입 목록.
+// opts:
+//   resolvers    - @접두 기본값(@repo 등) 해석용 (.sh는 수집 시점에 resolve_token — 동일)
+//   includeNexus - true면 server-deploy 제외 + nexus/ 포함 (복사 엔진과 스캔 범위 일치)
+//   prompts      - wizard-labels 파싱 객체 (워크플로우 표시명용, null이면 확장자 제거 폴백)
+// 반환: { keys:[], defaults:Map<key,default>, typeDefaults:Map<"type|key",default>,
+//        usages:Map<key,[{type,workflowName}]> }
+export function collectAsks(tempDir, types = [], opts = {}) {
+  const { resolvers = {}, includeNexus = false, prompts = null } = opts;
+  const baseDir = join(tempDir, PATHS.workflowsDir, PATHS.projectTypesDir);
+  const keys = [];
+  const defaults = new Map();
+  const typeDefaults = new Map();
+  const usages = new Map();
+
+  for (const type of types) {
+    const typeDir = join(baseDir, type);
+    if (!exists(typeDir)) continue;
+    // 복사 엔진과 동일한 폴더 구성: 타입 직하위 + (nexus 아니면) server-deploy + (nexus면) nexus
+    const dirs = [typeDir];
+    if (!includeNexus) dirs.push(join(typeDir, "server-deploy"));
+    else dirs.push(join(typeDir, "nexus"));
+
+    for (const dir of dirs) {
+      if (!exists(dir)) continue;
+      for (const filename of listYamlFiles(dir)) {
+        const content = readFileSync(join(dir, filename), "utf8");
+        if (!content.includes("@wizard")) continue;
+        const workflowName = workflowDisplayName(prompts, filename);
+        for (const line of content.split(/\r?\n/)) {
+          const p = parseWizardLine(line); // KEY 정규식 [A-Z_]+ (.sh와 동일)
+          if (!p || p.action !== "ask") continue;
+          // 타입별 기본값: @접두면 resolver 해석, 아니면 리터럴 (.sh _type_default 등가)
+          const typeDefault = p.arg.startsWith("@")
+            ? resolveToken(p.arg.slice(1), type, resolvers)
+            : p.arg;
+          typeDefaults.set(`${type}|${p.key}`, typeDefault);
+          if (!defaults.has(p.key)) { keys.push(p.key); defaults.set(p.key, typeDefault); }
+          const list = usages.get(p.key) || [];
+          list.push({ type, workflowName });
+          usages.set(p.key, list);
+        }
+      }
+    }
+  }
+  return { keys, defaults, typeDefaults, usages };
+}
+
+// KEY가 처음 등장한 type (.sh _wf_first_type_for — 라벨 조회 시 타입 오버라이드 우선순위용)
+function firstTypeFor(usages, key) {
+  return usages.get(key)?.[0]?.type ?? "";
+}
+
+// KEY 1개를 'label·사용처·설명·예시·기본값' 카드로 출력 (.sh _wf_print_field_card 등가).
+// info: { default, usages } — idx/tot 있으면 "(i/t)" 진행 표시. log 주입 가능(테스트 무음화).
+export function printFieldCard(prompts, key, info, idx = null, tot = null, log = defaultLog) {
+  const t = info.usages?.[0]?.type ?? "";
+  const label = wfField(prompts, t, key, "label");
+  const help = wfField(prompts, t, key, "help");
+  const ex = wfField(prompts, t, key, "example");
+  const scope = scopeString(info.usages || []);
+  const head = idx != null && tot != null
+    ? `   ▸ (${idx}/${tot}) ${label}  [${scope}]`
+    : `   ▸ ${label}  [${scope}]`;
+  log(head);
+  if (help) log(`       ${help}`);
+  if (ex) log(`       예) ${ex}`);
+  log(`       기본값: ${info.default ?? ""}`);
+  log("");
+}
+
+// 지정 KEY들을 하나씩 입력받아 values에 기록 (.sh _wf_prefill_interactive 등가).
+// 빈 입력(Enter)/ESC → KEY 공통 기본값 유지 (.sh safe_read || _in="" 등가).
+async function promptEach(io, prompts, asks, todoKeys, values, log) {
+  const tot = todoKeys.length;
+  if (tot === 0) return;
+  log("");
+  log("   값을 입력하세요. 그대로 두려면 아무것도 입력하지 말고 Enter를 누르면 기본값이 적용됩니다.");
+  log("");
+  let i = 0;
+  for (const key of todoKeys) {
+    i++;
+    const def = asks.defaults.get(key) ?? "";
+    printFieldCard(prompts, key, { default: def, usages: asks.usages.get(key) || [] }, i, tot, log);
+    let input = await io.text({ message: `↳ 값 입력 (Enter=기본값 «${def}» 유지):`, defaultValue: def });
+    if (input === CANCEL || input == null || input === "") input = def;
+    values.set(key, input);
+    const label = wfField(prompts, firstTypeFor(asks.usages, key), key, "label");
+    log(`         → ${label} = ${input}`);
+    log("");
+  }
+}
+
+// 배포 env 설정 계획 (.sh wf_prompt_env_plan 등가).
+// 반환: { values: Map<key,value>, useDefaults: boolean }
+//  - useDefaults=true  → 호출부는 substituteEnv에 그대로 넘기면 타입별 기본값 경로(.sh _wf_prefill_all 등가)
+//  - useDefaults=false → values에 담긴 키만 사용자 확정값으로 치환, 나머지는 기본값
+//    (⚠️ substituteEnv는 useDefaults=false일 때만 values를 참조하므로 이 플래그를 반드시 함께 전달)
+// 인자:
+//   tempDir/types/resolvers/includeNexus — collectAsks와 동일 의미
+//   targetRoot — wizard-prompts.yml 1차 탐색 위치(기본 ".")
+//   force      — true면 질문 없이 전부 기본값 (.sh FORCE_MODE 등가)
+//   io         — {select, multiselect, text} 주입 (기본 readline-engine). 테스트 스텁 지점.
+//   log        — 카드·안내 출력 함수 주입 (기본 stderr)
+export async function promptEnvPlan({
+  tempDir, types = [], io = null, force = false, resolvers = {},
+  includeNexus = false, targetRoot = ".", repoName = "", log = defaultLog,
+} = {}) {
+  const prompts = loadWizardPrompts(targetRoot, tempDir);
+  const asks = collectAsks(tempDir, types, { resolvers, includeNexus, prompts });
+  const defaults = asks.defaults;
+
+  // 수집 키 0개 → 질문 자체가 없음 (.sh `[ ${#WF_ASK_KEYS[@]} -eq 0 ]` 등가)
+  if (asks.keys.length === 0) return { values: new Map(), useDefaults: true };
+
+  // 비대화형: force 또는 (io 미주입 && 비TTY) → 전부 기본값 (.sh FORCE_MODE/TTY_AVAILABLE 분기 등가)
+  // io가 주입돼 있으면(테스트/상위 마법사) TTY 여부와 무관하게 대화형으로 진행한다.
+  const interactive = !force && (io != null || stdin.isTTY);
+  if (!interactive) return { values: new Map(defaults), useDefaults: true };
+
+  const ui = io ?? engine;
+
+  // 기본값 미리보기 카드 전체 출력 (.sh 3237~3251)
+  log("");
+  log("▶ 배포 워크플로우 환경설정을 채웁니다");
+  log("");
+  log("   설치되는 배포 워크플로우가 사용할 값입니다. 항목마다 '무엇에 쓰이는지·설명·예시'와");
+  log("   기본값을 함께 보여드립니다. 그대로 둬도 되고, 원하는 것만 바꿀 수 있습니다.");
+  log("");
+  const tot = asks.keys.length;
+  asks.keys.forEach((key, i) => {
+    printFieldCard(prompts, key, { default: defaults.get(key), usages: asks.usages.get(key) || [] }, i + 1, tot, log);
+  });
+  log("   ─────────────────────────────────────────────");
+
+  const choice = await ui.select({
+    message: "어떻게 채울까요?",
+    options: [
+      { value: "all", label: "① 위 기본값 그대로 전부 설치 (입력 없이 바로 진행)" },
+      { value: "each", label: "② 하나씩 직접 입력 (모든 항목을 순서대로)" },
+      { value: "some", label: "③ 몇 개만 골라서 바꾸기 (고른 것만 입력 · 나머지는 기본값)" },
+    ],
+  });
+  // ESC/취소 → 전부 기본값 (.sh `if [ "$_rc" -ne 0 ]` 등가)
+  if (choice === CANCEL || choice == null || choice === "all") {
+    return { values: new Map(defaults), useDefaults: true };
+  }
+
+  // 사용자가 확정한 키만 values에 담는다 — substituteEnv(useDefaults:false)가
+  // values에 없는 키는 타입별 기본값으로 채우므로 .sh(_wf_prefill_all 후 덮어쓰기)와 등가.
+  const values = new Map();
+  if (choice === "each") {
+    await promptEach(ui, prompts, asks, asks.keys, values, log);
+    return { values, useDefaults: false };
+  }
+
+  // some: 바꿀 항목만 멀티선택 → 고른 것만 입력 (.sh 3266~3277)
+  const options = asks.keys.map((key) => ({
+    value: key,
+    label: `${wfField(prompts, firstTypeFor(asks.usages, key), key, "label")}  (기본: ${defaults.get(key)})`,
+  }));
+  const selected = await ui.multiselect({
+    message: "바꿀 항목을 고르세요 (Space로 선택 · Enter로 확정)",
+    options,
+    initialValues: [],
+  });
+  // ESC/빈 선택 → 전부 기본값 (.sh: _wf_prefill_all만 수행)
+  if (selected === CANCEL || !Array.isArray(selected) || selected.length === 0) {
+    return { values: new Map(defaults), useDefaults: true };
+  }
+  // 수집 키 순서 유지 + WF_ASK_KEYS 멤버만 인정 (.sh _wf_prefill_interactive 필터 등가)
+  const todo = asks.keys.filter((k) => selected.includes(k));
+  await promptEach(ui, prompts, asks, todo, values, log);
+  return { values, useDefaults: false };
+}

package/src/ui/prompts.js

@@ -1,13 +1,13 @@
-// 대화형 프롬프트 래핑 (.sh interactive_menu/choose_menu/ask_* 등가) — @clack/prompts 기반.
+// 대화형 프롬프트 래핑 (.sh interactive_menu/choose_menu/ask_* 등가).
+// node:readline 기반 자체 엔진 사용 (@clack/prompts 는 Windows TTY에서 Enter가 멈추는 버그로 제거).
 // 취소(ESC/Ctrl+C)는 각 함수가 CANCEL 심볼을 반환 → 호출부가 정상 종료(exit 0) 처리.
-import * as clack from "@clack/prompts";
+import * as engine from "./readline-engine.js";
 
-export const CANCEL = Symbol("cancel");
-const wrap = (v) => (clack.isCancel(v) ? CANCEL : v);
+export const CANCEL = engine.CANCEL;
 
 // 모드 선택 — 한국어 라벨, 내부 키 반환. 취소 시 CANCEL.
 export async function selectMode() {
-  const v = await clack.select({
+  return engine.select({
     message: "무엇을 설치할까요?",
     options: [
       { value: "full", label: "전체 설치 — 버전관리 + 자동화 워크플로우 + 이슈·PR 템플릿 (처음이라면 추천)" },
@@ -17,12 +17,11 @@ export async function selectMode() {
       { value: "skills", label: "AI 스킬만 — Claude·Cursor·Gemini·Codex·PI용 스킬만 설치" },
     ],
   });
-  return wrap(v);
 }
 
 // 프로젝트 확인 화면 메뉴 (계속/수정/취소).
 export async function confirmProjectMenu() {
-  const v = await clack.select({
+  return engine.select({
     message: "이 정보로 진행할까요?",
     options: [
       { value: "continue", label: "예, 계속 진행" },
@@ -30,7 +29,6 @@ export async function confirmProjectMenu() {
       { value: "cancel", label: "아니오, 취소" },
     ],
   });
-  return wrap(v);
 }
 
 // 수정 메뉴 — 어떤 항목을 고칠지. showOptional=full/workflows에서만 nexus/secret 노출.
@@ -45,38 +43,60 @@ export async function editMenu({ showOptional = false } = {}) {
     options.push({ value: "secret", label: "Secret 백업 포함 여부" });
   }
   options.push({ value: "done", label: "모두 맞음, 계속" });
-  const v = await clack.select({ message: "어떤 항목을 수정할까요?", options });
-  return wrap(v);
+  return engine.select({ message: "어떤 항목을 수정할까요?", options });
 }
 
 // 타입 멀티선택.
 export async function selectTypes(current = []) {
   const all = ["spring", "flutter", "next", "react", "react-native", "react-native-expo", "node", "python", "basic"];
-  const v = await clack.multiselect({
+  return engine.multiselect({
     message: "프로젝트 타입을 선택하세요 (Space 토글, Enter 확정)",
     options: all.map((t) => ({ value: t, label: t })),
     initialValues: current.length ? current : ["basic"],
     required: true,
   });
-  return wrap(v);
 }
 
 // 텍스트 입력 (빈 입력=기본값 유지).
 export async function askText(message, defaultValue = "") {
-  const v = await clack.text({ message, placeholder: defaultValue, defaultValue });
-  const w = wrap(v);
-  if (w === CANCEL) return CANCEL;
-  return w === "" || w == null ? defaultValue : w;
+  const v = await engine.text({ message, defaultValue });
+  if (v === CANCEL) return CANCEL;
+  return v === "" || v == null ? defaultValue : v;
 }
 
 // 예/아니오.
 export async function askYesNo(message, initial = true) {
-  const v = await clack.confirm({ message, initialValue: initial });
-  return wrap(v);
+  return engine.confirm({ message, initialValue: initial });
 }
 
 // 배너·안내 출력.
-export function intro(text) { clack.intro(text); }
-export function outro(text) { clack.outro(text); }
-export function note(text, title) { clack.note(text, title); }
-export function cancelMessage(text = "취소했습니다.") { clack.cancel(text); }
+export function intro(text) { engine.intro(text); }
+export function outro(text) { engine.outro(text); }
+export function note(text, title) { engine.note(text, title); }
+export function cancelMessage(text = "취소했습니다.") { engine.cancelMessage(text); }
+
+// ── #446 첫 화면 UI 5층 + SP2-C 대화형 계층 실물 io ─────────────────
+// runInteractive는 io.<method>?.() 옵셔널 호출 — 테스트 스텁은 이 메서드들을 생략해
+// 시각 층·env 질문을 건너뛴다 (실행 계약은 그대로).
+import { printBanner as _printBanner } from "./banner.js";
+import {
+  printDetectionLog as _detLog, printAnalysisCard as _card,
+  printIdeStatus as _ideStatus, printInstallKind as _installKind, collectIdeStatuses,
+} from "./status-cards.js";
+import { printSummary as _summary } from "./summary.js";
+import { defaultIo } from "../core/ide/runner.js";
+
+export function banner(info) { _printBanner(info); }
+export function detectionLog(info) { _detLog(info); }
+export function analysisCard(info) { _card(info); }
+export function installKind(info) { _installKind(info); }
+export function ideStatus() { _ideStatus(collectIdeStatuses(defaultIo())); }
+export function summary(ctx, targetRoot) { _summary(ctx, targetRoot); }
+
+// env 계획·경로 해석·충돌 메뉴가 쓰는 저수준 엔진 io (env-plan/paths-resolve의 io 계약)
+export const engineIo = {
+  select: engine.select,
+  multiselect: engine.multiselect,
+  text: engine.text,
+  confirm: engine.confirm,
+};