@rch4com/agent-setup 1.19.0 → 1.21.0

package/install.mjs

@@ -125,7 +125,11 @@ async function main() {
   // 살아남는다. 조용히 되돌아가는 대신 화면이 그 사실을 알리게 한다.
   const localeForced = isLocaleForced({ flag, env: process.env })
 
-  if (root === null) throw new LocalizedError('error.notGitRepo')
+  // 도움말은 저장소가 필요 없다. 이 검사를 먼저 하면 `--help`가 Git 저장소
+  // 밖에서 "Run this inside a Git repository"로 죽는다 — 사용법을 보려는
+  // 사람에게 그 오류를 내밀 이유가 없다.
+  const wantsHelp = argv.includes('-h') || argv.includes('--help')
+  if (root === null && !wantsHelp) throw new LocalizedError('error.notGitRepo')
 
   if (argv[0] === 'bootstrap') {
     const opts = parseBootstrapArgs(argv.slice(1), t)
@@ -140,7 +144,8 @@ async function main() {
     if (opts.help) { console.log(updateUsage(t)); return }
     // 항목 수렴을 위해 스캔이 필요해 의존성 있는 모듈에 닿는다.
     const { runUpdate } = await withDeps(() => import('./lib/update.mjs'), t)
-    await runUpdate(root, { ...opts, t })
+    const { failed } = await runUpdate(root, { ...opts, t })
+    if (failed.length > 0) process.exitCode = 1
     return
   }
 

package/lib/bootstrap/adapter.mjs

@@ -2,7 +2,7 @@
 // Windows는 Junction을 쓴다. 관리자 권한이 필요 없고, MSYS(Git Bash)의 ln -s가
 // 링크 대신 복사를 만드는 문제도 우회한다.
 import { cpSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
-import { dirname, join, relative, resolve } from 'node:path'
+import { basename, dirname, join, relative, resolve } from 'node:path'
 import { repoPath, repoPathStrict } from '../context.mjs'
 import { createT, msg } from '../i18n/index.mjs'
 import { pathExists } from './apply.mjs'
@@ -42,7 +42,12 @@ export function configureAdapter(root, { tool, path: rel }, { dryRun = false, sk
   const target = repoPath(root, rel)
 
   const linked = linkTarget(target)
-  if (linked !== null) {
+  // 대상이 사라진 링크는 보존할 것이 없다. Windows Junction은 만들 때의 절대
+  // 경로를 담으므로 저장소 디렉터리를 옮기거나 이름을 바꾸면 옛 경로를
+  // 가리킨 채 끊긴다 — 그것을 "다른 곳을 가리키는 링크"로 보고 보존하면
+  // 매 실행마다 경고만 찍히고 Claude Code는 공유 스킬을 영영 보지 못한다.
+  const dangling = linked !== null && !pathExists(linked)
+  if (linked !== null && !dangling) {
     if (linked === repoPath(root, SOURCE_REL)) {
       log(t('log.skill.linkOk', { tool, path: rel }))
       return { ok: true, action: 'skip', path: rel }
@@ -51,8 +56,8 @@ export function configureAdapter(root, { tool, path: rel }, { dryRun = false, sk
     return { ok: true, action: 'warn', path: rel, message: msg('msg.foreignLink') }
   }
 
-  const managedCopy = pathExists(target) && pathExists(join(target, MARKER))
-  if (pathExists(target) && !managedCopy) {
+  const managedCopy = !dangling && pathExists(target) && pathExists(join(target, MARKER))
+  if (!dangling && pathExists(target) && !managedCopy) {
     log(t('log.skill.warnUnmanaged', { path: rel }))
     return { ok: true, action: 'warn', path: rel, message: msg('msg.unmanagedExisting') }
   }
@@ -62,7 +67,14 @@ export function configureAdapter(root, { tool, path: rel }, { dryRun = false, sk
   // 쓰기만 !dryRun으로 막는다 — apply.mjs의 ensureDirs와 같은 형태.
   // source(.agents/skills)는 실제로 읽어 복사하는 대상이므로 여기서 함께 검사한다.
   const source = repoPathStrict(root, SOURCE_REL)
-  const strictTarget = repoPathStrict(root, rel)
+  // 끊긴 링크는 realpath가 ENOENT로 실패해 자기 자신을 엄격 검사할 수 없다.
+  // 지울 것은 링크 항목 하나뿐이니 그것이 놓인 부모 디렉터리를 검사한다 —
+  // 부모가 저장소 안이면 그 안의 항목 하나를 지우는 것도 저장소 안이다.
+  const strictTarget = dangling
+    ? join(repoPathStrict(root, dirname(rel)), basename(rel))
+    : repoPathStrict(root, rel)
+
+  if (dangling) log(t('log.skill.relinkDangling', { path: rel }))
 
   if (dryRun) {
     log(t('log.skill.plan', { tool, path: rel, mode: skillMode }))
@@ -74,6 +86,8 @@ export function configureAdapter(root, { tool, path: rel }, { dryRun = false, sk
     // 마커가 확인된 복사본만 지운다.
     rmSync(strictTarget, { recursive: true, force: true })
   }
+  // 링크 자체만 지운다 — rmSync는 링크를 따라 내려가지 않는다(대상이 없기도 하다).
+  if (dangling) rmSync(strictTarget, { recursive: true, force: true })
 
   mkdirSync(dirname(strictTarget), { recursive: true })
 

package/lib/catalog.mjs

@@ -67,6 +67,12 @@ const execFileAsync = promisify(execFile)
 // 보고된다. 호출부가 opts.timeout으로 바꿀 수 있다.
 export const EXEC_TIMEOUT_MS = 10 * 60 * 1000
 
+// 자식 출력의 상한. execFile 기본값(1MB)을 넘기면 Node가 자식을 **죽이고**
+// "maxBuffer length exceeded"로 실패시킨다 — gsd(3,500파일)·hallmark
+// (references 100개 이상)처럼 파일마다 한 줄씩 찍는 설치가 반쯤 깔린 채
+// 실패로 보고됐다. 64MB면 어떤 설치 로그도 넉넉히 담긴다.
+export const EXEC_MAX_BUFFER = 64 * 1024 * 1024
+
 // 비동기다. 동기 실행은 이벤트 루프를 통째로 막아, npx가 도는 수십 초 동안
 // 진행 화면을 한 번도 다시 그릴 수 없었다. 반환 형태({ ok, output })는
 // 그대로라 호출부는 await만 더하면 된다.
@@ -91,6 +97,7 @@ export function makeExec(dryRun, log = console.log, t = null) {
       const p = execFileAsync(file, fileArgs, {
         encoding: 'utf8',
         timeout: EXEC_TIMEOUT_MS,
+        maxBuffer: EXEC_MAX_BUFFER,
         ...opts,
         shell,
       })

package/lib/design-md/flow.mjs

@@ -1,5 +1,5 @@
 import { scan, planChanges, apply } from '../engine.mjs'
-import { loadCatalog, saveCatalog, buildItems, allEntries, sha256, resolveTokens, netFetch, CATALOG_PATH } from './catalog.mjs'
+import { loadCatalog, saveCatalog, buildItems, allEntries, sha256, resolveTokens, netFetch, isSafeSegment, CATALOG_PATH } from './catalog.mjs'
 import { PROVIDERS } from './providers/index.mjs'
 import { discoverSources, extraDirsFromEnv } from './scan.mjs'
 import { makeOpener, openPreview } from './open.mjs'
@@ -90,7 +90,11 @@ export async function refreshCatalog({ dryRun, fetchImpl, log, catalogFile = CAT
   const next = { updatedAt: new Date().toISOString(), providers: {} }
   for (const provider of PROVIDERS) {
     try {
-      const entries = await provider.fetchCatalog(fetchImpl)
+      // 이름은 원격 README에서 오는 신뢰 경계 밖 값이다. buildItems가 설치
+      // 경로 앞에서 거르지만, 카탈로그 파일 자체에 `..` 같은 이름이 남으면
+      // 그 파일을 직접 읽는 번들 스크립트가 경로 이탈에 노출된다 — 저장
+      // 전에 거른다.
+      const entries = (await provider.fetchCatalog(fetchImpl)).filter((e) => isSafeSegment(e.name))
       next.providers[provider.id] = { label: provider.label, entries }
       log(t('design.provider.count', { label: provider.label, count: entries.length }))
     } catch (err) {

package/lib/gitignore.mjs

@@ -16,3 +16,18 @@ export function ensureGitignoreEntries(root, entries) {
   const sep = text.length === 0 || text.endsWith('\n') ? '' : eol
   writeFileSync(file, text + sep + missing.join(eol) + eol)
 }
+
+// 정확히 일치하는 줄만 걷어낸다 — 설치가 넣은 항목을 제거가 도로 가져가는
+// 용도라, 사용자가 손으로 적은 비슷한 패턴은 건드리지 않는다. 줄바꿈은
+// 파일의 것을 그대로 따른다.
+export function removeGitignoreEntries(root, entries) {
+  const file = repoPathStrict(root, '.gitignore')
+  if (!existsSync(file)) return
+  const text = readFileSync(file, 'utf8')
+  const eol = text.includes('\r\n') ? '\r\n' : '\n'
+  const drop = new Set(entries)
+  const lines = text.split(/\r?\n/)
+  const kept = lines.filter((line) => !drop.has(line))
+  if (kept.length === lines.length) return
+  writeFileSync(file, kept.join(eol))
+}

package/lib/i18n/catalog/en.mjs

@@ -109,7 +109,8 @@ export default {
     'Usage: npx @rch4com/agent-setup status [options]',
     '',
     'Shows intent (the install record), reality (a scan of the repository), and',
-    'the running tool version side by side. Changes nothing.',
+    'the running tool version side by side. Changes nothing. Asks the npm',
+    'registry for the latest version (5-second limit; offline just leaves it blank).',
     '',
     'Options:',
     '  --json       Print machine-readable output (for CI checks).',
@@ -150,6 +151,8 @@ export default {
   'log.record.write': 'install record written: {path}',
   'error.recordUnreadable': 'Cannot read {path} ({code})',
   'error.recordNotJson': 'Cannot read {path} — not JSON ({message})',
+  'error.tomlInvalid': 'Cannot read {path} — invalid TOML: {message}. Fix the file by hand; nothing was written.',
+  'error.jsonInvalid': 'Cannot read {path} — invalid JSON: {message}. Fix the file by hand; nothing was written.',
   'error.recordVersion': '{path} has format version {found}. This tool uses {expected} — upgrade the tool or recreate the record.',
 
   'log.repoRoot': 'repository root: {path}',
@@ -183,6 +186,7 @@ export default {
   'msg.readFailed': 'read failed',
   'msg.noRootObject': 'no root object',
   'msg.foreignLink': 'link pointing elsewhere',
+  'log.skill.relinkDangling': 'warning: {path} is a link whose target no longer exists (the repository moved?). Recreating it.',
   'msg.unmanagedExisting': 'existing entry not under management',
   'msg.noManagedBlock': 'no managed block',
   'msg.linkFailed': 'link creation failed: {message}',
@@ -344,6 +348,7 @@ export default {
   'tui.noPreview': 'This item has no preview.',
   'tui.opened': 'Opened: {target}',
   'tui.noChanges': 'Nothing to change.',
+  'tui.actionFailed': 'The action failed: {message}',
   'tui.submitCancelled': 'Submission cancelled.',
   'tui.selectedGlobal': 'Machine-global item — applies to this whole computer',
   'tui.toggledAll': 'Selected every visible item in the {tab} tab.',

package/lib/i18n/catalog/ko.mjs

@@ -103,7 +103,8 @@ export default {
     '사용법: npx @rch4com/agent-setup status [옵션]',
     '',
     '설치 기록(의도) / 실제 저장소 상태(스캔) / 실행 중 도구 버전을',
-    '나란히 보여줍니다. 아무것도 바꾸지 않습니다.',
+    '나란히 보여줍니다. 아무것도 바꾸지 않습니다. 최신 버전은 npm 레지스트리에',
+    '묻습니다(5초 제한, 오프라인이면 그 자리만 비웁니다).',
     '',
     '옵션:',
     '  --json       기계가 읽을 형태로 출력합니다 (CI 판정용).',
@@ -144,6 +145,8 @@ export default {
   'log.record.write': '설치 기록 기록: {path}',
   'error.recordUnreadable': '{path}을 읽을 수 없습니다 ({code})',
   'error.recordNotJson': '{path}을 읽을 수 없습니다 — JSON이 아닙니다 ({message})',
+  'error.tomlInvalid': '{path}을 읽을 수 없습니다 — TOML이 깨져 있습니다: {message}. 파일을 손으로 고치세요. 아무것도 쓰지 않았습니다.',
+  'error.jsonInvalid': '{path}을 읽을 수 없습니다 — JSON이 깨져 있습니다: {message}. 파일을 손으로 고치세요. 아무것도 쓰지 않았습니다.',
   'error.recordVersion': '{path}의 형식 버전이 {found}입니다. 이 도구는 {expected}을 씁니다 — 도구를 올리거나 기록을 다시 만드세요.',
 
   'log.repoRoot': '저장소 루트: {path}',
@@ -177,6 +180,7 @@ export default {
   'msg.readFailed': '읽기 실패',
   'msg.noRootObject': '루트 객체 없음',
   'msg.foreignLink': '다른 위치를 가리키는 링크',
+  'log.skill.relinkDangling': '경고: {path} 링크의 대상이 더는 존재하지 않습니다(저장소를 옮겼나요?). 다시 만듭니다.',
   'msg.unmanagedExisting': '관리 대상이 아닌 기존 항목',
   'msg.noManagedBlock': '관리 블록 없음',
   'msg.linkFailed': '링크 생성 실패: {message}',
@@ -334,6 +338,7 @@ export default {
   'tui.noPreview': '이 항목은 미리보기를 제공하지 않습니다.',
   'tui.opened': '열었습니다: {target}',
   'tui.noChanges': '변경할 항목이 없습니다.',
+  'tui.actionFailed': '작업이 실패했습니다: {message}',
   'tui.submitCancelled': '제출을 취소했습니다.',
   'tui.selectedGlobal': '머신 전역 항목 — 이 컴퓨터 전체에 적용됩니다',
   'tui.toggledAll': '{tab} 탭의 보이는 항목을 모두 선택했습니다.',

package/lib/items/skill.gstack.mjs

@@ -3,10 +3,11 @@ import { join } from 'node:path'
 import { defineSkill } from '../catalog.mjs'
 import { CLI_IDS } from '../clis.mjs'
 import { repoPath, repoPathStrict } from '../context.mjs'
-import { ensureGitignoreEntries } from '../gitignore.mjs'
+import { ensureGitignoreEntries, removeGitignoreEntries } from '../gitignore.mjs'
 import { LocalizedError, msg } from '../i18n/index.mjs'
 
 const REL_DIR = '.claude/skills/gstack'
+const IGNORE_ENTRIES = ['.claude/skills/gstack', '.agents/skills/gstack']
 
 // 상류 setup은 --host codex·kiro·opencode(와 factory)도 지원하지만 이 항목은
 // 인자 없이 실행하며 setup의 기본값이 claude 단독이다. README 표에 있는
@@ -58,12 +59,16 @@ export default defineSkill({
       }
     }
     // 부트스트랩 저장소에서는 .claude/skills가 .agents/skills Junction이므로 두 경로 모두 무시 처리
-    if (!dryRun) ensureGitignoreEntries(root, ['.claude/skills/gstack', '.agents/skills/gstack'])
+    if (!dryRun) ensureGitignoreEntries(root, IGNORE_ENTRIES)
   },
   async uninstall({ root, dryRun, exec }) {
     const dir = repoPathStrict(root, REL_DIR)
     if (!existsSync(dir)) return
     await exec('bash', [join(dir, 'bin', 'gstack-uninstall'), '--force'], { cwd: dir }) // 실패해도 디렉터리 삭제로 폴백
-    if (!dryRun && existsSync(dir)) rmSync(dir, { recursive: true, force: true })
+    if (dryRun) return
+    if (existsSync(dir)) rmSync(dir, { recursive: true, force: true })
+    // 설치가 넣은 두 줄을 도로 가져간다 — 남겨 두면 제거한 뒤에도 우리가 만든
+    // 흔적이 .gitignore에 계속 남는다.
+    removeGitignoreEntries(root, IGNORE_ENTRIES)
   },
 })

package/lib/jsonfile.mjs

@@ -1,22 +1,41 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
 import { dirname } from 'node:path'
-import { parse, modify, applyEdits } from 'jsonc-parser'
+import { parse, modify, applyEdits, printParseErrorCode } from 'jsonc-parser'
+import { LocalizedError } from './i18n/index.mjs'
 
 const FORMAT = { formattingOptions: { insertSpaces: true, tabSize: 2 } }
+// 이 파일들은 도구가 읽는 JSONC다 — 주석과 후행 콤마는 정상이다.
+const PARSE = { allowTrailingComma: true }
 
 function readText(file) {
   return existsSync(file) ? readFileSync(file, 'utf8') : ''
 }
 
+// jsonc-parser의 parse는 던지지 않는다 — 닫는 괄호가 빠진 파일도 "복구한"
+// 값을 돌려준다. 그대로 두면 깨진 파일에 키를 끼워 넣고 has()는 설치됨으로
+// 읽어, 사용자는 파일이 깨진 것을 끝까지 모른다. 오류 목록을 받아 하나라도
+// 있으면 record.mjs의 readRecord처럼 어느 파일이 왜 깨졌는지 말하며 던진다.
+function parseStrict(text, file) {
+  const errors = []
+  const data = parse(text, errors, PARSE)
+  if (errors.length > 0) {
+    const [first] = errors
+    const line = text.slice(0, first.offset).split('\n').length
+    throw new LocalizedError('error.jsonInvalid', { path: file, message: `${printParseErrorCode(first.error)} (line ${line})` })
+  }
+  return data
+}
+
 export function readJson(file) {
   const text = readText(file)
   if (!text.trim()) return undefined
-  return parse(text)
+  return parseStrict(text, file)
 }
 
 export function setKey(file, path, value) {
   let text = readText(file)
   if (!text.trim()) text = '{}\n'
+  else parseStrict(text, file)
   const edits = modify(text, path, value, FORMAT)
   mkdirSync(dirname(file), { recursive: true })
   writeFileSync(file, applyEdits(text, edits))
@@ -25,7 +44,7 @@ export function setKey(file, path, value) {
 export function removeKey(file, path) {
   const text = readText(file)
   if (!text.trim()) return
-  if (getIn(parse(text), path) === undefined) return
+  if (getIn(parseStrict(text, file), path) === undefined) return
   const edits = modify(text, path, undefined, FORMAT)
   writeFileSync(file, applyEdits(text, edits))
 }

package/lib/status.mjs

@@ -103,9 +103,27 @@ export function formatStatus(report, t = createT('en')) {
   return lines.join('\n')
 }
 
-export async function runStatus(root, { json = false, log = console.log, t = createT('en') } = {}) {
+// 레지스트리의 최신 발행 버전. status는 진단 명령이라 네트워크가 없거나
+// 느려도 죽으면 안 된다 — 어떤 실패든 null로 떨어뜨리고 화면은 "최신"
+// 자리만 비운다. 시간 제한은 짧게 둔다: 이 한 줄 때문에 status가 20초를
+// 기다리면 진단 도구가 아니다.
+export const LATEST_TIMEOUT_MS = 5000
+const LATEST_URL = 'https://registry.npmjs.org/@rch4com%2Fagent-setup/latest'
+
+export async function fetchLatestVersion(fetchImpl = fetch) {
+  try {
+    const res = await fetchImpl(LATEST_URL, { signal: AbortSignal.timeout(LATEST_TIMEOUT_MS) })
+    if (!res.ok) return null
+    const version = (await res.json())?.version
+    return typeof version === 'string' && version ? version : null
+  } catch {
+    return null
+  }
+}
+
+export async function runStatus(root, { json = false, log = console.log, fetchImpl = fetch, t = createT('en') } = {}) {
   const { loadItems } = await import('./catalog.mjs')
-  const report = await collectStatus(root, { items: await loadItems() })
+  const report = await collectStatus(root, { items: await loadItems(), latest: await fetchLatestVersion(fetchImpl) })
   log(json ? JSON.stringify(report, null, 2) : formatStatus(report, t))
   return report
 }

package/lib/tomlfile.mjs

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
 import { dirname } from 'node:path'
 import { parse } from 'smol-toml'
+import { LocalizedError } from './i18n/index.mjs'
 
 function readText(file) {
   return existsSync(file) ? readFileSync(file, 'utf8') : ''
@@ -10,19 +11,27 @@ function escapeRegExp(text) {
   return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
+// 깨진 TOML은 읽기·쓰기 모두 거부한다. 예전에는 파싱 실패를 "섹션 없음"으로
+// 돌려줘, 닫는 대괄호가 빠진 파일 끝에 같은 섹션이 하나 더 붙고 사용자는
+// 파일이 깨진 것을 끝까지 몰랐다 — jsonfile.mjs의 JSON 규칙과 같다.
+function parseStrict(text, file) {
+  try {
+    return parse(text)
+  } catch (err) {
+    throw new LocalizedError('error.tomlInvalid', { path: file, message: err.message.split('\n')[0] })
+  }
+}
+
 export function hasSection(file, name) {
   const text = readText(file)
   if (!text.trim()) return false
-  try {
-    const data = parse(text)
-    return data.mcp_servers != null && Object.hasOwn(data.mcp_servers, name)
-  } catch {
-    return false
-  }
+  const data = parseStrict(text, file)
+  return data.mcp_servers != null && Object.hasOwn(data.mcp_servers, name)
 }
 
 export function appendSection(file, name, lines) {
   let text = readText(file)
+  if (text.trim()) parseStrict(text, file)
   if (text.length > 0 && !text.endsWith('\n')) text += '\n'
   const separator = text.length > 0 ? '\n' : ''
   text += `${separator}[mcp_servers.${name}]\n${lines.join('\n')}\n`
@@ -33,6 +42,7 @@ export function appendSection(file, name, lines) {
 export function removeSection(file, name) {
   const text = readText(file)
   if (!text) return
+  parseStrict(text, file)
   const lines = text.split('\n')
   const headerRe = new RegExp(`^\\s*\\[mcp_servers\\.${escapeRegExp(name)}(\\.|\\])`)
   const anyHeaderRe = /^\s*\[/

package/lib/tui/rows.mjs

@@ -38,9 +38,11 @@ function groupRank(group) {
   return i === -1 ? GROUP_ORDER.length : i
 }
 
+// 코드 포인트 단위로 자른다 — slice는 코드 유닛을 세어 이모지 같은 서로게이트
+// 쌍 한가운데를 자를 수 있다. 이 파일의 다른 자르기(width.cut)와 같은 규칙이다.
 function short(text, n = 60) {
-  const t = (text ?? '').replace(/\s+/g, ' ').trim()
-  return t.length > n ? `${t.slice(0, n - 1)}…` : t
+  const chars = [...(text ?? '').replace(/\s+/g, ' ').trim()]
+  return chars.length > n ? `${chars.slice(0, n - 1).join('')}…` : chars.join('')
 }
 
 // 검색어에 섹션의 두 로케일 라벨을 모두 넣는다 — 한국어 화면에서도 영어 탭

package/lib/tui/run.mjs

@@ -387,7 +387,15 @@ export async function runTui(root, opts = {}) {
         if (row?.id === 'action.language') { status = await cycleLanguage(); continue }
         if (row?.kind === 'action') {
           await suspend(async () => {
-            await row.run({ root, dryRun, skillMode, fetchImpl, catalogFile, log, confirm, t })
+            // 작업 하나의 예외가 화면 전체를 끌고 내려가면 안 된다 — 깨진
+            // 기록 파일(부트스트랩), 읽기 전용 설치 위치(카탈로그 동기화)가
+            // 던지면 TUI가 통째로 죽고 고르던 선택이 사라졌다. 적용(runApply)이
+            // 항목별로 격리하는 것과 같은 규칙이다.
+            try {
+              await row.run({ root, dryRun, skillMode, fetchImpl, catalogFile, log, confirm, t })
+            } catch (err) {
+              log(`\n${t('tui.actionFailed', { message: err.key ? t(err.key, err.params) : err.message })}`)
+            }
             await pause()
           })
           await recollect()

package/lib/update.mjs

@@ -11,9 +11,11 @@ import { RECORD_REL, managedKey, readRecord, toolVersion, writeRecord } from './
 import { LocalizedError, createT, toText } from './i18n/index.mjs'
 
 // git이 유일한 되돌리기 수단이다. 커밋되지 않은 변경 위에 덮어쓰면 사용자가
-// 잃은 것을 복구할 방법이 없다.
+// 잃은 것을 복구할 방법이 없다. 추적되지 않는 파일은 세지 않는다 — 갱신
+// 대상은 기록에 해시가 있는 추적 파일뿐이라, 스크래치 파일 하나가 --force를
+// 막을 이유가 없다.
 function assertCleanWorktree(root) {
-  const out = execFileSync('git', ['-C', root, 'status', '--porcelain'], { encoding: 'utf8' })
+  const out = execFileSync('git', ['-C', root, 'status', '--porcelain', '--untracked-files=no'], { encoding: 'utf8' })
   if (out.trim()) {
     throw new LocalizedError('error.forceNeedsCleanTree')
   }
@@ -65,10 +67,18 @@ export async function runUpdate(root, opts = {}) {
   const drift = results.filter((r) => r.action === 'drift')
   const updated = results.filter((r) => r.action === 'update')
   const created = results.filter((r) => r.action === 'create')
+  // 어댑터가 격리해 돌려준 실패다. 요약이 갱신·신규·드리프트만 세면 이
+  // 결과는 아무 데도 나오지 않고 종료 코드도 0이라, 링크가 끊긴 채 "갱신
+  // 0건"으로 끝난다. flow.mjs의 bootstrap과 같은 형식으로 보고한다.
+  const failed = results.filter((r) => !r.ok)
 
   if (!dryRun) writeRecord(root, { ...record, managed }, { dryRun, log: say, t })
 
   log('')
+  if (failed.length > 0) {
+    say(t('bootstrap.failures', { count: failed.length }))
+    for (const f of failed) say(`  ✖ ${f.path} — ${toText(t, f.message)}`)
+  }
   say(t('update.summary', { updated: updated.length, created: created.length, drift: drift.length }))
   if (drift.length > 0) {
     say(t('update.driftHeader'))
@@ -81,5 +91,5 @@ export async function runUpdate(root, opts = {}) {
     say(t('update.driftHint'))
   }
 
-  return { results, drift, record: { ...record, managed } }
+  return { results, drift, failed, record: { ...record, managed } }
 }

package/lib/width.mjs

@@ -11,7 +11,23 @@
 
 // 동아시아 글자는 터미널에서 두 칸을 차지한다. 전체 wcwidth 표 대신
 // 실제로 쓰이는 구간(한글·한자·가나·전각)만 넓게 센다.
+//
+// 결합 문자(악센트·변형 선택자·폭 없는 문자)는 0칸이다 — 1로 세면 `é`가
+// 두 칸으로 읽혀 열이 왼쪽으로 밀린다. 이모지는 2칸이다 — DESIGN.md의
+// 라벨·설명에 실려 오는데 1로 세면 그 행만 오른쪽으로 밀린다. U+2600 구간의
+// 기호(☀ 등)는 터미널마다 폭이 갈리는 모호 폭이라 넣지 않는다.
 function charWidth(cp) {
+  if ((cp >= 0x0300 && cp <= 0x036f) // 결합 분음 부호
+    || (cp >= 0x1ab0 && cp <= 0x1aff) || (cp >= 0x1dc0 && cp <= 0x1dff)
+    || (cp >= 0x20d0 && cp <= 0x20ff) // 기호용 결합 부호
+    || (cp >= 0xfe00 && cp <= 0xfe0f) // 변형 선택자
+    || (cp >= 0xfe20 && cp <= 0xfe2f)
+    || (cp >= 0x200b && cp <= 0x200f) // 폭 없는 공백·결합자·방향 표식
+    || cp === 0xfeff) return 0
+  if ((cp >= 0x1f300 && cp <= 0x1f64f) // 이모지 그림·표정
+    || (cp >= 0x1f680 && cp <= 0x1f6ff) // 교통·지도
+    || (cp >= 0x1f900 && cp <= 0x1f9ff) // 보충 이모지
+    || (cp >= 0x1fa70 && cp <= 0x1faff)) return 2
   return (cp >= 0x1100 && cp <= 0x115f) // 한글 자모
     || (cp >= 0x2e80 && cp <= 0xa4cf) // 한자 부수·가나·한자
     || (cp >= 0xac00 && cp <= 0xd7a3) // 한글 음절

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rch4com/agent-setup",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "Repository-scoped bootstrap and optional-item installer for using multiple coding-agent CLIs in one repository | 여러 코딩 에이전트 CLI를 한 저장소에서 함께 쓰기 위한 저장소 범위 부트스트랩과 선택 항목 설치기",
   "keywords": [
     "agents-md",