@rch4com/agent-setup 1.0.0

package/lib/catalog.mjs

@@ -0,0 +1,145 @@
+import { readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { execFileSync } from 'node:child_process'
+import { CLIS, CLI_IDS } from './clis.mjs'
+import { isPluginEnabled, enablePlugin, disablePlugin } from './claude-plugins.mjs'
+
+const ITEMS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'items')
+
+export async function loadItems() {
+  const files = readdirSync(ITEMS_DIR).filter((f) => f.endsWith('.mjs')).sort()
+  const items = []
+  for (const f of files) {
+    const mod = await import(pathToFileURL(join(ITEMS_DIR, f)).href)
+    items.push(validate(mod.default, f))
+  }
+  return items
+}
+
+function validate(item, file) {
+  for (const field of ['id', 'category', 'label', 'detect', 'install', 'uninstall']) {
+    if (!item?.[field]) throw new Error(`${file}: ${field} 누락`)
+  }
+  return item
+}
+
+function assertReasons(id, supports, unsupported) {
+  for (const cli of CLI_IDS) {
+    if (!supports.includes(cli) && !unsupported[cli]) {
+      throw new Error(`${id}: 미지원 CLI '${cli}'의 사유(unsupported.${cli})가 필요합니다`)
+    }
+  }
+}
+
+// shell 모드에서 Node는 명령과 인자를 공백으로 이어붙일 뿐 quote하지 않으므로
+// 직접 감싼다. 공백이 있을 때만 감싸면 셸 메타문자가 그대로 노출된다 —
+// `D:\R&D\repo` 아래에서 gstack clone 대상이 명령 두 개로 쪼개졌다.
+// 조건 없이 항상 감싸고, 셸별로 실제로 안전한 인용 규칙을 쓴다.
+//   - cmd.exe: 큰따옴표 안에서 & | ^ ( ) < >는 리터럴이다. 큰따옴표 자체는
+//     이 위치에서 일관되게 이스케이프할 방법이 없어(cmd는 \"를 해석하지 않는다)
+//     깨진 명령을 만드는 대신 거부한다 — Windows 경로에 올 수 없는 문자다.
+//     닫는 따옴표 앞의 백슬래시 연속은 자식의 argv 파서가 이스케이프로 읽으므로
+//     두 배로 늘린다(Windows 표준 규칙).
+//     남는 것은 %VAR% 확장뿐인데, 짝을 이룬 %가 실제 환경변수일 때만 치환되고
+//     그러면 경로가 달라져 명령이 실패한다 — 조용한 오작동이 아니라 보이는 실패다.
+//   - POSIX sh: 작은따옴표 안은 $ ` \ 까지 전부 리터럴이다. 안의 작은따옴표만
+//     '\'' 로 끊어 이어 붙인다. 큰따옴표로 감싸면 $(...)가 살아남는다.
+export function shellQuote(text, platform = process.platform) {
+  const s = String(text)
+  if (platform === 'win32') {
+    if (s.includes('"')) {
+      throw new Error(`셸에 넘길 수 없는 큰따옴표가 인자에 있습니다: ${s}`)
+    }
+    return `"${s.replace(/(\\*)$/, '$1$1')}"`
+  }
+  return `'${s.replace(/'/g, "'\\''")}'`
+}
+
+export function makeExec(dryRun, log = console.log) {
+  return (cmd, args, opts = {}) => {
+    if (dryRun) {
+      log(`  [dry-run] ${cmd} ${args.join(' ')}`)
+      return { ok: true, output: '' }
+    }
+    // Windows에서는 npx/claude가 .cmd 심이라 shell 경유가 필요하다.
+    const shell = opts.shell ?? process.platform === 'win32'
+    // shell + 인자 배열을 함께 넘기면 Node가 DEP0190으로 경고한다(인자가 quote 없이 이어붙기 때문).
+    // 어차피 우리가 직접 quote하므로, 완성된 한 줄 명령을 넘기고 인자 배열은 비운다.
+    const [file, fileArgs] = shell ? [[cmd, ...args].map((s) => shellQuote(s)).join(' '), []] : [cmd, args]
+    try {
+      const output = execFileSync(file, fileArgs, {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        ...opts,
+        shell,
+      })
+      return { ok: true, output }
+    } catch (err) {
+      return { ok: false, output: String(err.stderr ?? err.message) }
+    }
+  }
+}
+
+export function defineMcp({ id, label, server, supports = [...CLI_IDS], unsupported = {}, note }) {
+  assertReasons(id, supports, unsupported)
+  const name = id.replace(/^mcp\./, '')
+  return {
+    id, category: 'mcp', label, scope: 'project', supports, unsupported, note,
+    async detect({ root }) {
+      const present = supports.filter((cli) => CLIS[cli].has(root, name))
+      if (present.length === 0) return { status: 'absent' }
+      if (present.length === supports.length) return { status: 'installed' }
+      return { status: 'partial', detail: `등록됨: ${present.join(', ')} / 누락: ${supports.filter((c) => !present.includes(c)).join(', ')}` }
+    },
+    async install({ root, dryRun, log = () => {} }) {
+      for (const cli of supports) {
+        if (!CLIS[cli].has(root, name)) {
+          if (dryRun) log(`  [dry-run] ${CLIS[cli].label} 설정에 ${name} 등록`)
+          else CLIS[cli].add(root, name, server)
+        }
+      }
+    },
+    async uninstall({ root, dryRun, log = () => {} }) {
+      for (const cli of supports) {
+        if (CLIS[cli].has(root, name)) {
+          if (dryRun) log(`  [dry-run] ${CLIS[cli].label} 설정에서 ${name} 제거`)
+          else CLIS[cli].remove(root, name)
+        }
+      }
+    },
+  }
+}
+
+export function definePlugin({ id, label, installId, detectIds, marketplace, note }) {
+  const unsupported = Object.fromEntries(
+    CLI_IDS.filter((c) => c !== 'claude').map((c) => [c, 'Claude Code 전용 플러그인']),
+  )
+  return {
+    id, category: 'plugin', label, scope: 'project', supports: ['claude'], unsupported, note,
+    async detect({ root }) {
+      return { status: isPluginEnabled(root, detectIds) ? 'installed' : 'absent' }
+    },
+    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 (!r.ok) {
+        if (!dryRun) enablePlugin(root, installId, marketplace)
+        return { fallback: true, message: '설정 기록됨 — 다음 Claude Code 실행 시 다운로드됩니다' }
+      }
+    },
+    async uninstall(ctx) {
+      const { root, dryRun, exec } = ctx
+      const r = exec('claude', ['plugin', 'uninstall', installId], { cwd: root })
+      if (!r.ok && !dryRun) disablePlugin(root, detectIds)
+    },
+  }
+}
+
+export function defineSkill({ id, label, scope, detect, install, uninstall, note }) {
+  const unsupported = Object.fromEntries(
+    CLI_IDS.filter((c) => c !== 'claude').map((c) => [c, 'Claude Code 스킬 설치본']),
+  )
+  return { id, category: 'skill', label, scope, supports: ['claude'], unsupported, note, detect, install, uninstall }
+}

package/lib/claude-plugins.mjs

@@ -0,0 +1,64 @@
+import { repoPath, repoPathStrict } from './context.mjs'
+import { readJson, setKey, removeKey } from './jsonfile.mjs'
+
+const SETTINGS = '.claude/settings.json'
+
+function readSettings(root) {
+  return readJson(repoPath(root, SETTINGS)) ?? {}
+}
+
+// 쓰기 경로만 링크 이탈까지 검사한다 — 저장소 안 `.claude`가 홈을 가리키는
+// Junction이면 어휘적 검사는 통과하고 글로벌 settings.json이 수정된다.
+// clis.mjs의 add·remove, bootstrap의 apply.mjs와 같은 규칙.
+function settingsFile(root) {
+  return repoPathStrict(root, SETTINGS)
+}
+
+function enabledList(settings) {
+  const ep = settings.enabledPlugins
+  if (Array.isArray(ep)) return ep
+  if (ep && typeof ep === 'object') return Object.keys(ep).filter((k) => ep[k])
+  return []
+}
+
+export function isPluginEnabled(root, ids) {
+  const list = enabledList(readSettings(root))
+  return ids.some((id) => list.includes(id))
+}
+
+export function enablePlugin(root, id, marketplace) {
+  const file = settingsFile(root)
+  const settings = readSettings(root)
+  if (Array.isArray(settings.enabledPlugins)) {
+    if (!settings.enabledPlugins.includes(id)) {
+      setKey(file, ['enabledPlugins', settings.enabledPlugins.length], id)
+    }
+  } else {
+    setKey(file, ['enabledPlugins', id], true)
+  }
+  if (marketplace) {
+    setKey(file, ['extraKnownMarketplaces', marketplace.name], {
+      source: { source: 'github', repo: marketplace.repo },
+    })
+  }
+}
+
+export function disablePlugin(root, ids) {
+  const file = settingsFile(root)
+  const settings = readSettings(root)
+  if (Array.isArray(settings.enabledPlugins)) {
+    const kept = settings.enabledPlugins.filter((e) => !ids.includes(e))
+    setKey(file, ['enabledPlugins'], kept)
+  } else if (settings.enabledPlugins) {
+    for (const id of ids) removeKey(file, ['enabledPlugins', id])
+  }
+  // 제거한 플러그인이 쓰던 마켓플레이스만 정리 대상으로 삼는다 (무관한 사용자 항목 보존).
+  const candidates = new Set(ids.map((id) => id.slice(id.indexOf('@') + 1)))
+  const after = readSettings(root)
+  const remaining = enabledList(after).map((e) => e.slice(e.indexOf('@') + 1))
+  for (const mkt of candidates) {
+    if (!remaining.includes(mkt) && after.extraKnownMarketplaces?.[mkt] !== undefined) {
+      removeKey(file, ['extraKnownMarketplaces', mkt])
+    }
+  }
+}

package/lib/clis.mjs

@@ -0,0 +1,102 @@
+import { repoPath, repoPathStrict } from './context.mjs'
+import { readJson, setKey, removeKey, getIn } from './jsonfile.mjs'
+import { hasSection, appendSection, removeSection } from './tomlfile.mjs'
+
+// 읽기(has)는 어휘적 경로면 충분하고, 실제로 만들거나 고치는 경로(add·remove)만
+// 링크를 통한 저장소 이탈까지 검사한다 — bootstrap의 apply.mjs, design-md의
+// designPaths와 같은 규칙이다. 저장소 안 `.codex`·`.claude`가 홈을 가리키는
+// Junction일 때 MCP 등록 한 번으로 글로벌 설정이 생성·수정되는 것을 막는다.
+function jsonAdapter(relFile, topKey, toEntry) {
+  return {
+    has(root, name) {
+      const data = readJson(repoPath(root, relFile))
+      return getIn(data, [topKey, name]) !== undefined
+    },
+    add(root, name, server) {
+      setKey(repoPathStrict(root, relFile), [topKey, name], toEntry(server))
+    },
+    remove(root, name) {
+      removeKey(repoPathStrict(root, relFile), [topKey, name])
+    },
+  }
+}
+
+function tomlLines(server) {
+  if (server.kind === 'http') return [`url = ${JSON.stringify(server.url)}`]
+  return [
+    `command = ${JSON.stringify(server.command)}`,
+    `args = [${server.args.map((a) => JSON.stringify(a)).join(', ')}]`,
+  ]
+}
+
+export const CLIS = {
+  claude: {
+    label: 'Claude Code',
+    ...jsonAdapter('.mcp.json', 'mcpServers', (s) =>
+      s.kind === 'http'
+        ? { type: 'http', url: s.url }
+        : { type: 'stdio', command: s.command, args: s.args }),
+  },
+  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),
+  },
+  gemini: {
+    label: 'Gemini CLI',
+    ...jsonAdapter('.gemini/settings.json', 'mcpServers', (s) =>
+      s.kind === 'http' ? { httpUrl: s.url } : { command: s.command, args: s.args }),
+  },
+  opencode: {
+    label: 'OpenCode',
+    ...jsonAdapter('opencode.jsonc', 'mcp', (s) =>
+      s.kind === 'http'
+        ? { type: 'remote', url: s.url, enabled: true }
+        : { type: 'local', command: [s.command, ...s.args], enabled: true }),
+  },
+  kilo: {
+    label: 'Kilo Code',
+    ...jsonAdapter('.kilocode/mcp.json', 'mcpServers', (s) =>
+      s.kind === 'http'
+        ? { type: 'streamable-http', url: s.url, disabled: false }
+        : { command: s.command, args: s.args, disabled: false }),
+  },
+  kiro: {
+    label: 'Kiro',
+    ...jsonAdapter('.kiro/settings/mcp.json', 'mcpServers', (s) =>
+      s.kind === 'http'
+        ? { url: s.url, disabled: false, autoApprove: [] }
+        : { command: s.command, args: s.args, disabled: false, autoApprove: [] }),
+  },
+  kimi: {
+    label: 'Kimi Code',
+    ...jsonAdapter('.kimi-code/mcp.json', 'mcpServers', (s) =>
+      s.kind === 'http' ? { url: s.url } : { command: s.command, args: s.args }),
+  },
+  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),
+  },
+  copilot: {
+    label: 'GitHub Copilot CLI',
+    // Copilot CLI는 루트 .mcp.json도 읽지만(같은 이름이면 그쪽이 우선),
+    // 도구마다 자기 파일을 갖는 이 저장소의 패턴을 따라 .github/mcp.json에 쓴다.
+    ...jsonAdapter('.github/mcp.json', 'mcpServers', (s) =>
+      s.kind === 'http'
+        ? { type: 'http', url: s.url }
+        : { type: 'local', command: s.command, args: s.args }),
+  },
+  vscode: {
+    label: 'VS Code Copilot',
+    // VS Code는 최상위 키가 servers이고 로컬 서버 타입이 stdio다.
+    ...jsonAdapter('.vscode/mcp.json', 'servers', (s) =>
+      s.kind === 'http'
+        ? { type: 'http', url: s.url }
+        : { type: 'stdio', command: s.command, args: s.args }),
+  },
+}
+
+export const CLI_IDS = Object.keys(CLIS)

package/lib/context.mjs

@@ -0,0 +1,65 @@
+import { execFileSync } from 'node:child_process'
+import { lstatSync, realpathSync } from 'node:fs'
+import { dirname, resolve, sep } from 'node:path'
+
+export function findRepoRoot(cwd = process.cwd()) {
+  let out
+  try {
+    out = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' })
+  } catch {
+    throw new Error('git 저장소 안에서 실행해야 합니다.')
+  }
+  return resolve(out.trim())
+}
+
+export function repoPath(root, rel) {
+  const abs = resolve(root, rel)
+  const normRoot = resolve(root)
+  if (abs !== normRoot && !abs.startsWith(normRoot + sep)) {
+    throw new Error(`저장소 밖의 경로에는 쓸 수 없습니다: ${abs}`)
+  }
+  return abs
+}
+
+function pathExists(target) {
+  try {
+    lstatSync(target)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// repoPath의 어휘적 검사에 더해, 가장 가까운 존재하는 조상의 realpath가
+// 저장소 안인지 확인한다. 어휘적 검사만으로는 심볼릭 링크/Junction을 통한
+// 이탈을 막지 못한다. 부트스트랩의 모든 쓰기 경로가 이 함수를 쓴다.
+export function repoPathStrict(root, rel) {
+  const abs = repoPath(root, rel)
+
+  let probe = abs
+  while (!pathExists(probe)) {
+    const parent = dirname(probe)
+    if (parent === probe) break
+    probe = parent
+  }
+
+  let realProbe
+  try {
+    realProbe = realpathSync(probe)
+  } catch (err) {
+    // 경합으로 사라졌거나(ENOENT) 링크가 순환하는(ELOOP) 경우다.
+    // 원인을 알 수 없는 raw 예외 대신 진단 가능한 메시지로 바꾼다.
+    throw new Error(`경로를 확인할 수 없습니다: ${probe} (${err.code ?? err.message})`)
+  }
+
+  let realRoot
+  try {
+    realRoot = realpathSync(root)
+  } catch (err) {
+    throw new Error(`경로를 확인할 수 없습니다: ${root} (${err.code ?? err.message})`)
+  }
+  if (realProbe !== realRoot && !realProbe.startsWith(realRoot + sep)) {
+    throw new Error(`저장소 내부 경로가 외부 링크를 통해 이탈합니다: ${probe} -> ${realProbe}`)
+  }
+  return abs
+}

package/lib/deps.mjs

@@ -0,0 +1,19 @@
+// 선택적 의존성 로딩. 부트스트랩은 npm install 없이 돌아야 하므로
+// jsonc-parser·smol-toml에 닿는 모듈은 전부 동적 import로 가져오고,
+// 없을 때는 Node의 원시 메시지 대신 설치 방법을 안내한다.
+
+export const DEPS_HINT =
+  '이 기능에는 의존성이 필요합니다. 다음 중 하나를 실행하세요:\n' +
+  '  ./setup-agents.sh --tui\n' +
+  '  npm install --prefix agent-installer'
+
+export async function withDeps(load) {
+  try {
+    return await load()
+  } catch (err) {
+    // 모듈이 정말 없을 때만 안내로 바꾼다. 로드된 모듈 안에서 난 오류는
+    // 그대로 올려보내야 한다 — 삼키면 진짜 버그가 "의존성 없음"으로 둔갑한다.
+    if (err.code !== 'ERR_MODULE_NOT_FOUND') throw err
+    throw new Error(DEPS_HINT)
+  }
+}