@rch4com/agent-setup 1.0.0

package/lib/tui/render.mjs

@@ -0,0 +1,192 @@
+// 순수 렌더 — 상태와 크기를 받아 화면 줄 배열을 돌려준다.
+// 커서 이동·지우기 같은 제어 시퀀스는 run.mjs가 맡는다.
+import { displayList, tabCounts, activeTab } from './state.mjs'
+
+const ESC = String.fromCharCode(27)
+const DIM = `${ESC}[2m`
+const BOLD = `${ESC}[1m`
+const REVERSE = `${ESC}[7m`
+const RESET = `${ESC}[0m`
+
+// 머리글·탭줄·검색줄·구분 공백·바닥글이 차지하는 줄 수.
+const CHROME = 6
+const LABEL_WIDTH = 24
+
+export function bodyHeight(height) {
+  return Math.max(3, height - CHROME)
+}
+
+// 동아시아 글자는 터미널에서 두 칸을 차지한다. 전체 wcwidth 표 대신
+// 실제로 쓰이는 구간(한글·한자·가나·전각)만 넓게 센다 — 액션 행 라벨이 전부 한글이라
+// 한 칸씩 밀리면 첫 화면부터 열이 어긋난다.
+function charWidth(cp) {
+  return (cp >= 0x1100 && cp <= 0x115f) // 한글 자모
+    || (cp >= 0x2e80 && cp <= 0xa4cf) // 한자 부수·가나·한자
+    || (cp >= 0xac00 && cp <= 0xd7a3) // 한글 음절
+    || (cp >= 0xf900 && cp <= 0xfaff) // 한자 호환
+    || (cp >= 0xfe30 && cp <= 0xfe6f) // 전각 형태
+    || (cp >= 0xff00 && cp <= 0xff60) // 전각 영숫자
+    || (cp >= 0xffe0 && cp <= 0xffe6)
+    ? 2 : 1
+}
+
+export function width(text) {
+  let w = 0
+  for (const ch of String(text ?? '')) w += charWidth(ch.codePointAt(0))
+  return w
+}
+
+// 색 코드는 폭에 포함되면 안 되므로, 자르기는 항상 색을 입히기 **전에** 한다.
+export function cut(text, limit) {
+  if (limit <= 0) return ''
+  const s = String(text ?? '')
+  if (width(s) <= limit) return s
+  let out = ''
+  let w = 0
+  for (const ch of s) {
+    const cw = charWidth(ch.codePointAt(0))
+    if (w + cw > limit - 1) break
+    out += ch
+    w += cw
+  }
+  return `${out}…`
+}
+
+function pad(text, limit) {
+  const s = cut(text, limit)
+  return s + ' '.repeat(Math.max(0, limit - width(s)))
+}
+
+const MARK = { action: '▶', on: '×', off: ' ' }
+
+function checkbox(row, selected) {
+  if (row.kind === 'action') return `[${MARK.action}]`
+  return `[${selected.has(row.id) ? MARK.on : MARK.off}]`
+}
+
+// 탭 줄. 검색 중이면 탭마다 적중 수를 보여 준다 —
+// 검색은 활성 탭 안으로만 걸리므로, 다른 탭에 결과가 있다는 사실을 여기서 알린다.
+// 폭이 모자라면 활성 탭 하나 + 위치 표시로 줄인다(줄바꿈은 화면을 무너뜨린다).
+export function tabBar(state, { width: limit, color = false, searching = false } = {}) {
+  const counts = tabCounts(state)
+  if (counts.length === 0) return ''
+  const active = activeTab(state)
+
+  const segs = counts.map(({ tab, shown, total }) => ({
+    tab,
+    text: searching ? `${tab} ${shown}/${total}` : `${tab} ${total}`,
+    active: tab === active,
+    empty: searching && shown === 0,
+  }))
+
+  const SEP = '  '
+  const plain = segs.map((s) => s.text).join(SEP)
+  if (width(plain) > limit) {
+    const i = segs.findIndex((s) => s.active)
+    const compact = `‹ ${segs[i]?.text ?? ''} ›  ${i + 1}/${segs.length}`
+    return color ? `${BOLD}${cut(compact, limit)}${RESET}` : cut(compact, limit)
+  }
+  if (!color) return segs.map((s) => (s.active ? `[${s.text}]` : ` ${s.text} `)).join('')
+  return segs
+    .map((s) => (s.active ? `${REVERSE} ${s.text} ${RESET}` : s.empty ? `${DIM} ${s.text} ${RESET}` : ` ${s.text} `))
+    .join('')
+}
+
+// 검색줄 = 하나의 입력칸이다. 포커스가 여기 있으면 입력 커서(▌)로 드러내고,
+// 컬러에서는 줄 전체를 반전시켜 "지금 여기에 타이핑된다"를 분명히 한다 —
+// 이 상태에서만 스페이스가 선택이 아니라 검색어로 들어가기 때문이다.
+function searchLine(state, { limit, color, paint }) {
+  const prefix = '검색 › '
+  const room = Math.max(0, limit - width(prefix))
+  if (state.focus === 'search') {
+    const text = `${prefix}${cut(`${state.query}▌`, room)}`
+    return color ? `${REVERSE}${pad(text, limit)}${RESET}` : text
+  }
+  if (state.query) return `${prefix}${cut(state.query, room)}`
+  return `${prefix}${paint(DIM, cut('타이핑하면 검색 · ↓ 로 목록', room))}`
+}
+
+export function render(state, opts = {}) {
+  // columns로 받는다 — width로 두면 모듈의 width() 함수를 함수 스코프 전체에서 가린다.
+  const { width: columns = 80, height = 24, repo = '', dryRun = false, color = false, status = '' } = opts
+
+  // 마지막 칸은 비워 둔다 — 폭을 꽉 채우면 터미널이 줄을 넘긴다.
+  const w = Math.max(24, columns - 1)
+  const paint = (code, text) => (color ? `${code}${text}${RESET}` : text)
+
+  const items = state.rows.filter((r) => r.kind === 'item')
+  const picked = items.filter((r) => state.selected.has(r.id)).length
+
+  const title = `agent-installer${dryRun ? ' (dry-run)' : ''}`
+  const counts = `선택 ${picked} / 전체 ${items.length}`
+  const head = cut(`${title}  ${counts}  ${repo}`, w)
+  const searching = String(state.query ?? '').trim() !== ''
+
+  const lines = [
+    color ? `${BOLD}${title}${RESET}${cut(`  ${counts}  ${repo}`, Math.max(0, w - width(title)))}` : head,
+    tabBar(state, { width: w, color, searching }),
+    searchLine(state, { limit: w, color, paint }),
+    '',
+  ]
+
+  const body = bodyHeight(height)
+  const all = displayList(state)
+
+  if (all.length === 0) {
+    lines.push(paint(DIM, cut(searching ? '  이 탭에는 일치하는 항목이 없습니다. Tab으로 다른 탭을 보세요.' : '  항목이 없습니다.', w)))
+    for (let i = 1; i < body; i++) lines.push('')
+  } else {
+    const window = all.slice(state.offset, state.offset + body)
+    for (const entry of window) {
+      if (entry.type === 'header') {
+        const count = entry.shown === entry.total ? `${entry.total}` : `${entry.shown}/${entry.total}`
+        lines.push(paint(DIM, cut(`  ${entry.section} (${count})`, w)))
+        continue
+      }
+      const { row, index } = entry
+      const here = index === state.cursor
+      const hintWidth = Math.max(0, w - LABEL_WIDTH - 6)
+      const text = cut(`${here ? '❯' : ' '} ${checkbox(row, state.selected)} ${pad(row.label, LABEL_WIDTH)} ${cut(row.hint, hintWidth)}`, w)
+      lines.push(here ? paint(REVERSE, text) : text)
+    }
+    for (let i = window.length; i < body; i++) lines.push('')
+  }
+
+  const hint = state.focus === 'search'
+    ? '입력=검색어(스페이스 포함)   ↓ 목록으로   Tab 탭이동   Esc 검색해제'
+    : 'Space 선택   ↑↓ 이동(맨 위 ↑=검색칸)   Tab 탭   Enter 실행/제출   Ctrl+A 전체   Ctrl+O 미리보기'
+  lines.push('')
+  lines.push(paint(DIM, cut(status || hint, w)))
+  return lines
+}
+
+const CHANGE_MARK = { install: '+', complete: '±', uninstall: '−' }
+const CHANGE_LABEL = { install: '설치', complete: '보완 설치', uninstall: '제거' }
+
+// 제출 검토 화면 — 적용 직전에 무엇이 바뀌는지만 보여 준다.
+// 목록이 길면 잘라내고 남은 건수를 알린다(스크롤 대신) — 여기서 길을 잃을 이유는 없다.
+export function renderReview(changes, opts = {}) {
+  const { width: columns = 80, height = 24, dryRun = false, color = false } = opts
+  const w = Math.max(24, columns - 1)
+  const paint = (code, text) => (color ? `${code}${text}${RESET}` : text)
+
+  const title = `제출 검토 — 변경 ${changes.length}건${dryRun ? ' (dry-run)' : ''}`
+  const lines = [color ? `${BOLD}${cut(title, w)}${RESET}` : cut(title, w), '']
+
+  const body = bodyHeight(height)
+  const room = Math.max(1, body - 1)
+  const shown = changes.slice(0, room)
+  for (const c of shown) {
+    lines.push(cut(`  ${CHANGE_MARK[c.action] ?? '?'} ${pad(CHANGE_LABEL[c.action] ?? c.action, 10)} ${c.item.label}`, w))
+  }
+  if (changes.length > shown.length) {
+    lines.push(paint(DIM, cut(`  …외 ${changes.length - shown.length}건`, w)))
+  } else {
+    lines.push('')
+  }
+  for (let i = shown.length + 1; i < body; i++) lines.push('')
+
+  lines.push('')
+  lines.push(paint(DIM, cut('Enter 적용   Esc 취소', w)))
+  return lines
+}

package/lib/tui/rows.mjs

@@ -0,0 +1,206 @@
+// 부트스트랩·에이전트·design.md를 하나의 행 배열로 합친다.
+// 화면을 모른다 — 폭도 색도 커서도 여기서는 다루지 않는다.
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { scan } from '../engine.mjs'
+import { loadItems } from '../catalog.mjs'
+import { runBootstrap } from '../bootstrap/flow.mjs'
+import { MANIFEST } from '../bootstrap/manifest.mjs'
+import { loadCatalog, buildItems, netFetch, CATALOG_PATH } from '../design-md/catalog.mjs'
+import { discoverSources, extraDirsFromEnv } from '../design-md/scan.mjs'
+import { refreshCatalog, updateInstalled, findStale } from '../design-md/flow.mjs'
+
+const AGENT_SECTION = { plugin: 'PLUGIN', mcp: 'MCP', skill: 'SKILL' }
+const STATUS_LABEL = { installed: '설치됨', partial: '일부 설치됨', absent: '미설치' }
+const DESIGN_STATUS = { installed: '설치됨', partial: '일부', absent: '미설치' }
+
+export const ACTION_SECTION = '작업'
+// scan.mjs의 BUNDLE_CATEGORY와 같은 값이다 — 카테고리를 못 얻은 항목이 모이는 자리.
+export const CATCH_ALL_CATEGORY = '기타'
+export const SECTION_ORDER = [ACTION_SECTION, 'PLUGIN', 'MCP', 'SKILL', 'DESIGN.MD']
+
+function short(text, n = 60) {
+  const t = (text ?? '').replace(/\s+/g, ' ').trim()
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t
+}
+
+// 에이전트 항목 힌트 — 상태·설치 위치·미지원 CLI 사유까지 한 줄에 담는다.
+export function agentHint(item, state) {
+  const parts = []
+  if (state.status !== 'absent') parts.push(STATUS_LABEL[state.status])
+  if (state.detail) parts.push(state.detail)
+  if (item.scope === 'user') parts.push('설치 위치: 사용자 글로벌')
+  const un = Object.entries(item.unsupported ?? {})
+  if (item.category === 'mcp' && un.length > 0) {
+    parts.push(`미지원: ${un.map(([cli, why]) => `${cli}(${why})`).join(', ')}`)
+  }
+  if (item.supports?.length === 1 && item.supports[0] === 'claude') parts.push('Claude Code 전용')
+  if (item.note) parts.push(item.note)
+  return parts.join(' · ')
+}
+
+export function designHint(state, multiProvider = false) {
+  const parts = []
+  if (multiProvider) parts.push(state.item.providerId)
+  parts.push(state.item.designCategory)
+  if (state.status !== 'absent') parts.push(DESIGN_STATUS[state.status])
+  if (state.item.description) parts.push(short(state.item.description))
+  return parts.filter(Boolean).join(' · ')
+}
+
+// group = 탭 **안쪽**의 소분류 헤더. design.md만 76개라 카테고리로 갈라야 읽힌다.
+// 나머지 탭은 항목이 적어 그룹 없이 평평하게 둔다.
+function itemRow({ id, section, label, hint, status, previewTarget = null, item, extra = '', group = null }) {
+  return {
+    kind: 'item',
+    id,
+    section,
+    group,
+    label,
+    hint,
+    status,
+    previewTarget,
+    item,
+    searchText: `${label} ${hint} ${section} ${extra}`.toLowerCase(),
+  }
+}
+
+function actionRow({ id, label, hint, run }) {
+  return {
+    kind: 'action',
+    id,
+    section: ACTION_SECTION,
+    group: null,
+    label,
+    hint,
+    status: 'absent',
+    previewTarget: null,
+    run,
+    searchText: `${label} ${hint} ${ACTION_SECTION}`.toLowerCase(),
+  }
+}
+
+// 부트스트랩이 만들 파일 중 이미 있는 수 — 실행 전에 무엇이 남았는지 알려 준다.
+function bootstrapHint(root) {
+  const present = MANIFEST.files.filter((f) => existsSync(join(root, f.path))).length
+  return `지침 · 스킬 · 도구별 설정 · 파일 ${MANIFEST.files.length}개 중 ${present}개 존재`
+}
+
+export function buildActions(root, { designItems = [] } = {}) {
+  return [
+    actionRow({
+      id: 'action.bootstrap',
+      label: '부트스트랩 실행',
+      hint: bootstrapHint(root),
+      run: ({ dryRun, skillMode, log }) => runBootstrap(root, { dryRun, skillMode, log }),
+    }),
+    actionRow({
+      id: 'action.sync.installed',
+      label: '설치본 업데이트',
+      hint: 'design.md 설치본을 원본 최신으로 다시 받는다',
+      run: ({ dryRun, log }) => updateInstalled(root, designItems, { dryRun, log }),
+    }),
+    actionRow({
+      id: 'action.sync.catalog',
+      label: '카탈로그 새로고침',
+      hint: 'design.md 목록·카테고리를 소스에서 다시 만든다',
+      run: ({ dryRun, fetchImpl, log, catalogFile }) => refreshCatalog({ dryRun, fetchImpl, log, catalogFile }),
+    }),
+    actionRow({
+      id: 'action.sync.stale',
+      label: '오래된 항목 확인',
+      hint: '설치본을 원본과 해시 비교한다',
+      run: async ({ dryRun, log, confirm }) => {
+        const stale = await findStale(root, designItems, { log })
+        if (stale.length === 0) { log('모든 설치본이 최신입니다.'); return }
+        log(`오래된 항목 ${stale.length}개: ${stale.map((i) => i.name).join(', ')}`)
+        if (dryRun) return
+        if (!(await confirm(`${stale.length}개를 지금 업데이트할까요?`))) return
+        for (const item of stale) {
+          try {
+            await item.install({ root, dryRun, fresh: true })
+            log(`  ✔ 업데이트 ${item.label}`)
+          } catch (err) {
+            log(`  ✖ 업데이트 ${item.label} — ${err.message}`)
+          }
+        }
+      },
+    }),
+  ]
+}
+
+// 순수 조립 — 이미 스캔된 상태를 받아 행 배열을 만든다. 테스트는 여기를 겨눈다.
+export function buildRows({ actions = [], agentStates = [], designStates = [], multiProvider = false }) {
+  const agents = agentStates.map((s) =>
+    itemRow({
+      id: s.item.id,
+      section: AGENT_SECTION[s.item.category] ?? s.item.category.toUpperCase(),
+      label: s.item.label,
+      hint: agentHint(s.item, s),
+      status: s.status,
+      item: s.item,
+      extra: s.item.id,
+    }),
+  )
+
+  // 카테고리 → 라벨 순으로 정렬한다. 그룹 헤더는 인접한 같은 group을 하나로 묶으므로
+  // 정렬이 흐트러지면 같은 카테고리가 여러 번 쪼개져 나온다.
+  const designs = designStates
+    .map((s) =>
+      itemRow({
+        id: s.item.id,
+        section: 'DESIGN.MD',
+        group: s.item.designCategory || CATCH_ALL_CATEGORY,
+        label: s.item.label,
+        hint: designHint(s, multiProvider),
+        status: s.status,
+        previewTarget: s.item.webUrl ?? s.item.previewPath ?? null,
+        item: s.item,
+        extra: `${s.item.name} ${s.item.providerId}`,
+      }),
+    )
+    // 분류 못 한 항목을 모아 둔 '기타'는 맨 뒤로 보낸다 — catch-all이 목록 머리를 차지하면
+    // 실제 카테고리를 훑기 전에 잡동사니부터 읽게 된다.
+    .sort((a, b) =>
+      (a.group === CATCH_ALL_CATEGORY ? 1 : 0) - (b.group === CATCH_ALL_CATEGORY ? 1 : 0)
+      || a.group.localeCompare(b.group)
+      || a.label.localeCompare(b.label))
+
+  const rows = [...actions, ...agents, ...designs]
+  // 섹션 순서를 고정한다 — displayList가 인접한 같은 섹션을 하나로 묶기 때문이다.
+  return rows.sort((a, b) => SECTION_ORDER.indexOf(a.section) - SECTION_ORDER.indexOf(b.section))
+}
+
+// 스캔까지 포함한 수집. 적용·액션 실행 뒤 다시 부른다.
+export async function collectRows(root, opts = {}) {
+  const { fetchImpl = netFetch, designDirs = [], env = process.env, catalogFile = CATALOG_PATH, log = () => {} } = opts
+
+  const agentItems = await loadItems()
+  const catalog = loadCatalog(catalogFile)
+  const sources = opts.sources ?? discoverSources({
+    ...(opts.bundleDir ? { bundleDir: opts.bundleDir } : {}),
+    extraDirs: [...extraDirsFromEnv(env), ...designDirs],
+    log,
+  })
+  const designItems = buildItems(catalog, { fetchImpl, sources })
+
+  const [agentStates, designStates] = await Promise.all([scan(root, agentItems), scan(root, designItems)])
+  const multiProvider = new Set(designItems.map((i) => i.providerId)).size > 1
+
+  return {
+    rows: buildRows({
+      actions: buildActions(root, { designItems }),
+      agentStates,
+      designStates,
+      multiProvider,
+    }),
+    agentStates,
+    designStates,
+    designItems,
+  }
+}
+
+// 설치된 항목 = 시작 시 체크된 항목.
+export function installedIds(rows) {
+  return rows.filter((r) => r.kind === 'item' && r.status !== 'absent').map((r) => r.id)
+}

package/lib/tui/run.mjs

@@ -0,0 +1,257 @@
+// 유일한 부수효과 지점 — 키 입력, 화면 그리기, 액션 실행, 적용.
+// 무엇을 보여줄지(render)와 무엇이 선택됐는지(state)는 순수 모듈이 정한다.
+import { emitKeypressEvents } from 'node:readline'
+import { planChanges, apply } from '../engine.mjs'
+import { makeOpener, openPreview } from '../design-md/open.mjs'
+import { netFetch, CATALOG_PATH } from '../design-md/catalog.mjs'
+import { collectRows, installedIds } from './rows.mjs'
+import {
+  createState, setQuery, setFocus, move, moveTab, toggle, toggleVisible, scroll, currentRow, replaceRows, activeTab,
+} from './state.mjs'
+import { render, renderReview, bodyHeight } from './render.mjs'
+
+const ESC = String.fromCharCode(27)
+const HIDE_CURSOR = `${ESC}[?25l`
+const SHOW_CURSOR = `${ESC}[?25h`
+const ALT_ON = `${ESC}[?1049h`
+const ALT_OFF = `${ESC}[?1049l`
+const HOME = `${ESC}[H`
+const CLEAR_LINE = `${ESC}[K`
+const CLEAR_DOWN = `${ESC}[J`
+
+const ACTION_LABEL = { install: '설치', complete: '보완 설치', uninstall: '제거' }
+
+// 키를 큐에 쌓아 두고 하나씩 꺼내 쓴다. 이벤트 상태 기계 대신
+// `for(;;) await next()` 루프로 흐름을 읽을 수 있게 하기 위해서다.
+function keyReader(stdin) {
+  const queue = []
+  let waiting = null
+  const onKey = (str, key) => {
+    const event = { str, ...(key ?? {}) }
+    if (waiting) { const resolve = waiting; waiting = null; resolve(event) }
+    else queue.push(event)
+  }
+  stdin.on('keypress', onKey)
+  return {
+    next: () => (queue.length > 0 ? Promise.resolve(queue.shift()) : new Promise((r) => { waiting = r })),
+    stop: () => stdin.off('keypress', onKey),
+  }
+}
+
+function itemStates(rows) {
+  return rows.filter((r) => r.kind === 'item').map((r) => ({ item: r.item, status: r.status }))
+}
+
+function printPlain(rows, log) {
+  let section = null
+  for (const row of rows) {
+    if (row.section !== section) { section = row.section; log(`[${section}]`) }
+    const mark = row.kind === 'action' ? '▶' : row.status === 'absent' ? ' ' : '×'
+    log(`  [${mark}] ${row.label}${row.hint ? ` — ${row.hint}` : ''}`)
+  }
+}
+
+// 화면에 찍히는 글자인가(스페이스 포함). 검색칸 포커스에서 검색어로 들어갈 후보다.
+// 스페이스의 뜻은 포커스가 가른다: 검색칸에서는 검색어, 목록에서는 선택.
+// 그래서 목록에서 타이핑으로 검색칸에 올라갈 때는 호출부에서 스페이스를 뺀다.
+function isPrintable(key) {
+  return Boolean(key.str) && !key.ctrl && !key.meta && key.str >= ' ' && key.str !== ESC
+}
+
+export async function runTui(root, opts = {}) {
+  const {
+    dryRun = false,
+    skillMode = 'auto',
+    fetchImpl = netFetch,
+    designDirs = [],
+    env = process.env,
+    catalogFile = CATALOG_PATH,
+    log = console.log,
+    stdin = process.stdin,
+    stdout = process.stdout,
+  } = opts
+  const opener = opts.opener ?? makeOpener(dryRun, log)
+
+  let collected = await collectRows(root, { fetchImpl, designDirs, env, catalogFile, log: () => {} })
+
+  // raw 모드를 켤 수 없으면(CI·파이프) 목록만 내고 끝낸다.
+  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') {
+    printPlain(collected.rows, log)
+    log('\n대화형 화면은 터미널에서만 열립니다. --list · --set 으로도 다룰 수 있습니다.')
+    return { interactive: false }
+  }
+
+  // 처음엔 목록에 포커스를 둔다 — 곧바로 화살표 이동·Space 선택·Enter 실행이 되게.
+  // 타이핑하면 검색칸으로 올라간다.
+  let state = createState(collected.rows, { selectedIds: installedIds(collected.rows), focus: 'list' })
+  let status = ''
+
+  emitKeypressEvents(stdin)
+  stdin.setRawMode(true)
+  stdin.resume()
+  const keys = keyReader(stdin)
+  stdout.write(ALT_ON + HIDE_CURSOR)
+
+  const color = !env.NO_COLOR && stdout.isTTY
+  const draw = (lines) => stdout.write(HOME + lines.map((l) => l + CLEAR_LINE).join('\n') + '\n' + CLEAR_DOWN)
+  const paint = () => {
+    const height = stdout.rows ?? 24
+    state = scroll(state, bodyHeight(height))
+    draw(render(state, { width: stdout.columns ?? 80, height, repo: root, dryRun, color, status }))
+  }
+
+  // 로그는 화면 안에 우겨넣지 않는다 — 실패 메시지가 길고, 잘리면 진단이 불가능해진다.
+  const suspend = async (fn) => {
+    stdout.write(ALT_OFF + SHOW_CURSOR)
+    try { return await fn() } finally { stdout.write(ALT_ON + HIDE_CURSOR) }
+  }
+  const confirm = async (message) => {
+    stdout.write(`\n${message} [y/N] `)
+    const key = await keys.next()
+    stdout.write('\n')
+    return String(key.str ?? '').toLowerCase() === 'y'
+  }
+  const pause = async () => {
+    stdout.write('\n계속하려면 아무 키나 누르세요…')
+    await keys.next()
+  }
+
+  const recollect = async () => {
+    collected = await collectRows(root, { fetchImpl, designDirs, env, catalogFile, log: () => {} })
+    state = replaceRows(state, collected.rows, installedIds(collected.rows))
+  }
+
+  const select = () => {
+    const row = currentRow(state)
+    if (row?.kind !== 'item') return '이 행은 Enter로 실행합니다.'
+    state = toggle(state)
+    return ''
+  }
+
+  // 미리보기는 두 포커스에서 모두 통해야 한다 — 검색으로 찾은 직후가 가장 열어 보고 싶은 순간이다.
+  const preview = () => {
+    const row = currentRow(state)
+    if (row?.kind !== 'item' || !row.previewTarget) return '이 항목은 미리보기를 제공하지 않습니다.'
+    const notes = []
+    openPreview(opener, row.item, (m) => notes.push(String(m).trim()))
+    return notes.length > 0 ? notes.join(' ') : `열었습니다: ${row.previewTarget}`
+  }
+
+  // 제출 검토 — 적용 직전에 변경 목록을 보여 주고 Enter/Esc만 받는다.
+  const review = async (changes) => {
+    for (;;) {
+      draw(renderReview(changes, { width: stdout.columns ?? 80, height: stdout.rows ?? 24, dryRun, color }))
+      const key = await keys.next()
+      if (key.ctrl && key.name === 'c') return 'quit'
+      if (key.name === 'escape') return 'cancel'
+      if (key.name === 'return' || key.name === 'enter') return 'apply'
+    }
+  }
+
+  try {
+    for (;;) {
+      paint()
+      const key = await keys.next()
+      status = ''
+
+      if (key.ctrl && key.name === 'c') break
+
+      // ── 검색칸에 포커스: 타이핑이 곧 검색어다(스페이스 포함, 두 단어 검색 가능).
+      if (state.focus === 'search') {
+        // Esc: 검색어가 있으면 지우고 검색칸에 남는다. 이미 비었으면 목록으로 내려간다.
+        if (key.name === 'escape') {
+          state = state.query ? setQuery(state, '') : setFocus(state, 'list')
+          continue
+        }
+        // Enter·↓: 검색을 마치고 목록으로 내려간다. 결과의 첫 항목이 커서다.
+        if (key.name === 'return' || key.name === 'enter' || key.name === 'down') { state = setFocus(state, 'list'); continue }
+        if (key.name === 'backspace') { state = setQuery(state, state.query.slice(0, -1)); continue }
+        if (key.name === 'tab') { state = moveTab(state, key.shift ? -1 : 1); continue }
+        if (key.ctrl && key.name === 'o') { status = preview(); continue }
+        if (isPrintable(key)) state = setQuery(state, state.query + key.str)
+        continue
+      }
+
+      // ── 목록에 포커스
+      if (key.name === 'escape') {
+        if (state.query) { state = setQuery(state, ''); continue }
+        break
+      }
+
+      // / 또는 글자를 누르면 검색칸으로 올라가 타이핑을 시작한다. 스페이스는 선택이므로 제외한다.
+      if (key.str === '/') { state = setFocus(state, 'search'); continue }
+      if (key.name !== 'space' && isPrintable(key)) {
+        state = setQuery(setFocus(state, 'search'), state.query + key.str)
+        continue
+      }
+
+      // 맨 위에서 ↑를 누르면 검색칸으로 되돌아간다 — 목록과 검색칸이 위아래로 이어진 느낌.
+      if (key.name === 'up' || (key.ctrl && key.name === 'p')) {
+        state = state.cursor === 0 ? setFocus(state, 'search') : move(state, -1)
+        continue
+      }
+      if (key.name === 'down' || (key.ctrl && key.name === 'n')) { state = move(state, 1); continue }
+      if (key.name === 'pageup') { state = move(state, -bodyHeight(stdout.rows ?? 24)); continue }
+      if (key.name === 'pagedown') { state = move(state, bodyHeight(stdout.rows ?? 24)); continue }
+
+      // 탭 이동 — Tab/Shift+Tab, 좌우 화살표.
+      if (key.name === 'tab') { state = moveTab(state, key.shift ? -1 : 1); continue }
+      if (key.name === 'right') { state = moveTab(state, 1); continue }
+      if (key.name === 'left') { state = moveTab(state, -1); continue }
+
+      // 선택 토글 — 액션 행에서는 아무 일도 하지 않는다(제거 개념이 없다).
+      if (key.name === 'space') { status = select(); continue }
+
+      // 지금 탭에서 보이는 항목 전체 토글.
+      if (key.ctrl && key.name === 'a') {
+        const before = state.selected.size
+        state = toggleVisible(state)
+        status = `${activeTab(state)} 탭의 보이는 항목을 ${state.selected.size >= before ? '모두 선택' : '모두 해제'}했습니다.`
+        continue
+      }
+
+      if (key.ctrl && key.name === 'o') { status = preview(); continue }
+
+      if (key.name === 'return' || key.name === 'enter') {
+        // 액션 행은 그 자리에서 실행한다. 나머지는 제출(검토 → 일괄 적용)이다.
+        const row = currentRow(state)
+        if (row?.kind === 'action') {
+          await suspend(async () => {
+            await row.run({ root, dryRun, skillMode, fetchImpl, catalogFile, log, confirm })
+            await pause()
+          })
+          await recollect()
+          continue
+        }
+
+        const changes = planChanges(itemStates(state.rows), state.selected)
+        if (changes.length === 0) { status = '변경할 항목이 없습니다.'; continue }
+
+        const verdict = await review(changes)
+        if (verdict === 'quit') break
+        if (verdict === 'cancel') { status = '제출을 취소했습니다.'; continue }
+
+        await suspend(async () => {
+          log(`\n적용할 변경 ${changes.length}건${dryRun ? ' (dry-run)' : ''}:`)
+          for (const c of changes) log(`  ${ACTION_LABEL[c.action]} ${c.item.label}`)
+          const results = await apply(root, changes, { dryRun, log })
+          for (const r of results) log(`  ${r.ok ? '✔' : '✖'} ${ACTION_LABEL[r.action]} ${r.item.label}${r.message ? ` — ${r.message}` : ''}`)
+          if (results.some((r) => !r.ok)) process.exitCode = 1
+          log('\n설정 파일 변경 내용은 git diff로 확인할 수 있습니다.')
+          await pause()
+        })
+        await recollect()
+        continue
+      }
+    }
+  } finally {
+    keys.stop()
+    stdout.write(ALT_OFF + SHOW_CURSOR)
+    stdin.setRawMode(false)
+    stdin.pause()
+  }
+
+  return { interactive: true }
+}
+
+export { printPlain, itemStates }