@rch4com/agent-setup 1.20.0 → 1.21.0

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/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,7 @@ 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.',
 
@@ -184,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}',
@@ -345,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,7 @@ 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}을 씁니다 — 도구를 올리거나 기록을 다시 만드세요.',
 
@@ -178,6 +180,7 @@ export default {
   'msg.readFailed': '읽기 실패',
   'msg.noRootObject': '루트 객체 없음',
   'msg.foreignLink': '다른 위치를 가리키는 링크',
+  'log.skill.relinkDangling': '경고: {path} 링크의 대상이 더는 존재하지 않습니다(저장소를 옮겼나요?). 다시 만듭니다.',
   'msg.unmanagedExisting': '관리 대상이 아닌 기존 항목',
   'msg.noManagedBlock': '관리 블록 없음',
   'msg.linkFailed': '링크 생성 실패: {message}',
@@ -335,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/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/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.20.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",