@rch4com/agent-setup 1.1.0 → 1.4.0

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

@@ -1,114 +1,124 @@
-// awesome-design-md (VoltAgent) 프로바이더.
-// 카탈로그: README `## Collection`의 `### 카테고리` + 링크 목록을 파싱한다.
-// 링크 URL `getdesign.md/<name>/design-md`의 <name>이 곧 GitHub 폴더명이다.
-// 파일: 폴더에는 DESIGN.md만 있다(preview.html 없음). 렌더된 미리보기는 웹페이지.
-import { existsSync, readFileSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-// lib/design-md/cache/<name>/DESIGN.md — 인스톨러에 동봉된 오프라인 번들.
-const BUNDLE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'cache')
-
-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`
-const TREE_URL = `https://api.github.com/repos/${REPO}/git/trees/${BRANCH}?recursive=1`
-const UNCATEGORIZED = '기타'
-
-const ENTRY_RE = /^-\s*\[\*\*(.+?)\*\*\]\(\s*https?:\/\/getdesign\.md\/([^/)]+)\/design-md\s*\)\s*-\s*(.*)$/
-
-// README `## Collection` 블록만 대상으로 카테고리·항목을 뽑는다.
-export function parseReadme(md) {
-  const lines = md.split(/\r?\n/)
-  const entries = []
-  let inCollection = false
-  let category = UNCATEGORIZED
-  for (const line of lines) {
-    const h2 = /^##\s+(.*)$/.exec(line)
-    if (h2) {
-      inCollection = /^collection\b/i.test(h2[1].trim())
-      continue
-    }
-    if (!inCollection) continue
-    const h3 = /^###\s+(.*)$/.exec(line)
-    if (h3) {
-      category = h3[1].trim()
-      continue
-    }
-    const m = ENTRY_RE.exec(line.trim())
-    if (m) {
-      entries.push({ name: m[2].trim(), label: m[1].trim(), category, description: m[3].trim() })
-    }
-  }
-  return entries
-}
-
-// tree API에서 design-md/<name>/ 폴더명 집합을 뽑는다(orphan 보강용).
-export function parseTreeNames(treeJson) {
-  const names = new Set()
-  for (const e of treeJson?.tree ?? []) {
-    const m = /^design-md\/([^/]+)\//.exec(e.path)
-    if (m) names.add(m[1])
-  }
-  return names
-}
-
-export const awesomeDesignMd = {
-  id: 'awesome-design-md',
-  label: 'awesome-design-md (VoltAgent)',
-  files: ['DESIGN.md'],
-
-  fileUrl(name, file = 'DESIGN.md') {
-    return `${RAW_BASE}/${encodeURIComponent(name)}/${file}`
-  },
-
-  // fileUrl과 같이 인코딩한다 — name은 원격 README에서 오므로, 그대로 이어
-  // 붙이면 URL이 아닌 문자가 미리보기 대상 문자열에 섞인다.
-  webUrl(name) {
-    return `https://getdesign.md/${encodeURIComponent(name)}/design-md`
-  },
-
-  bundlePath(name, file = 'DESIGN.md') {
-    return join(BUNDLE_DIR, this.id, name, file)
-  },
-
-  // 동봉 번들에서 읽는다(없으면 null). 오프라인 설치용.
-  bundledText(name, file = 'DESIGN.md') {
-    if (/[\\/]/.test(name)) return null
-    const p = this.bundlePath(name, file)
-    return existsSync(p) ? readFileSync(p, 'utf8') : null
-  },
-
-  async fetchFile(fetchImpl, name, file = 'DESIGN.md') {
-    const res = await fetchImpl(this.fileUrl(name, file))
-    if (!res.ok) return null
-    return res.text()
-  },
-
-  // README 파싱(주) + tree orphan 보강(선택). 이름순 정렬 반환.
-  async fetchCatalog(fetchImpl) {
-    const readmeRes = await fetchImpl(README_URL)
-    if (!readmeRes.ok) throw new Error(`README 가져오기 실패: HTTP ${readmeRes.status}`)
-    const entries = parseReadme(await readmeRes.text())
-    const seen = new Set(entries.map((e) => e.name))
-
-    try {
-      const treeRes = await fetchImpl(TREE_URL, { headers: { 'User-Agent': 'agent-installer' } })
-      if (treeRes.ok) {
-        for (const name of parseTreeNames(await treeRes.json())) {
-          if (!seen.has(name)) {
-            entries.push({ name, label: name, category: UNCATEGORIZED, description: '' })
-            seen.add(name)
-          }
-        }
-      }
-    } catch {
-      // tree 실패는 무시 — README만으로도 카탈로그는 유효하다.
-    }
-
-    return entries.sort((a, b) => a.name.localeCompare(b.name))
-  },
-}
-
-export default awesomeDesignMd
+// awesome-design-md (VoltAgent) 프로바이더.
+// 카탈로그: README `## Collection`의 `### 카테고리` + 링크 목록을 파싱한다.
+// 링크 URL `getdesign.md/<name>/design-md`의 <name>이 곧 GitHub 폴더명이다.
+// 파일: 폴더에는 DESIGN.md만 있다(preview.html 없음). 렌더된 미리보기는 웹페이지.
+import { existsSync, readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { LocalizedError } from '../../i18n/index.mjs'
+
+// lib/design-md/cache/<name>/DESIGN.md — 인스톨러에 동봉된 오프라인 번들.
+const BUNDLE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'cache')
+
+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와 같은 값이어야 한다 — 둘 다 카테고리 못 얻은
+// 항목이 모이는 자리라, 갈라지면 같은 그룹이 헤더 두 개로 쪼개진다.
+export const UNCATEGORIZED = '__other'
+
+const ENTRY_RE = /^-\s*\[\*\*(.+?)\*\*\]\(\s*https?:\/\/getdesign\.md\/([^/)]+)\/design-md\s*\)\s*-\s*(.*)$/
+
+// README `## Collection` 블록만 대상으로 카테고리·항목을 뽑는다.
+export function parseReadme(md) {
+  const lines = md.split(/\r?\n/)
+  const entries = []
+  let inCollection = false
+  let category = UNCATEGORIZED
+  for (const line of lines) {
+    const h2 = /^##\s+(.*)$/.exec(line)
+    if (h2) {
+      inCollection = /^collection\b/i.test(h2[1].trim())
+      continue
+    }
+    if (!inCollection) continue
+    const h3 = /^###\s+(.*)$/.exec(line)
+    if (h3) {
+      category = h3[1].trim()
+      continue
+    }
+    const m = ENTRY_RE.exec(line.trim())
+    if (m) {
+      entries.push({ name: m[2].trim(), label: m[1].trim(), category, description: m[3].trim() })
+    }
+  }
+  return entries
+}
+
+// tree API에서 design-md/<name>/ 폴더명 집합을 뽑는다(orphan 보강용).
+export function parseTreeNames(treeJson) {
+  const names = new Set()
+  for (const e of treeJson?.tree ?? []) {
+    const m = /^design-md\/([^/]+)\//.exec(e.path)
+    if (m) names.add(m[1])
+  }
+  return names
+}
+
+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}`
+  },
+
+  // fileUrl과 같이 인코딩한다 — name은 원격 README에서 오므로, 그대로 이어
+  // 붙이면 URL이 아닌 문자가 미리보기 대상 문자열에 섞인다.
+  webUrl(name) {
+    return `https://getdesign.md/${encodeURIComponent(name)}/design-md`
+  },
+
+  bundlePath(name, file = 'DESIGN.md') {
+    return join(BUNDLE_DIR, this.id, name, file)
+  },
+
+  // 동봉 번들에서 읽는다(없으면 null). 오프라인 설치용.
+  bundledText(name, file = 'DESIGN.md') {
+    if (/[\\/]/.test(name)) return null
+    const p = this.bundlePath(name, file)
+    return existsSync(p) ? readFileSync(p, 'utf8') : null
+  },
+
+  async fetchFile(fetchImpl, name, file = 'DESIGN.md') {
+    const res = await fetchImpl(this.fileUrl(name, file))
+    if (!res.ok) return null
+    return res.text()
+  },
+
+  // README 파싱(주) + tree orphan 보강(선택). 이름순 정렬 반환.
+  async fetchCatalog(fetchImpl) {
+    const readmeRes = await fetchImpl(README_URL)
+    if (!readmeRes.ok) throw new LocalizedError('error.readmeFetch', { status: readmeRes.status })
+    const entries = parseReadme(await readmeRes.text())
+    const seen = new Set(entries.map((e) => e.name))
+
+    try {
+      const treeRes = await fetchImpl(TREE_URL, { headers: { 'User-Agent': 'agent-installer' } })
+      if (treeRes.ok) {
+        for (const name of parseTreeNames(await treeRes.json())) {
+          if (!seen.has(name)) {
+            entries.push({ name, label: name, category: UNCATEGORIZED, description: '' })
+            seen.add(name)
+          }
+        }
+      }
+    } catch {
+      // tree 실패는 무시 — README만으로도 카탈로그는 유효하다.
+    }
+
+    return entries.sort((a, b) => a.name.localeCompare(b.name))
+  },
+}
+
+export default awesomeDesignMd

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

@@ -1,9 +1,9 @@
-// design.md 프로바이더 레지스트리 — 소스 확장 지점.
-// 새 소스 추가 = 프로바이더 모듈 1개 작성 + 여기 등록.
-import { awesomeDesignMd } from './awesome-design-md.mjs'
-
-export const PROVIDERS = [awesomeDesignMd]
-
-export function getProvider(id) {
-  return PROVIDERS.find((p) => p.id === id)
-}
+// design.md 프로바이더 레지스트리 — 소스 확장 지점.
+// 새 소스 추가 = 프로바이더 모듈 1개 작성 + 여기 등록.
+import { awesomeDesignMd } from './awesome-design-md.mjs'
+
+export const PROVIDERS = [awesomeDesignMd]
+
+export function getProvider(id) {
+  return PROVIDERS.find((p) => p.id === id)
+}

package/lib/design-md/scan.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url'
 import { StringDecoder } from 'node:string_decoder'
 import { isSafeSegment } from './catalog.mjs'
 import { PROVIDERS } from './providers/index.mjs'
+import { createT } from '../i18n/index.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 export const BUNDLE_DIR = join(HERE, 'cache')
@@ -25,8 +26,11 @@ const SKIP_DIRS = new Set(['node_modules', '.git', '.svn'])
 const FM_OPEN = /^---[ \t]*\r?\n/
 const FM_CLOSE = /\r?\n---[ \t]*(\r?\n|$)/
 
-export const BUNDLE_CATEGORY = '기타' // 번들 캐시에서 카테고리를 못 얻었을 때
-export const LOCAL_CATEGORY = '사내' // 외부(사내) 경로에서 카테고리를 못 얻었을 때
+// 카테고리는 정렬 키이자 그룹 헤더다. 표시 문자열을 그대로 쓰면 번역하는
+// 순간 정렬과 그룹 묶기가 어긋나므로 id를 두고 표시할 때만 번역한다.
+// tui/rows.mjs의 CATCH_ALL_CATEGORY와 같은 값이어야 한다.
+export const BUNDLE_CATEGORY = '__other'
+export const LOCAL_CATEGORY = '__local'
 
 // 설치 경로 `design-md/<소스>/<이름>/`에 쓰이므로 경로에 위험한 문자만 걷어낸다.
 // 한글 등 유니코드 이름은 그대로 살린다 — 사내 디렉터리명이 대개 그렇다.
@@ -165,7 +169,7 @@ function subdirs(dir) {
 // 디렉터리 트리에서 DESIGN.md를 찾아 엔트리로 만든다.
 // `<루트>/<카테고리…>/<이름>/DESIGN.md` — DESIGN.md가 있는 폴더가 곧 항목(리프)이다.
 // 루트 바로 아래 DESIGN.md가 있으면 루트 폴더명이 항목 이름이 된다.
-export function scanDesignDir(dir, { defaultCategory = LOCAL_CATEGORY, maxDepth = MAX_DEPTH, log } = {}) {
+export function scanDesignDir(dir, { defaultCategory = LOCAL_CATEGORY, maxDepth = MAX_DEPTH, log, t = createT('en') } = {}) {
   const root = resolve(dir)
   const entries = []
   const seen = new Set()
@@ -177,7 +181,7 @@ export function scanDesignDir(dir, { defaultCategory = LOCAL_CATEGORY, maxDepth
     const prefixed = sanitizeId([...segs.slice(0, -1), name].join('-'))
     let candidate = prefixed
     for (let n = 2; seen.has(candidate); n++) candidate = `${prefixed}-${n}`
-    if (log) log(`  design.md 이름이 겹쳐 '${candidate}'로 구분합니다: ${segs.join('/')}`)
+    if (log) log(t('design.nameClash', { picked: candidate, path: segs.join('/') }))
     return candidate
   }
 
@@ -251,7 +255,7 @@ export function makeDirProvider({ id, label, dir, entries }) {
 
 // 번들 캐시 하위 디렉터리 + 지정한 외부 경로를 소스 목록으로 만든다.
 // 반환: [{ id, dir, label, bundled, entries, provider }]
-export function discoverSources({ bundleDir = BUNDLE_DIR, extraDirs = [], reservedIds, log } = {}) {
+export function discoverSources({ bundleDir = BUNDLE_DIR, extraDirs = [], reservedIds, log, t = createT('en') } = {}) {
   const sources = []
   const usedIds = new Set()
   // 등록된 프로바이더 id는 번들 캐시 전용이다. 외부 경로가 그 id를 차지하면
@@ -259,18 +263,18 @@ export function discoverSources({ bundleDir = BUNDLE_DIR, extraDirs = [], reserv
   const reserved = new Set(reservedIds ?? PROVIDERS.map((p) => p.id))
 
   const add = ({ id, dir, bundled, defaultCategory }) => {
-    const entries = scanDesignDir(dir, { defaultCategory, log })
+    const entries = scanDesignDir(dir, { defaultCategory, log, t })
     if (entries.length === 0) {
-      if (!bundled && log) log(`  design.md 소스에 DESIGN.md가 없습니다: ${dir}`)
+      if (!bundled && log) log(t('design.noDesignFile', { path: dir }))
       return
     }
     const base = sanitizeId(id)
     const taken = (candidate) => usedIds.has(candidate) || (!bundled && reserved.has(candidate))
     let uid = base
     for (let n = 2; taken(uid); n++) uid = `${base}-${n}`
-    if (uid !== base && log) log(`  design.md 소스 id가 겹쳐 '${uid}'로 사용합니다: ${dir}`)
+    if (uid !== base && log) log(t('design.sourceIdClash', { picked: uid, path: dir }))
     usedIds.add(uid)
-    const label = bundled ? uid : `${uid} (로컬)`
+    const label = bundled ? uid : t('design.localSuffix', { id: uid })
     sources.push({ id: uid, dir, label, bundled, entries, provider: makeDirProvider({ id: uid, label, dir, entries }) })
   }
 
@@ -282,7 +286,7 @@ export function discoverSources({ bundleDir = BUNDLE_DIR, extraDirs = [], reserv
   for (const spec of extraDirs) {
     const { id, dir } = parseDirSpec(spec)
     if (!existsSync(dir)) {
-      if (log) log(`  design.md 경로를 찾을 수 없습니다: ${dir}`)
+      if (log) log(t('design.pathMissing', { path: dir }))
       continue
     }
     add({ id, dir, bundled: false, defaultCategory: LOCAL_CATEGORY })

package/lib/engine.mjs

@@ -1,44 +1,48 @@
-import { makeExec } from './catalog.mjs'
-
-export async function scan(root, items) {
-  const states = []
-  for (const item of items) {
-    try {
-      const r = await item.detect({ root })
-      states.push({ item, status: r.status, detail: r.detail })
-    } catch (err) {
-      states.push({ item, status: 'absent', detail: `감지 실패: ${err.message}` })
-    }
-  }
-  return states
-}
-
-export function planChanges(states, selectedIds) {
-  const changes = []
-  for (const { item, status } of states) {
-    const selected = selectedIds.has(item.id)
-    if (selected && status === 'absent') changes.push({ item, action: 'install' })
-    else if (selected && status === 'partial') changes.push({ item, action: 'complete' })
-    else if (!selected && status !== 'absent') changes.push({ item, action: 'uninstall' })
-  }
-  return changes
-}
-
-export async function apply(root, changes, { dryRun = false, log = console.log } = {}) {
-  const exec = makeExec(dryRun, log)
-  const results = []
-  for (const { item, action } of changes) {
-    // log까지 넘긴다 — 파일을 직접 쓰는 항목(MCP·design.md)은 exec를 거치지
-    // 않아 dry-run에서 아무것도 보고하지 못했다. 결과줄은 ✔ 설치라고 찍히는데
-    // 무엇이 바뀔지는 알 수 없는 상태였다.
-    const ctx = { root, dryRun, exec, log }
-    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 })
-    } catch (err) {
-      results.push({ item, action, ok: false, message: err.message })
-    }
-  }
-  return results
-}
+import { makeExec } from './catalog.mjs'
+import { createT, msg } from './i18n/index.mjs'
+
+export async function scan(root, items) {
+  const states = []
+  for (const item of items) {
+    try {
+      const r = await item.detect({ root })
+      states.push({ item, status: r.status, detail: r.detail })
+    } catch (err) {
+      states.push({ item, status: 'absent', detail: msg('item.scanFailed', { message: err.message }) })
+    }
+  }
+  return states
+}
+
+export function planChanges(states, selectedIds) {
+  const changes = []
+  for (const { item, status } of states) {
+    const selected = selectedIds.has(item.id)
+    if (selected && status === 'absent') changes.push({ item, action: 'install' })
+    else if (selected && status === 'partial') changes.push({ item, action: 'complete' })
+    else if (!selected && status !== 'absent') changes.push({ item, action: 'uninstall' })
+  }
+  return changes
+}
+
+export async function apply(root, changes, { dryRun = false, log = console.log, t = createT('en') } = {}) {
+  const exec = makeExec(dryRun, log)
+  const results = []
+  for (const { item, action } of changes) {
+    // log까지 넘긴다 — 파일을 직접 쓰는 항목(MCP·design.md)은 exec를 거치지
+    // 않아 dry-run에서 아무것도 보고하지 못했다. 결과줄은 ✔ 설치라고 찍히는데
+    // 무엇이 바뀔지는 알 수 없는 상태였다.
+    const ctx = { root, dryRun, exec, log, t }
+    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 })
+    } 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 })
+    }
+  }
+  return results
+}

package/lib/gitignore.mjs

@@ -1,18 +1,18 @@
-import { readFileSync, writeFileSync, existsSync } from 'node:fs'
-import { repoPathStrict } from './context.mjs'
-
-export function ensureGitignoreEntries(root, entries) {
-  // 함수의 목적 자체가 쓰기이므로 맨 앞에서 한 번 엄격 검사한다 —
-  // bootstrap의 ensureIgnore와 같은 규칙. 어휘적 검사만으로는 .gitignore가
-  // 저장소 밖을 가리키는 링크일 때를 막지 못한다.
-  const file = repoPathStrict(root, '.gitignore')
-  const text = existsSync(file) ? readFileSync(file, 'utf8') : ''
-  const lines = new Set(text.split(/\r?\n/))
-  const missing = entries.filter((e) => !lines.has(e))
-  if (missing.length === 0) return
-  // 파일의 우세 줄바꿈을 따른다 — CRLF 파일에 덧붙인 줄만 LF로 섞이지 않게.
-  // apply.mjs의 ensureJsonKeys가 JSON에 대해 지키는 규칙과 같다.
-  const eol = text.includes('\r\n') ? '\r\n' : '\n'
-  const sep = text.length === 0 || text.endsWith('\n') ? '' : eol
-  writeFileSync(file, text + sep + missing.join(eol) + eol)
-}
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { repoPathStrict } from './context.mjs'
+
+export function ensureGitignoreEntries(root, entries) {
+  // 함수의 목적 자체가 쓰기이므로 맨 앞에서 한 번 엄격 검사한다 —
+  // bootstrap의 ensureIgnore와 같은 규칙. 어휘적 검사만으로는 .gitignore가
+  // 저장소 밖을 가리키는 링크일 때를 막지 못한다.
+  const file = repoPathStrict(root, '.gitignore')
+  const text = existsSync(file) ? readFileSync(file, 'utf8') : ''
+  const lines = new Set(text.split(/\r?\n/))
+  const missing = entries.filter((e) => !lines.has(e))
+  if (missing.length === 0) return
+  // 파일의 우세 줄바꿈을 따른다 — CRLF 파일에 덧붙인 줄만 LF로 섞이지 않게.
+  // apply.mjs의 ensureJsonKeys가 JSON에 대해 지키는 규칙과 같다.
+  const eol = text.includes('\r\n') ? '\r\n' : '\n'
+  const sep = text.length === 0 || text.endsWith('\n') ? '' : eol
+  writeFileSync(file, text + sep + missing.join(eol) + eol)
+}