@rch4com/agent-setup 1.0.0

package/lib/design-md/catalog.mjs

@@ -0,0 +1,268 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createHash } from 'node:crypto'
+import { repoPath, repoPathStrict } from '../context.mjs'
+import { PROVIDERS, getProvider } from './providers/index.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+export const CATALOG_PATH = join(HERE, 'catalog.json')
+
+export function loadCatalog(file = CATALOG_PATH) {
+  if (!existsSync(file)) return { updatedAt: null, providers: {} }
+  const text = readFileSync(file, 'utf8')
+  if (!text.trim()) return { updatedAt: null, providers: {} }
+  try {
+    return JSON.parse(text)
+  } catch (err) {
+    // 원시 SyntaxError는 어느 파일이 문제인지도, 어떻게 고치는지도 알려 주지
+    // 않는다. deps.mjs가 모듈 부재를 안내로 바꾸는 것과 같은 이유다.
+    throw new Error(
+      `design.md 카탈로그를 읽을 수 없습니다: ${file}\n${err.message}\n` +
+      '`design --sync=catalog`로 다시 만들 수 있습니다.',
+    )
+  }
+}
+
+export function saveCatalog(catalog, file = CATALOG_PATH) {
+  writeFileSync(file, JSON.stringify(catalog, null, 2) + '\n')
+}
+
+export function allEntries(catalog) {
+  return Object.values(catalog.providers ?? {}).flatMap((p) => p.entries ?? [])
+}
+
+export function sha256(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex')
+}
+
+// 응답 시간 제한. 맨 fetch에는 제한이 없어, 응답하지 않는 서버를 만나면
+// 동기화가 취소할 방법 없이 멈춘다 — 특히 TUI에서는 화면이 정지한 것처럼 보인다.
+export const FETCH_TIMEOUT_MS = 20000
+
+// 응답 본문 상한. DESIGN.md는 수십 KB, 가장 큰 응답인 tree API도 수 MB
+// 수준이다. 상한이 없으면 응답하는 서버가 무한 스트림을 흘려보낼 때
+// text()가 메모리를 다 쓸 때까지 읽는다 — 시간 제한은 이 경우를 막지 못한다
+// (데이터가 계속 오는 동안은 타임아웃이 걸리지 않는다).
+export const FETCH_MAX_BYTES = 8 * 1024 * 1024
+
+async function readCapped(res, limit) {
+  // body가 없는 구현(테스트의 가짜 fetch 등)은 그대로 읽는다.
+  if (!res.body?.getReader) return res.text()
+  const reader = res.body.getReader()
+  const decoder = new TextDecoder()
+  let text = ''
+  let total = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    total += value.byteLength
+    if (total > limit) {
+      await reader.cancel()
+      throw new Error(`응답이 상한(${limit} 바이트)을 넘었습니다: ${res.url}`)
+    }
+    text += decoder.decode(value, { stream: true })
+  }
+  return text + decoder.decode()
+}
+
+// 기본 fetch에 위 두 제한을 건다. 주입된 fetchImpl(테스트·대체 구현)은
+// 건드리지 않는다.
+export async function netFetch(url, opts = {}) {
+  // maxBytes는 우리 옵션이므로 fetch에 넘기지 않는다(기본값은 FETCH_MAX_BYTES).
+  const { maxBytes = FETCH_MAX_BYTES, ...init } = opts
+  const res = await fetch(url, { ...init, signal: init.signal ?? AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+  // 소비자는 ok·status·text()·json()만 쓴다. text()는 한 번만 읽을 수 있는
+  // 스트림을 감싸므로 결과를 기억해 두 번 호출에도 견디게 한다.
+  let body = null
+  const text = () => (body ??= readCapped(res, maxBytes))
+  return {
+    ok: res.ok,
+    status: res.status,
+    url: res.url,
+    headers: res.headers,
+    text,
+    json: async () => JSON.parse(await text()),
+  }
+}
+
+// 경로 세그먼트 하나로 안전한 이름인지 본다. 한글 등 유니코드는 허용하되
+// 경로 구분자·상위 이동·Windows 금지 문자·제어문자는 막는다.
+// (name은 원격 README 파싱이나 디렉터리 스캔에서 오므로 신뢰 경계 밖이다.)
+export function isSafeSegment(text) {
+  const value = String(text ?? '')
+  // 선행·후행 점은 숨김 파일이자 Windows에서 다루기 어려운 이름이다('.', '..' 포함).
+  if (!value || value.startsWith('.') || value.endsWith('.')) return false
+  // eslint-disable-next-line no-control-regex
+  return !/[\\/:*?"<>|\x00-\x1f]/.test(value)
+}
+
+// 라벨·카테고리·설명은 원격 README나 DESIGN.md 본문에서 온다. 목록과 TUI가
+// 이 값을 터미널에 그대로 찍으므로 제어문자를 걷어낸다 — ANSI 이스케이프가
+// 남아 있으면 화면을 지우거나 커서를 옮겨 목록을 위장할 수 있다.
+// C0/C1 제어문자에 더해 눈에 보이지 않으면서 표시 순서를 바꾸는 유니코드
+// 서식문자도 함께 지운다: bidi 오버라이드·isolate(U+202A~202E, U+2066~2069)는
+// 라벨을 거꾸로 그려 다른 항목처럼 보이게 만들고, 폭 없는 문자(U+200B~200F,
+// U+FEFF, U+00AD)는 이름이 같아 보이는 서로 다른 항목을 만든다.
+export function stripControl(text) {
+  return String(text ?? '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f\x7f-\x9f\u00ad\u061c\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u206f\ufeff]+/g, ' ')
+    .trim()
+}
+
+// 설치·번들 경로는 제공자별로 스코프한다: design-md/<provider>/<name>/DESIGN.md.
+// 동명 항목이 여러 제공자에 있어도 충돌 없이 공존한다.
+// 읽기는 어휘적 경로면 충분하다. 실제로 만들거나 지우는 경로만 링크를 통한
+// 저장소 이탈까지 검사한다 — bootstrap의 apply.mjs와 같은 규칙이다.
+// design-md가 저장소 밖을 가리키는 링크일 때 uninstall의 재귀 삭제가
+// 그 너머까지 닿는 것을 막는다.
+function designPaths(root, providerId, name, { strict = false } = {}) {
+  if (!isSafeSegment(providerId) || !isSafeSegment(name)) {
+    throw new Error(`잘못된 design.md 식별자: ${providerId}/${name}`)
+  }
+  const rel = `design-md/${providerId}/${name}`
+  const dir = strict ? repoPathStrict(root, rel) : repoPath(root, rel)
+  return { dir, file: join(dir, 'DESIGN.md') }
+}
+
+// 카탈로그 엔트리 1개를 item 인터페이스(engine.mjs 호환)로 변환한다.
+// provider와 fetchImpl을 클로저로 잡아 install/detect가 그것을 사용한다.
+export function defineDesignMd(entry, provider, { fetchImpl }) {
+  const { name, label, category, description } = entry
+  const providerId = provider.id
+  return {
+    id: `design.${providerId}.${name}`,
+    category: 'design',
+    providerId,
+    local: provider.local === true, // 디렉터리 스캔으로 찾은 로컬(사내) 정의
+    name,
+    // 화면에 나가는 세 값만 정화한다. name은 isSafeSegment가 이미 걸렀고
+    // 경로·URL에 쓰이므로 여기서 바꾸면 안 된다.
+    label: stripControl(label) || name,
+    designCategory: stripControl(category),
+    description: stripControl(description),
+    webUrl: provider.webUrl(name),
+    // 로컬(디렉터리) 항목은 웹 페이지가 없다 — 미리보기는 원본 파일을 연다.
+    previewPath: provider.local === true ? provider.fileUrl(name) : null,
+
+    async detect({ root }) {
+      return { status: existsSync(designPaths(root, providerId, name).file) ? 'installed' : 'absent' }
+    },
+
+    // fresh=false: 동봉 번들 우선(오프라인) → 없으면 네트워크.
+    // fresh=true: 번들 우회, 항상 네트워크 최신(업데이트/동기화용).
+    async install({ root, dryRun, fresh = false, log = () => {} }) {
+      // dry-run은 네트워크도 쓰기도 하지 않고 예정 동작만 알린다.
+      if (dryRun) {
+        log(`  [dry-run] design-md/${providerId}/${name}/DESIGN.md 작성`)
+        return
+      }
+      let text = fresh ? null : provider.bundledText?.(name, 'DESIGN.md')
+      if (text == null) text = await provider.fetchFile(fetchImpl, name, 'DESIGN.md')
+      if (text == null) throw new Error(`${providerId}/${name}: DESIGN.md 다운로드 실패`)
+      const { dir, file } = designPaths(root, providerId, name, { strict: true })
+      mkdirSync(dir, { recursive: true })
+      writeFileSync(file, text)
+    },
+
+    async uninstall({ root, dryRun, log = () => {} }) {
+      if (dryRun) {
+        log(`  [dry-run] design-md/${providerId}/${name} 제거`)
+        return
+      }
+      const { dir } = designPaths(root, providerId, name, { strict: true })
+      if (existsSync(dir)) rmSync(dir, { recursive: true, force: true })
+    },
+
+    // 오래된 항목 감지용: 로컬과 원본 DESIGN.md 해시 비교.
+    localText({ root }) {
+      const { file } = designPaths(root, providerId, name)
+      return existsSync(file) ? readFileSync(file, 'utf8') : null
+    },
+    async remoteText() {
+      return provider.fetchFile(fetchImpl, name, 'DESIGN.md')
+    },
+  }
+}
+
+// 큐레이션된 카탈로그 값이 우선, 비어 있으면 스캔에서 얻은 값으로 채운다.
+function mergeEntry(scanned, curated) {
+  if (!scanned) return curated
+  const pick = (a, b) => (a != null && String(a).trim() !== '' ? a : b)
+  return {
+    ...scanned,
+    ...curated,
+    label: pick(curated.label, scanned.label),
+    category: pick(curated.category, scanned.category),
+    description: pick(curated.description, scanned.description),
+  }
+}
+
+// 카탈로그 + 디렉터리 스캔 소스 → item 배열.
+// 디렉터리로 발견한 소스는 프로바이더 등록 없이도 목록에 오르고(사내 오프라인 정의),
+// 등록된 프로바이더가 있으면 그쪽(네트워크·웹 미리보기 지원)을 쓴다.
+// 카탈로그에만 있고 프로바이더도 스캔 결과도 없는 엔트리는 다룰 방법이 없어 건너뛴다.
+// id가 소스별로 유일하므로 동명 항목이 붕괴하지 않는다. (provider, name)순 정렬.
+export function buildItems(catalog, { fetchImpl, providers = PROVIDERS, sources = [] } = {}) {
+  const registered = new Map(providers.map((p) => [p.id, p]))
+  const blocks = new Map() // sourceId → { provider, entries: Map<name, entry> }
+
+  const blockFor = (id, provider) => {
+    let block = blocks.get(id)
+    if (!block) {
+      block = { provider, entries: new Map() }
+      blocks.set(id, block)
+    }
+    return block
+  }
+
+  // 1) 디렉터리 스캔 — 등록 여부와 무관하게 목록에 올린다.
+  for (const source of sources) {
+    const provider = registered.get(source.id) ?? getProvider(source.id) ?? source.provider
+    if (!provider) continue
+    const block = blockFor(source.id, provider)
+    for (const entry of source.entries ?? []) block.entries.set(entry.name, entry)
+  }
+
+  // 2) 카탈로그 — 라벨·카테고리·설명을 보강하고, 아직 없는 항목을 추가한다.
+  for (const [providerId, catalogBlock] of Object.entries(catalog.providers ?? {})) {
+    const provider = registered.get(providerId) ?? getProvider(providerId) ?? blocks.get(providerId)?.provider
+    if (!provider) continue
+    const block = blockFor(providerId, provider)
+    for (const entry of catalogBlock.entries ?? []) {
+      block.entries.set(entry.name, mergeEntry(block.entries.get(entry.name), entry))
+    }
+  }
+
+  const items = []
+  for (const block of blocks.values()) {
+    for (const entry of block.entries.values()) {
+      // 이름은 원격 README 파싱이나 디렉터리 스캔에서 오므로 신뢰 경계 밖이다.
+      // 설치 경로도 미리보기 URL도 이 이름을 쓰는데, 경로 검사는 designPaths가
+      // install 시점에만 한다. item이 만들어지는 이 한 곳에서 걸러 두면
+      // 목록·미리보기를 포함한 모든 소비자가 함께 안전해진다.
+      if (!isSafeSegment(entry.name)) continue
+      items.push(defineDesignMd(entry, block.provider, { fetchImpl }))
+    }
+  }
+  return items.sort((a, b) => a.providerId.localeCompare(b.providerId) || a.name.localeCompare(b.name))
+}
+
+// `--set`/`--preview` 토큰(`name` 또는 `provider/name`)을 item으로 해석한다.
+// 이름이 여러 제공자에 걸쳐 중복되면 제공자 지정을 요구한다.
+export function resolveTokens(items, tokensStr) {
+  const out = []
+  for (const tok of tokensStr.split(',').map((s) => s.trim()).filter(Boolean)) {
+    const slash = tok.indexOf('/')
+    const matches = slash >= 0
+      ? items.filter((i) => i.providerId === tok.slice(0, slash) && i.name === tok.slice(slash + 1))
+      : items.filter((i) => i.name === tok)
+    if (matches.length === 0) throw new Error(`알 수 없는 항목: ${tok}`)
+    if (matches.length > 1) {
+      throw new Error(`중복된 이름 '${tok}' — 제공자를 지정하세요: ${matches.map((m) => `${m.providerId}/${m.name}`).join(', ')}`)
+    }
+    out.push(matches[0])
+  }
+  return out
+}

package/lib/design-md/flow.mjs

@@ -0,0 +1,166 @@
+import { scan, planChanges, apply } from '../engine.mjs'
+import { loadCatalog, saveCatalog, buildItems, allEntries, sha256, resolveTokens, netFetch, CATALOG_PATH } from './catalog.mjs'
+import { PROVIDERS } from './providers/index.mjs'
+import { discoverSources, extraDirsFromEnv } from './scan.mjs'
+import { makeOpener, openPreview } from './open.mjs'
+
+const STATUS_LABEL = { installed: '설치됨', partial: '일부', absent: '미설치' }
+
+function report(results, log) {
+  const ACTION = { install: '설치', complete: '보완', uninstall: '제거' }
+  for (const r of results) {
+    log(`  ${r.ok ? '✔' : '✖'} ${ACTION[r.action]} ${r.item.label}${r.message ? ` — ${r.message}` : ''}`)
+  }
+}
+
+// ── 비대화형/공용 코어 ─────────────────────────────────────────────
+
+function printList(states, log) {
+  const byProvider = new Map()
+  for (const s of states) {
+    if (!byProvider.has(s.item.providerId)) byProvider.set(s.item.providerId, [])
+    byProvider.get(s.item.providerId).push(s)
+  }
+  for (const [pid, group] of byProvider) {
+    log(`[${pid}${group[0].item.local ? ' · 로컬' : ''}]`)
+    for (const s of group) {
+      log(`  ${STATUS_LABEL[s.status].padEnd(4)} ${s.item.name} — ${s.item.label} [${s.item.designCategory}]`)
+    }
+  }
+}
+
+// 미리보기는 관대하게 해석한다: 알 수 없거나 중복된 토큰은 예외 없이 안내하고 건너뛴다.
+function openPreviews(items, tokensStr, opener, log) {
+  for (const tok of tokensStr.split(',').map((s) => s.trim()).filter(Boolean)) {
+    const slash = tok.indexOf('/')
+    const matches = slash >= 0
+      ? items.filter((i) => i.providerId === tok.slice(0, slash) && i.name === tok.slice(slash + 1))
+      : items.filter((i) => i.name === tok)
+    if (matches.length === 0) { log(`  알 수 없는 항목: ${tok}`); continue }
+    if (matches.length > 1) {
+      log(`  중복된 이름 '${tok}' — 제공자를 지정하세요: ${matches.map((m) => `${m.providerId}/${m.name}`).join(', ')}`)
+      continue
+    }
+    openPreview(opener, matches[0], log)
+  }
+}
+
+// 보이는 집합(visibleStates) 안에서만 diff/적용한다.
+async function applyVisible(root, visibleStates, selectedIds, { dryRun, log }) {
+  const changes = planChanges(visibleStates, selectedIds)
+  if (changes.length === 0) { log('변경할 항목이 없습니다.'); return [] }
+  const results = await apply(root, changes, { dryRun, log })
+  report(results, log)
+  return results
+}
+
+async function installedItems(root, items) {
+  const out = []
+  for (const item of items) {
+    if ((await item.detect({ root })).status === 'installed') out.push(item)
+  }
+  return out
+}
+
+export async function refreshCatalog({ dryRun, fetchImpl, log, catalogFile = CATALOG_PATH }) {
+  const next = { updatedAt: new Date().toISOString(), providers: {} }
+  for (const provider of PROVIDERS) {
+    try {
+      const entries = await provider.fetchCatalog(fetchImpl)
+      next.providers[provider.id] = { label: provider.label, entries }
+      log(`  ${provider.label}: ${entries.length}개`)
+    } catch (err) {
+      log(`  ${provider.label}: 실패 — ${err.message}`)
+    }
+  }
+  const total = allEntries(next).length
+  if (total === 0) { log('가져온 항목이 없어 카탈로그를 갱신하지 않습니다.'); return { total: 0 } }
+  if (!dryRun) saveCatalog(next, catalogFile)
+  log(dryRun ? `  [dry-run] ${total}개로 갱신 예정` : `카탈로그 갱신됨: ${total}개`)
+  return { total }
+}
+
+export async function updateInstalled(root, items, { dryRun, log }) {
+  const installed = await installedItems(root, items)
+  if (installed.length === 0) { log('설치된 design.md가 없습니다.'); return }
+  for (const item of installed) {
+    try {
+      await item.install({ root, dryRun, fresh: true })
+      log(`  ✔ 업데이트 ${item.label}`)
+    } catch (err) {
+      log(`  ✖ 업데이트 ${item.label} — ${err.message}`)
+    }
+  }
+}
+
+export async function findStale(root, items, { log }) {
+  const installed = await installedItems(root, items)
+  const stale = []
+  for (const item of installed) {
+    const local = item.localText({ root })
+    if (local == null) continue
+    let remote
+    try { remote = await item.remoteText() } catch { remote = null }
+    if (remote == null) { log(`  ? ${item.label}: 원본 확인 실패`); continue }
+    if (sha256(local) !== sha256(remote)) stale.push(item)
+  }
+  return stale
+}
+
+// ── 진입점 ────────────────────────────────────────────────────────
+
+export async function runDesign(root, opts = {}) {
+  const {
+    dryRun = false,
+    list = false,
+    set = null,
+    sync = null,
+    preview = null,
+    fetchImpl = netFetch,
+    log = console.log,
+    designDirs = [],
+    env = process.env,
+    catalogFile = CATALOG_PATH,
+  } = opts
+  const opener = opts.opener ?? makeOpener(dryRun, log)
+
+  const catalog = loadCatalog(catalogFile)
+  // 디렉터리 스캔이 먼저다 — 프로바이더 등록 없이도 사내 정의가 목록에 오른다.
+  const sources = opts.sources ?? discoverSources({
+    ...(opts.bundleDir ? { bundleDir: opts.bundleDir } : {}),
+    extraDirs: [...extraDirsFromEnv(env), ...designDirs],
+    log,
+  })
+  const items = buildItems(catalog, { fetchImpl, sources })
+
+  if (list) {
+    printList(await scan(root, items), log)
+    return
+  }
+  if (preview != null) {
+    openPreviews(items, preview, opener, log)
+    return
+  }
+  if (sync != null) {
+    await runSync(root, items, { op: sync, dryRun, fetchImpl, log, catalogFile })
+    return
+  }
+  if (set != null) {
+    const selected = new Set(resolveTokens(items, set).map((i) => i.id))
+    await applyVisible(root, await scan(root, items), selected, { dryRun, log })
+    return
+  }
+  printList(await scan(root, items), log)
+}
+
+async function runSync(root, items, { op: chosen, dryRun, fetchImpl, log, catalogFile }) {
+  if (chosen === 'catalog') { await refreshCatalog({ dryRun, fetchImpl, log, catalogFile }); return }
+  if (chosen === 'installed') { await updateInstalled(root, items, { dryRun, log }); return }
+  if (chosen === 'stale') {
+    const stale = await findStale(root, items, { log })
+    if (stale.length === 0) { log('모든 설치본이 최신입니다.'); return }
+    log(`오래된 항목 ${stale.length}개: ${stale.map((i) => i.name).join(', ')}`)
+    return
+  }
+  log(`알 수 없는 동기화 작업: ${chosen}`)
+}

package/lib/design-md/open.mjs

@@ -0,0 +1,50 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+
+// 미리보기 대상은 신뢰 경계 밖이다 — 이름이 원격 README 파싱이나 디렉터리
+// 스캔에서 온다. http(s) URL이거나 실제로 존재하는 로컬 경로일 때만 OS에
+// 넘긴다. `javascript:`처럼 스킴만 바꾼 대상이 기본 앱으로 열리지 않게 한다.
+export function isOpenableTarget(target) {
+  const text = String(target ?? '')
+  // eslint-disable-next-line no-control-regex
+  if (!text || /[\x00-\x1f\x7f]/.test(text)) return false
+  if (/^https?:\/\//i.test(text)) return true
+  return existsSync(text)
+}
+
+// OS 기본 브라우저/앱으로 target(URL 또는 파일)을 연다. 주입 가능(테스트 대체).
+export function makeOpener(dryRun, log = console.log) {
+  return (target) => {
+    if (dryRun) {
+      log(`  [dry-run] open ${target}`)
+      return { ok: true }
+    }
+    if (!isOpenableTarget(target)) return { ok: false, output: '열 수 있는 대상이 아닙니다' }
+    // Windows에서 `cmd /c start`를 쓰지 않는다 — Node는 셸 없이 cmd를 부를 때
+    // 공백 없는 인자를 quote하지 않고, cmd는 `&`·`|`를 명령 구분자로 읽는다.
+    // 그러면 이름에 섞인 `&`가 곧바로 명령 실행이 된다. rundll32는 셸을 거치지
+    // 않아 인자가 그대로 전달되고, URL과 로컬 파일을 모두 기본 앱으로 연다.
+    const [cmd, args] =
+      process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', target]] :
+      process.platform === 'darwin' ? ['open', [target]] :
+      ['xdg-open', [target]]
+    try {
+      execFileSync(cmd, args, { stdio: 'ignore' })
+      return { ok: true }
+    } catch (err) {
+      return { ok: false, output: String(err.message) }
+    }
+  }
+}
+
+// 항목의 미리보기를 연다: 웹 URL이 있으면 그 페이지, 로컬 항목은 원본 파일을 기본 앱으로.
+export function openPreview(opener, item, log = console.log) {
+  const target = item.webUrl ?? item.previewPath ?? null
+  if (!target) {
+    log(`  ${item.label}: 미리보기 URL이 없습니다.`)
+    return { ok: false }
+  }
+  const r = opener(target)
+  if (!r.ok) log(`  ${item.label}: 열기 실패 — 직접 여세요: ${target}`)
+  return r
+}

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

@@ -0,0 +1,114 @@
+// 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

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

@@ -0,0 +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)
+}