@rch4com/agent-setup 1.3.0 → 1.5.0

package/install.mjs

@@ -52,6 +52,7 @@ async function openTui(root, { dryRun, skillMode, designDirs, t, localeForced })
 async function runClassic(root, { dryRun, listOnly, setArg, t }) {
   const { loadItems } = await withDeps(() => import('./lib/catalog.mjs'), t)
   const { scan, planChanges, apply } = await withDeps(() => import('./lib/engine.mjs'), t)
+  const { plainLine } = await withDeps(() => import('./lib/tui/progress.mjs'), t)
   const items = await loadItems()
   const states = await scan(root, items)
   const statusWidth = labelWidth(t, STATUS_KEYS)
@@ -71,7 +72,16 @@ async function runClassic(root, { dryRun, listOnly, setArg, t }) {
   const changes = planChanges(states, selectedIds)
   if (changes.length === 0) { console.log(t('apply.noChanges')); return }
 
-  const results = await apply(root, changes, { dryRun, t })
+  // 비대화형 경로다 — 바를 그리지 않고 평문 한 줄씩 흘린다.
+  // ANSI 제어문자로 CI 로그를 더럽히지 않기 위해서다.
+  const results = await apply(root, changes, {
+    dryRun,
+    t,
+    onProgress: (event) => {
+      const line = plainLine(event, t)
+      if (line) console.log(line)
+    },
+  })
   for (const r of results) {
     console.log(`${r.ok ? '✔' : '✖'} ${t(`change.${r.action}`)} ${r.item.label}${r.message ? ` — ${toText(t, r.message)}` : ''}`)
   }

package/lib/bootstrap/flow.mjs

@@ -6,11 +6,26 @@ import {
 } from './apply.mjs'
 import { RECORD_REL, collectManaged, emptyRecord, readRecord, writeRecord } from './record.mjs'
 import { createT, LocalizedError, toText } from '../i18n/index.mjs'
+import { width } from '../width.mjs'
 
 const SKILL_MODES = ['auto', 'link', 'copy']
 
+// 오른쪽 정렬. width.mjs의 pad()는 오른쪽에 공백을 채워 왼쪽 정렬만 하므로
+// 숫자에는 못 쓴다 — 자릿수가 9에서 10으로 늘 때 열이 흔들리지 않으려면
+// 왼쪽에 채워야 한다. 숫자만 다루니 실제로는 문자 수와 같지만, 이 저장소의
+// 다른 폭 계산과 방식을 맞추려고 width()로 잰다.
+function alignRight(text, w) {
+  return ' '.repeat(Math.max(0, w - width(text))) + text
+}
+
+// "[ 3/39]" 꼴의 단계 번호. total의 자릿수에 맞춰 n을 오른쪽 정렬한다.
+function counterTag(n, total) {
+  const totalText = String(total)
+  return `[${alignRight(String(n), width(totalText))}/${totalText}]`
+}
+
 export function runBootstrap(root, opts = {}) {
-  const { dryRun = false, skillMode = 'auto', adopt = false, log = console.log, manifest = MANIFEST, t = createT('en') } = opts
+  const { dryRun = false, skillMode = 'auto', adopt = false, log = console.log, manifest = MANIFEST, onProgress = null, t = createT('en') } = opts
 
   if (!SKILL_MODES.includes(skillMode)) {
     throw new LocalizedError('error.badSkillModeRuntime', { list: SKILL_MODES.join(', '), value: skillMode })
@@ -22,23 +37,71 @@ export function runBootstrap(root, opts = {}) {
   say(t('log.repoRoot', { path: root }))
   say(t('log.noGlobalWrites'))
 
+  // 총 단계 수. 동기 파일 작업이라 단계 바만 돌지만, 무엇이 남았는지는
+  // 알려 줄 수 있다. adopt는 파일을 만들지 않으므로 기록 쓰기 한 단계뿐이다.
+  // 예측일 뿐이다 — ensureIgnore는 부정 항목이 기존 .gitignore에 가려지면
+  // manifest.ignore.length보다 많은 결과(경고 포함)를 돌려줄 수 있다.
+  let total = adopt
+    ? 1
+    : manifest.dirs.length + manifest.files.length + (manifest.settings ?? []).length
+      + manifest.blocks.length + manifest.adapters.length + manifest.ignore.length + 1
+  let done = 0
+  const step = (results) => {
+    const list = Array.isArray(results) ? results : [results]
+    for (const r of list) {
+      done++
+      // 실제 진행이 예측을 앞지르면 천장을 함께 올린다. total을 고정해 두면
+      // done > total인 알림이 나가 진행률이 100%를 넘고 바가 자기 너비를
+      // 넘겨 그려진다 — done을 total에 맞춰 죽이면 화면은 멈춘 것처럼 보이는데
+      // 남은 단계가 조용히 계속 도는, 더 나쁜 오류가 된다.
+      if (done > total) total = done
+      if (onProgress) onProgress({ done, total, path: r?.path ?? null })
+    }
+    return list
+  }
+
+  // 단계 안에서 나온 로그는 모아 뒀다가 step()이 done/total을 확정한 뒤에
+  // 번호를 붙여 낸다. ensureDirs는 이미 있는 항목을 건너뛸 때 아예 로그를
+  // 내지 않고, ensureIgnore는 여러 항목을 한 줄로 묶어 보고한다 — "몇 번째
+  // 줄이 찍혔는가"와 "몇 번째 항목을 처리했는가"가 그래서 어긋난다. 번호는
+  // 항목 순서가 아니라 처리 위치(done)를 보여 주는 것이 목적이므로, 이
+  // 구간이 시작한 위치(before)부터 실제로 찍힌 줄 수만큼만 순서대로 매긴다.
+  // 못 채운 자리는 건너뛰지만, 다음 구간은 항상 정확한 위치에서 이어져
+  // 마지막 줄은 반드시 total 가까이에서 끝난다.
+  //
+  // onProgress는 그대로 step()이 몬다 — 기계가 읽는 진행 이벤트와 사람이
+  // 읽는 로그 줄은 타이밍이 다르다(ensureX 호출이 끝나야 결과 배열이
+  // 나오고, 그제서야 done/total이 확정된다). 두 소비자를 하나의 흐름으로
+  // 우겨넣는 대신, 같은 done/total 계산을 공유하는 별도 경로로 뒀다.
+  const runStep = (run) => {
+    const buffer = []
+    const before = done
+    const list = step(run({ ...ctx, log: (message) => buffer.push(message) }))
+    let n = before
+    for (const message of buffer) {
+      n++
+      say(`${counterTag(n, total)} ${message}`)
+    }
+    return list
+  }
+
   // --adopt는 이미 있는 저장소를 기록 체계로 끌어오는 용도라 파일을 만들지
   // 않는다. 설치기를 복사해 쓰던 저장소가 여기로 들어온다.
   const results = adopt ? [] : [
-    ...ensureDirs(root, manifest.dirs, ctx),
-    ...ensureFiles(root, manifest.files, ctx),
-    ...ensureJsonKeys(root, manifest.settings ?? [], ctx),
-    ...ensureBlocks(root, manifest.blocks, ctx),
+    ...runStep((c) => ensureDirs(root, manifest.dirs, c)),
+    ...runStep((c) => ensureFiles(root, manifest.files, c)),
+    ...runStep((c) => ensureJsonKeys(root, manifest.settings ?? [], c)),
+    ...runStep((c) => ensureBlocks(root, manifest.blocks, c)),
   ]
 
   if (!adopt) {
     // 어댑터는 항목별로 실패를 격리한다 — 하나가 실패해도 나머지를 계속한다.
     // update.mjs도 같은 격리를 써야 하므로 apply.mjs가 단일 출처다.
     for (const entry of manifest.adapters) {
-      results.push(configureAdapterSafe(root, entry, { ...ctx, skillMode }))
+      results.push(...runStep((c) => configureAdapterSafe(root, entry, { ...c, skillMode })))
     }
 
-    results.push(...ensureIgnore(root, manifest.ignore, ctx))
+    results.push(...runStep((c) => ensureIgnore(root, manifest.ignore, c)))
   }
 
   // 기존 기록의 items·design은 보존한다 — 부트스트랩은 배선만 다루므로
@@ -53,7 +116,11 @@ export function runBootstrap(root, opts = {}) {
     design: previous?.design ?? [],
     managed: collectManaged(root, manifest),
   }
-  results.push(writeRecord(root, record, ctx))
+  results.push(...runStep((c) => writeRecord(root, record, c)))
+
+  // 실제 결과 수가 예측과 다르면 마지막 알림으로 100%를 맞춘다.
+  // 진행 바가 87%에서 끝나면 사용자는 무엇이 실패했다고 읽는다.
+  if (onProgress && done !== total) onProgress({ done: total, total, path: null })
 
   const failed = results.filter((r) => !r.ok)
   log('')

package/lib/catalog.mjs

@@ -1,7 +1,8 @@
 import { existsSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import { execFileSync } from 'node:child_process'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
 import { CLIS, CLI_IDS } from './clis.mjs'
 import { isPluginEnabled, enablePlugin, disablePlugin } from './claude-plugins.mjs'
 import { repoPath, repoPathStrict } from './context.mjs'
@@ -58,8 +59,13 @@ export function shellQuote(text, platform = process.platform) {
   return `'${s.replace(/'/g, "'\\''")}'`
 }
 
+const execFileAsync = promisify(execFile)
+
+// 비동기다. 동기 실행은 이벤트 루프를 통째로 막아, npx가 도는 수십 초 동안
+// 진행 화면을 한 번도 다시 그릴 수 없었다. 반환 형태({ ok, output })는
+// 그대로라 호출부는 await만 더하면 된다.
 export function makeExec(dryRun, log = console.log) {
-  return (cmd, args, opts = {}) => {
+  return async (cmd, args, opts = {}) => {
     if (dryRun) {
       log(`  [dry-run] ${cmd} ${args.join(' ')}`)
       return { ok: true, output: '' }
@@ -70,15 +76,27 @@ export function makeExec(dryRun, log = console.log) {
     // 어차피 우리가 직접 quote하므로, 완성된 한 줄 명령을 넘기고 인자 배열은 비운다.
     const [file, fileArgs] = shell ? [[cmd, ...args].map((s) => shellQuote(s)).join(' '), []] : [cmd, args]
     try {
-      const output = execFileSync(file, fileArgs, {
+      // execFile은 stdio를 강제로 파이프로 고정하고 옵션으로 넘겨도 무시한다 —
+      // 그래서 stdout·stderr는 버퍼링이 공짜로 따라온다. 문제는 stdin이다:
+      // 파이프가 열린 채로 자식에게 넘어가므로, stdin을 읽는 명령(자격 증명·
+      // 확인 프롬프트 등)은 EOF를 못 받아 영원히 멈춘다. 옛 execFileSync는
+      // stdio: ['ignore', ...]로 자식의 stdin을 즉시 닫아 뒀다 — 그 동작을
+      // 복원하려면 스폰 직후 우리가 직접 stdin을 닫아야 한다.
+      const p = execFileAsync(file, fileArgs, {
         encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe'],
         ...opts,
         shell,
       })
-      return { ok: true, output }
+      // 옵션 조합에 따라 stdin이 없을 수 있다 — 없으면 조용히 넘어간다.
+      p.child.stdin?.end()
+      const { stdout } = await p
+      return { ok: true, output: stdout }
     } catch (err) {
-      return { ok: false, output: String(err.stderr ?? err.message) }
+      // spawn 자체가 실패하면(ENOENT 등) err.stderr가 undefined가 아니라
+      // 빈 문자열로 온다 — ??는 빈 문자열을 "값 있음"으로 보고 통과시켜
+      // err.message(바이너리 이름이 담긴 진단 텍스트)를 삼켜 버린다. ||로
+      // 빈 문자열도 폴백하게 한다.
+      return { ok: false, output: String(err.stderr || err.message) }
     }
   }
 }
@@ -130,8 +148,8 @@ export function definePlugin({ id, label, installId, detectIds, marketplace, not
     },
     async install(ctx) {
       const { root, dryRun, exec } = ctx
-      if (marketplace) exec('claude', ['plugin', 'marketplace', 'add', marketplace.repo], { cwd: root })
-      const r = exec('claude', ['plugin', 'install', installId, '--scope', 'project'], { cwd: root })
+      if (marketplace) await exec('claude', ['plugin', 'marketplace', 'add', marketplace.repo], { cwd: root })
+      const r = await exec('claude', ['plugin', 'install', installId, '--scope', 'project'], { cwd: root })
       if (!r.ok) {
         if (!dryRun) enablePlugin(root, installId, marketplace)
         return { fallback: true, message: msg('item.plugin.deferred') }
@@ -139,7 +157,7 @@ export function definePlugin({ id, label, installId, detectIds, marketplace, not
     },
     async uninstall(ctx) {
       const { root, dryRun, exec } = ctx
-      const r = exec('claude', ['plugin', 'uninstall', installId], { cwd: root })
+      const r = await exec('claude', ['plugin', 'uninstall', installId], { cwd: root })
       if (!r.ok && !dryRun) disablePlugin(root, detectIds)
     },
   }
@@ -197,14 +215,14 @@ export function defineRegistrySkill({ id, label, source, skill, note, group = nu
       return { status: findSkillDir(root, skill) ? 'installed' : 'absent' }
     },
     async install({ root, exec }) {
-      const r = exec('npx', ['-y', 'skills@latest', 'add', source, '--skill', skill, '--agent', 'universal', '--yes', '--copy'], { cwd: root })
+      const r = await exec('npx', ['-y', 'skills@latest', 'add', source, '--skill', skill, '--agent', 'universal', '--yes', '--copy'], { cwd: root })
       if (!r.ok) throw new LocalizedError('error.registrySkillInstall', { skill, output: r.output })
     },
     async uninstall({ root, dryRun, exec }) {
       // 레지스트리의 remove는 --agent universal에서 "Done!"을 찍고도 디렉터리를
       // 남긴다(실측). 그래서 성공/실패와 무관하게 남은 디렉터리를 우리가 지운다 —
       // 남겨 두면 detect가 계속 installed로 읽어 제거가 안 된 채 성공으로 보인다.
-      exec('npx', ['-y', 'skills@latest', 'remove', skill, '--agent', 'universal', '--yes'], { cwd: root })
+      await exec('npx', ['-y', 'skills@latest', 'remove', skill, '--agent', 'universal', '--yes'], { cwd: root })
       if (dryRun) return
       const dir = findSkillDir(root, skill)
       if (dir) rmSync(repoPathStrict(root, `${SHARED_SKILLS}/${dir}`), { recursive: true, force: true })

package/lib/clis.mjs

@@ -8,6 +8,9 @@ import { hasSection, appendSection, removeSection } from './tomlfile.mjs'
 // Junction일 때 MCP 등록 한 번으로 글로벌 설정이 생성·수정되는 것을 막는다.
 function jsonAdapter(relFile, topKey, toEntry) {
   return {
+    // 경로를 밖으로 낸다 — 상세 패널이 "이 항목이 어디에 쓰이나"를 보여 준다.
+    // 어댑터가 실제로 쓰는 값과 같은 변수라 두 곳이 갈릴 수 없다.
+    file: relFile,
     has(root, name) {
       const data = readJson(repoPath(root, relFile))
       return getIn(data, [topKey, name]) !== undefined
@@ -29,6 +32,16 @@ function tomlLines(server) {
   ]
 }
 
+// codex·grok은 TOML을 쓴다. jsonAdapter와 같은 이유로 경로를 한 번만 적는다.
+function tomlAdapter(file) {
+  return {
+    file,
+    has: (root, name) => hasSection(repoPath(root, file), name),
+    add: (root, name, s) => appendSection(repoPathStrict(root, file), name, tomlLines(s)),
+    remove: (root, name) => removeSection(repoPathStrict(root, file), name),
+  }
+}
+
 export const CLIS = {
   claude: {
     label: 'Claude Code',
@@ -39,9 +52,7 @@ export const CLIS = {
   },
   codex: {
     label: 'Codex',
-    has: (root, name) => hasSection(repoPath(root, '.codex/config.toml'), name),
-    add: (root, name, s) => appendSection(repoPathStrict(root, '.codex/config.toml'), name, tomlLines(s)),
-    remove: (root, name) => removeSection(repoPathStrict(root, '.codex/config.toml'), name),
+    ...tomlAdapter('.codex/config.toml'),
   },
   gemini: {
     label: 'Gemini CLI',
@@ -76,9 +87,7 @@ export const CLIS = {
   },
   grok: {
     label: 'Grok Build',
-    has: (root, name) => hasSection(repoPath(root, '.grok/config.toml'), name),
-    add: (root, name, s) => appendSection(repoPathStrict(root, '.grok/config.toml'), name, tomlLines(s)),
-    remove: (root, name) => removeSection(repoPathStrict(root, '.grok/config.toml'), name),
+    ...tomlAdapter('.grok/config.toml'),
   },
   copilot: {
     label: 'GitHub Copilot CLI',

package/lib/design-md/cache/awesome-design-md/LICENSE.md

@@ -0,0 +1,38 @@
+# Third-party notice — awesome-design-md
+
+이 디렉터리의 `DESIGN.md` 파일들은 아래 저장소에서 그대로 가져온 사본입니다.
+오프라인 설치를 위해 동봉하며, 원문을 고치지 않습니다.
+
+- Source: https://github.com/VoltAgent/awesome-design-md
+- License: MIT
+
+MIT는 재배포를 허용하되 저작권 고지와 허가 문구를 사본에 함께 담을 것을
+요구합니다. 아래가 상류 `LICENSE`의 원문입니다.
+
+파일 이름이 `LICENSE`가 아니라 `LICENSE.md`인 이유는 발행물 검사가 최상위
+`LICENSE` 하나만 확장자 없는 파일로 허용하기 때문입니다 — 이름이 아니라
+담긴 내용이 고지의 요건을 채웁니다.
+
+---
+
+MIT License
+
+Copyright (c) 2026 VoltAgent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/design-md/flow.mjs

@@ -5,6 +5,7 @@ import { discoverSources, extraDirsFromEnv } from './scan.mjs'
 import { makeOpener, openPreview } from './open.mjs'
 import { createT, toText } from '../i18n/index.mjs'
 import { labelWidth, pad } from '../width.mjs'
+import { plainLine } from '../tui/progress.mjs'
 
 // design 항목의 detect는 installed/absent만 돌려준다(catalog.mjs) — partial은
 // 열을 넓히기만 하고 실제로 나오지 않는다.
@@ -62,7 +63,17 @@ function openPreviews(items, tokensStr, opener, log, t) {
 async function applyVisible(root, visibleStates, selectedIds, { dryRun, log, t }) {
   const changes = planChanges(visibleStates, selectedIds)
   if (changes.length === 0) { log(t('apply.noChanges')); return [] }
-  const results = await apply(root, changes, { dryRun, log, t })
+  // design --set도 비대화형 경로다 — runClassic의 --set과 대칭으로, 바를
+  // 그리지 않고 평문 한 줄씩 흘린다. ANSI 제어문자로 로그를 더럽히지 않는다.
+  const results = await apply(root, changes, {
+    dryRun,
+    log,
+    t,
+    onProgress: (event) => {
+      const line = plainLine(event, t)
+      if (line) log(line)
+    },
+  })
   report(results, log, t)
   return results
 }

package/lib/design-md/providers/awesome-design-md.mjs

@@ -14,6 +14,9 @@ const REPO = 'VoltAgent/awesome-design-md'
 const BRANCH = 'main'
 const RAW_BASE = `https://raw.githubusercontent.com/${REPO}/${BRANCH}/design-md`
 const README_URL = `https://raw.githubusercontent.com/${REPO}/${BRANCH}/README.md`
+// 번들에 함께 담는 상류 고지의 출처. MIT는 사본에 저작권 고지와 허가 문구를
+// 담을 것을 요구하므로, 파일을 내려받아 재배포하는 이상 이 URL이 필요하다.
+const LICENSE_URL = `https://raw.githubusercontent.com/${REPO}/${BRANCH}/LICENSE`
 const TREE_URL = `https://api.github.com/repos/${REPO}/git/trees/${BRANCH}?recursive=1`
 // scan.mjs의 BUNDLE_CATEGORY와 같은 값이어야 한다 — 둘 다 카테고리 못 얻은
 // 항목이 모이는 자리라, 갈라지면 같은 그룹이 헤더 두 개로 쪼개진다.
@@ -61,6 +64,10 @@ export const awesomeDesignMd = {
   id: 'awesome-design-md',
   label: 'awesome-design-md (VoltAgent)',
   files: ['DESIGN.md'],
+  licenseUrl: LICENSE_URL,
+  // 번들과 함께 발행되는 고지 파일. 이름이 LICENSE가 아닌 이유는 발행물 검사가
+  // 최상위 LICENSE 하나만 확장자 없는 파일로 허용하기 때문이다.
+  noticeFile: 'LICENSE.md',
 
   fileUrl(name, file = 'DESIGN.md') {
     return `${RAW_BASE}/${encodeURIComponent(name)}/${file}`

package/lib/engine.mjs

@@ -25,24 +25,76 @@ export function planChanges(states, selectedIds) {
   return changes
 }
 
-export async function apply(root, changes, { dryRun = false, log = console.log, t = createT('en') } = {}) {
-  const exec = makeExec(dryRun, log)
+export async function apply(root, changes, { dryRun = false, log = console.log, t = createT('en'), onProgress = null, shouldStop = null } = {}) {
+  const baseExec = makeExec(dryRun, log)
   const results = []
-  for (const { item, action } of changes) {
+  const total = changes.length
+
+  // 알림은 참고용이지 설치를 좌우하지 않는다. onProgress는 훗날 실제 렌더러가
+  // 될 자리라(Task 11) 그 안의 버그가 던지면, notify를 감싸지 않는 한 예외가
+  // apply()를 통째로 빠져나가 이미 디스크에 쓴 항목의 결과를 아무도 못 받는다.
+  // command 단계 알림은 install/uninstall의 try 안에서 불리므로, 여기서 삼키지
+  // 않으면 렌더링 버그가 그 항목의 설치 실패로 잘못 보고된다.
+  const notify = (event) => {
+    if (!onProgress) return
+    try {
+      onProgress({ total, ...event })
+    } catch {
+      // 무시한다 — 알림 실패로 설치를 멈추거나 결과를 뒤틀면 안 된다.
+    }
+  }
+
+  // shouldStop도 같은 이유로 감싼다. 여기서 다시 던지면 UI 술어의 버그 하나가
+  // 설치 전체를 중단시킨다 — 알림을 못 받는 것보다 더 나쁘다. 던지면 "멈추지
+  // 않음"으로 취급해 계속 진행한다.
+  const isStopRequested = () => {
+    if (!shouldStop) return false
+    try {
+      return Boolean(shouldStop())
+    } catch {
+      return false
+    }
+  }
+
+  for (let index = 0; index < total; index++) {
+    const { item, action } = changes[index]
+
+    // 중단은 **항목 경계에서만** 본다. 외부 명령을 중간에 죽이면 반쯤 설치된
+    // 상태가 남는다 — 그래서 AbortSignal이 아니라 술어(predicate)다.
+    if (isStopRequested()) {
+      // skipped: true는 "시도조차 하지 않았다"는 뜻이다. ok는 성공하지 못했으니
+      // false지만 실패는 아니다 — 소비자는 실패로 보고하거나 exitCode를 세우기
+      // 전에 반드시 skipped를 먼저 확인해야 한다(!r.ok && !r.skipped).
+      results.push({ item, action, ok: false, skipped: true })
+      continue
+    }
+
+    notify({ index, item, action, phase: 'start' })
+    const startedAt = Date.now()
+
+    // 화면이 "지금 무엇이 도는가"를 보여 줄 수 있는 유일한 경로다.
+    const exec = async (cmd, args, opts) => {
+      notify({ index, item, action, phase: 'command', command: [cmd, ...args].join(' ') })
+      return baseExec(cmd, args, opts)
+    }
+
     // log까지 넘긴다 — 파일을 직접 쓰는 항목(MCP·design.md)은 exec를 거치지
     // 않아 dry-run에서 아무것도 보고하지 못했다. 결과줄은 ✔ 설치라고 찍히는데
     // 무엇이 바뀔지는 알 수 없는 상태였다.
     const ctx = { root, dryRun, exec, log, t }
+    let result
     try {
       const fn = action === 'uninstall' ? item.uninstall : item.install
       const r = await fn.call(item, ctx)
-      results.push({ item, action, ok: true, message: r?.message })
+      result = { item, action, ok: true, message: r?.message }
     } catch (err) {
       // LocalizedError는 .key를 들고 있다 — 구조체로 옮겨 담아야 표시하는
       // 쪽에서 toText로 활성 로케일에 맞게 다시 렌더할 수 있다. 그냥
       // err.message만 쓰면 LocalizedError.message는 항상 영어라 로케일이 섞인다.
-      results.push({ item, action, ok: false, message: err.key ? msg(err.key, err.params) : err.message })
+      result = { item, action, ok: false, message: err.key ? msg(err.key, err.params) : err.message }
     }
+    results.push(result)
+    notify({ index, item, action, phase: 'done', ok: result.ok, ms: Date.now() - startedAt, message: result.message })
   }
   return results
 }

package/lib/i18n/catalog/en.mjs

@@ -280,8 +280,8 @@ export default {
   'tui.search.placeholder': 'type to search · ↓ for the list',
   'tui.empty.filtered': '  Nothing matches in this tab. Press Tab to try another.',
   'tui.empty.none': '  Nothing here.',
-  'tui.hint.search': 'type to search (spaces included)   ↓ to list   Tab switch tab   Esc clear',
-  'tui.hint.list': 'Space select   ↑↓ move (↑ at top = search)   Tab switch tab   Enter run/submit   Ctrl+A all   Ctrl+O preview',
+  'tui.hint.search': 'type to search (spaces included)   ↓ to list   Tab tab   Esc clear   Ctrl+F CLI   Ctrl+D detail',
+  'tui.hint.list': 'Space select   ↑↓ move (↑ at top = search)   Tab tab   Enter run/submit   Ctrl+A all   Ctrl+O preview   Ctrl+F CLI   Ctrl+D detail',
   'tui.review.title': 'Review — {count} change(s)',
   'tui.review.more': '  …and {count} more',
   'tui.review.hint': 'Enter apply   Esc cancel',
@@ -293,21 +293,50 @@ export default {
   'tui.toggledAll': 'Selected every visible item in the {tab} tab.',
   'tui.toggledNone': 'Cleared every visible item in the {tab} tab.',
   'tui.nonInteractive': 'The interactive screen only opens in a terminal. --list and --set work too.',
-  'tui.applyHeader': '{count} change(s) to apply{suffix}:',
   'tui.pressAnyKey': 'Press any key to continue…',
   'tui.confirmSuffix': ' [y/N] ',
 
+  // 진행 화면(tui/progress.mjs) 문구. Task 9의 이벤트(start·command·done)를
+  // 사람이 읽는 줄로 바꾼다. plain*은 비TTY(CI·파이프)용 한 줄 출력이다.
+  'progress.title': 'Applying — {count} change(s){suffix}',
+  'progress.counter': '{done}/{total}  {percent}%',
+  'progress.elapsed': '{seconds}s',
+  'progress.elapsedMin': '{minutes}m{seconds}s',
+  'progress.running': '{seconds}s elapsed',
+  'progress.more': '  …and {count} more',
+  'progress.abortHint': 'Ctrl+C stops after the current item',
+  'progress.aborted': 'Stopped — {count} item(s) skipped',
+  'progress.skipped': 'skipped',
+  'progress.done': 'Done — {ok} succeeded, {failed} failed{skippedSuffix}',
+  'progress.plain': '[{index}/{total}] {action} {label}',
+  'progress.plainDone': '      {mark} {seconds}s',
+
   // 언어 행(action.language) 전용. 저장 성공·dry-run·실패·강제 로케일 네 갈래를 덮는다.
   'tui.lang.saved': 'Saved to {path}',
   'tui.lang.dryRun': 'dry-run — applied to this session only',
   'tui.lang.saveFailed': 'Could not save the language: {message}',
   'tui.lang.overridden': '--lang / AGENT_SETUP_LANG still wins on the next run.',
 
+  // CLI 필터 표시. 검색줄 오른쪽 끝에 붙는다(Task 7) — filterSegment가 쓴다.
+  // 필터가 없을 때는 아무것도 내지 않는다(잡음 방지) — "전체" 라벨을 위한
+  // 키를 따로 두지 않는다.
+  'tui.filter.prefix': 'CLI › ',
+  'tui.filter.position': '{current}/{total}',
+  'tui.filter.empty': '  Nothing in this tab is wired for {cli}.',
+
   'item.location.user': 'installs to: user global',
   // 커버리지는 전부 지원할 때도 찍는다 — 표시가 없는 것과 "10/10"은 뜻이 다르다.
   'item.cliCoverage': 'CLI {covered}/{total}',
   'item.unsupportedList': 'not wired for {count}: {groups}',
   'item.unsupportedGroup': '{clis} — {why}',
+  'detail.wired': 'wired',
+  'detail.unwired': 'unwired',
+  'detail.provider': 'source',
+  'detail.preview': 'preview',
+  'detail.scope.project': 'repo scope',
+  'detail.scope.user': 'user global',
+  'detail.more': '  …and {count} more line(s) — Ctrl+D to expand',
+  'detail.empty': '  Move the cursor onto an item to see its details.',
 
   // 상주 언어 행 — 작업 탭 맨 위. hint는 현재 로케일의 자기 이름을 담는다.
   'action.language.label': 'Language',

package/lib/i18n/catalog/ko.mjs

@@ -271,8 +271,8 @@ export default {
   'tui.search.placeholder': '타이핑하면 검색 · ↓ 로 목록',
   'tui.empty.filtered': '  이 탭에는 일치하는 항목이 없습니다. Tab으로 다른 탭을 보세요.',
   'tui.empty.none': '  항목이 없습니다.',
-  'tui.hint.search': '입력=검색어(스페이스 포함)   ↓ 목록으로   Tab 탭이동   Esc 검색해제',
-  'tui.hint.list': 'Space 선택   ↑↓ 이동(맨 위 ↑=검색칸)   Tab 탭   Enter 실행/제출   Ctrl+A 전체   Ctrl+O 미리보기',
+  'tui.hint.search': '입력=검색어   ↓ 목록으로   Tab 탭이동   Esc 검색해제   Ctrl+F CLI   Ctrl+D 상세',
+  'tui.hint.list': 'Space 선택   ↑↓ 이동   Tab 탭   Enter 실행/제출   Ctrl+A 전체   Ctrl+O 미리보기   Ctrl+F CLI   Ctrl+D 상세',
   'tui.review.title': '제출 검토 — 변경 {count}건',
   'tui.review.more': '  …외 {count}건',
   'tui.review.hint': 'Enter 적용   Esc 취소',
@@ -284,21 +284,47 @@ export default {
   'tui.toggledAll': '{tab} 탭의 보이는 항목을 모두 선택했습니다.',
   'tui.toggledNone': '{tab} 탭의 보이는 항목을 모두 해제했습니다.',
   'tui.nonInteractive': '대화형 화면은 터미널에서만 열립니다. --list · --set 으로도 다룰 수 있습니다.',
-  'tui.applyHeader': '적용할 변경 {count}건{suffix}:',
   'tui.pressAnyKey': '계속하려면 아무 키나 누르세요…',
   'tui.confirmSuffix': ' [y/N] ',
 
+  // 진행 화면(tui/progress.mjs) 문구. en.mjs 쪽 주석 참고.
+  'progress.title': '적용 중 — 변경 {count}건{suffix}',
+  'progress.counter': '{done}/{total}  {percent}%',
+  'progress.elapsed': '{seconds}초',
+  'progress.elapsedMin': '{minutes}분{seconds}초',
+  'progress.running': '{seconds}초 경과',
+  'progress.more': '  …외 {count}건',
+  'progress.abortHint': 'Ctrl+C 중단 (현재 항목까지 마칩니다)',
+  'progress.aborted': '중단했습니다 — {count}건 건너뜀',
+  'progress.skipped': '건너뜀',
+  'progress.done': '끝났습니다 — 성공 {ok}건, 실패 {failed}건{skippedSuffix}',
+  'progress.plain': '[{index}/{total}] {action} {label}',
+  'progress.plainDone': '      {mark} {seconds}초',
+
   // 언어 행(action.language) 전용. en.mjs 쪽 주석 참고.
   'tui.lang.saved': '{path}에 저장했습니다',
   'tui.lang.dryRun': 'dry-run — 이번 세션에만 적용했습니다',
   'tui.lang.saveFailed': '언어를 저장하지 못했습니다: {message}',
   'tui.lang.overridden': '다음 실행에서는 --lang / AGENT_SETUP_LANG이 여전히 이깁니다.',
 
+  // CLI 필터 표시. en.mjs 쪽 주석 참고.
+  'tui.filter.prefix': 'CLI › ',
+  'tui.filter.position': '{current}/{total}',
+  'tui.filter.empty': '  이 탭에는 {cli}에 배선되는 항목이 없습니다.',
+
   'item.location.user': '설치 위치: 사용자 글로벌',
   // en.mjs 쪽 주석 참고.
   'item.cliCoverage': 'CLI {covered}/{total}',
   'item.unsupportedList': '미배선 {count}곳: {groups}',
   'item.unsupportedGroup': '{clis} — {why}',
+  'detail.wired': '배선',
+  'detail.unwired': '미배선',
+  'detail.provider': '공급자',
+  'detail.preview': '미리보기',
+  'detail.scope.project': '저장소 스코프',
+  'detail.scope.user': '사용자 전역',
+  'detail.more': '  …외 {count}줄 — Ctrl+D로 펼치기',
+  'detail.empty': '  커서를 항목 위에 올리면 상세가 보입니다.',
 
   // 상주 언어 행 — en.mjs 쪽 주석 참고.
   'action.language.label': '언어',

package/lib/items/plugin.ponytail.mjs

@@ -67,8 +67,8 @@ export default {
   async install({ root, dryRun, exec, log = () => {}, t }) {
     let deferred = false
     if (!isPluginEnabled(root, [INSTALL_ID])) {
-      exec('claude', ['plugin', 'marketplace', 'add', MARKETPLACE.repo], { cwd: root })
-      const r = exec('claude', ['plugin', 'install', INSTALL_ID, '--scope', 'project'], { cwd: root })
+      await exec('claude', ['plugin', 'marketplace', 'add', MARKETPLACE.repo], { cwd: root })
+      const r = await exec('claude', ['plugin', 'install', INSTALL_ID, '--scope', 'project'], { cwd: root })
       if (!r.ok) {
         if (!dryRun) enablePlugin(root, INSTALL_ID, MARKETPLACE)
         deferred = true
@@ -86,7 +86,7 @@ export default {
 
   async uninstall({ root, dryRun, exec, log = () => {}, t }) {
     if (isPluginEnabled(root, [INSTALL_ID])) {
-      const r = exec('claude', ['plugin', 'uninstall', INSTALL_ID], { cwd: root })
+      const r = await exec('claude', ['plugin', 'uninstall', INSTALL_ID], { cwd: root })
       if (!r.ok && !dryRun) disablePlugin(root, [INSTALL_ID])
     }
     if (!hasOpencode(root)) return

package/lib/items/skill.gsd.mjs

@@ -15,11 +15,11 @@ export default defineSkill({
     return { status: found ? 'installed' : 'absent' }
   },
   async install({ root, exec }) {
-    const r = exec('npx', ['-y', '@opengsd/gsd-core@latest', '--claude', '--local'], { cwd: root })
+    const r = await exec('npx', ['-y', '@opengsd/gsd-core@latest', '--claude', '--local'], { cwd: root })
     if (!r.ok) throw new LocalizedError('error.gsdInstall', { output: r.output })
   },
   async uninstall({ root, exec }) {
-    const r = exec('npx', ['-y', '@opengsd/gsd-core@latest', '--uninstall'], { cwd: root })
+    const r = await exec('npx', ['-y', '@opengsd/gsd-core@latest', '--uninstall'], { cwd: root })
     if (!r.ok) throw new LocalizedError('error.gsdUninstall', { output: r.output })
   },
 })

package/lib/items/skill.gstack.mjs

@@ -19,9 +19,9 @@ export default defineSkill({
     // .agents/skills Junction은 저장소 안이라 그대로 통과한다).
     const dir = repoPathStrict(root, REL_DIR)
     if (!existsSync(dir)) {
-      const clone = exec('git', ['clone', '--single-branch', '--depth', '1', 'https://github.com/garrytan/gstack.git', dir])
+      const clone = await exec('git', ['clone', '--single-branch', '--depth', '1', 'https://github.com/garrytan/gstack.git', dir])
       if (!clone.ok) throw new LocalizedError('error.gstackClone', { output: clone.output })
-      const setup = exec('bash', ['./setup'], { cwd: dir })
+      const setup = await exec('bash', ['./setup'], { cwd: dir })
       if (!setup.ok) {
         // setup 실패 잔존물이 detect를 installed로 오판시키지 않도록 정리한다.
         rmSync(dir, { recursive: true, force: true })
@@ -34,7 +34,7 @@ export default defineSkill({
   async uninstall({ root, dryRun, exec }) {
     const dir = repoPathStrict(root, REL_DIR)
     if (!existsSync(dir)) return
-    exec('bash', [join(dir, 'bin', 'gstack-uninstall'), '--force'], { cwd: dir }) // 실패해도 디렉터리 삭제로 폴백
+    await exec('bash', [join(dir, 'bin', 'gstack-uninstall'), '--force'], { cwd: dir }) // 실패해도 디렉터리 삭제로 폴백
     if (!dryRun && existsSync(dir)) rmSync(dir, { recursive: true, force: true })
   },
 })