@rch4com/agent-setup 1.28.0 → 2.2.0

package/lib/probe.mjs

@@ -0,0 +1,136 @@
+// 감지 질의. 항목 detect는 여기 캐시만 조회한다 — CLI 목록 명령은 스캔
+// 한 번에 질의마다 한 번만 돈다. 쓰기는 하지 않는다: 읽는 파일도 CLI가
+// 소유한 설정이라, 고치는 일은 그 CLI의 명령이 맡는다.
+import { existsSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { CLIS } from './clis.mjs'
+import { readJson } from './jsonfile.mjs'
+import { findSkillDir } from './skills-registry.mjs'
+
+// 목록 명령 하나에 주는 시간. 설치 명령(10분)과 달리 목록은 금방 끝나야
+// 정상이다 — 멈춘 CLI 하나가 화면 전체의 스캔을 붙잡지 않게 한다.
+const PROBE_TIMEOUT_MS = 60 * 1000
+
+// 구분자는 실행 중인 OS가 아니라 platform 인자를 따른다 — Windows의 PATH를
+// 콜론으로 쪼개면 드라이브 문자(C:)에서 끊긴다.
+export function onPath(bin, { env = process.env, platform = process.platform, exists = existsSync } = {}) {
+  const win = platform === 'win32'
+  const dirs = String(env.PATH ?? env.Path ?? '').split(win ? ';' : ':').filter(Boolean)
+  // Windows는 확장자 없는 파일을 실행하지 않는다 — PATHEXT 후보만 본다.
+  const exts = win ? String(env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean) : ['']
+  return dirs.some((dir) => exts.some((ext) => exists(join(dir, `${bin}${ext}`))))
+}
+
+// `agy mcp list`는 JSON을 주지 않는다. 머리줄(NAME …) 뒤 각 줄의 첫 열이 이름이다.
+export function parseAgyMcpList(text) {
+  const lines = String(text).split(/\r?\n/).map((l) => l.trim()).filter(Boolean)
+  const head = lines.findIndex((l) => /^NAME\s/.test(l))
+  return head === -1 ? [] : lines.slice(head + 1).map((l) => l.split(/\s+/)[0])
+}
+
+// OpenCode 설정 파일. 둘 다 없으면 OpenCode가 새로 만들 자리를 돌려준다.
+export function opencodeConfigFile({ root, scope, home = homedir(), env = process.env }) {
+  const dir = scope === 'project' ? root : join(env.XDG_CONFIG_HOME || join(home, '.config'), 'opencode')
+  for (const name of ['opencode.jsonc', 'opencode.json']) {
+    if (existsSync(join(dir, name))) return join(dir, name)
+  }
+  return join(dir, scope === 'project' ? 'opencode.jsonc' : 'opencode.json')
+}
+
+export function readOpencodeConfig(opts) {
+  const file = opencodeConfigFile(opts)
+  return { file, data: readJson(file) ?? null }
+}
+
+// Copilot CLI의 사용자 MCP 설정. VS Code의 Global > Copilot도 같은 파일에 쓴다
+// (code.visualstudio.com/docs/copilot/customization/mcp-servers) — 그래서 두 CLI의
+// 전역 MCP는 한 저장소를 나눠 쓴다.
+export function copilotMcpFile({ home = homedir(), env = process.env } = {}) {
+  return join(env.COPILOT_HOME || join(home, '.copilot'), 'mcp-config.json')
+}
+
+// VS Code 프로젝트 MCP. `.vscode/mcp.json`은 "호환용"으로 남았다는 표시가 붙었지만
+// 플래그 없이 읽히는 유일한 프로젝트 경로다(`.mcp.json`은 실험 플래그가 필요하다).
+export const VSCODE_MCP_FILE = '.vscode/mcp.json'
+
+function samePath(a, b, platform) {
+  if (!a) return false
+  const norm = (p) => (platform === 'win32' ? resolve(p).toLowerCase() : resolve(p))
+  return norm(a) === norm(b)
+}
+
+export function createProbe({ root, scope, exec, env = process.env, home = homedir(), platform = process.platform }) {
+  const memo = new Map()
+  // 실패도 캐시한다 — 같은 스캔에서 항목마다 죽은 CLI를 다시 부르지 않는다.
+  const once = (key, fn) => {
+    if (!memo.has(key)) memo.set(key, Promise.resolve().then(fn))
+    return memo.get(key)
+  }
+  const run = (cli, args) => once(`${cli} ${args.join(' ')}`, async () => {
+    const r = await exec(CLIS[cli]?.bin ?? cli, args, { cwd: root, timeout: PROBE_TIMEOUT_MS })
+    if (!r.ok) throw new Error(String(r.output ?? '').trim() || `${cli} ${args.join(' ')} failed`)
+    return r.output
+  })
+  const json = async (cli, args) => JSON.parse(await run(cli, args))
+  const opencode = () => readOpencodeConfig({ root, scope, home, env }).data
+
+  return {
+    root, scope, home,
+    has: (cli) => onPath(CLIS[cli].bin, { env, platform }),
+    async claudePlugin(ids) {
+      const list = await json('claude', ['plugin', 'list', '--json'])
+      return list.some((p) => ids.includes(p.id) && p.scope === scope
+        && (scope !== 'project' || samePath(p.projectPath, root, platform)))
+    },
+    async codexPlugin(id) {
+      const data = await json('codex', ['plugin', 'list', '--json'])
+      return (data.installed ?? []).some((p) => p.pluginId === id && p.installed !== false)
+    },
+    async agyPlugin(name) {
+      return (await json('antigravity', ['plugin', 'list', '--json'])).some((p) => p.name === name)
+    },
+    // id는 `이름@마켓`이거나 마켓 없이 직접 설치한 `이름`이다. 내장 플러그인은
+    // 설치가 아니다 — 같은 이름이 와도 세지 않는다.
+    async copilotPlugin(id) {
+      const [name, market = ''] = id.split('@')
+      return (await json('copilot', ['plugin', 'list', '--json']))
+        .some((p) => p.name === name && (p.marketplace ?? '') === market && p.source === 'installed')
+    },
+    async opencodePlugin(module) {
+      const list = opencode()?.plugin
+      return Array.isArray(list) && list.includes(module)
+    },
+    async mcp(cli, name) {
+      if (cli === 'claude') {
+        // `claude mcp list`는 서버마다 연결을 검사해 느리고 네트워크를 탄다.
+        const file = scope === 'project' ? join(root, '.mcp.json') : join(home, '.claude.json')
+        return readJson(file)?.mcpServers?.[name] !== undefined
+      }
+      if (cli === 'codex') return (await json('codex', ['mcp', 'list', '--json'])).some((s) => s.name === name)
+      if (cli === 'antigravity') return parseAgyMcpList(await run('antigravity', ['mcp', 'list'])).includes(name)
+      if (cli === 'opencode') return opencode()?.mcp?.[name] !== undefined
+      // Copilot CLI는 프로젝트 MCP를 쓰는 명령이 없다 — 사용자 설정만 본다.
+      if (cli === 'copilot') return scope === 'user' && readJson(copilotMcpFile({ home, env }))?.mcpServers?.[name] !== undefined
+      if (cli === 'vscode') {
+        return scope === 'project'
+          ? readJson(join(root, VSCODE_MCP_FILE))?.servers?.[name] !== undefined
+          : readJson(copilotMcpFile({ home, env }))?.mcpServers?.[name] !== undefined
+      }
+      return false
+    },
+    async skill(name) {
+      if (scope === 'project') return findSkillDir(root, name) !== null
+      const list = JSON.parse(await run('npx', ['-y', 'skills@latest', 'list', '-g', '--json']))
+      return list.some((s) => s.name === name)
+    },
+    exists: (rel) => existsSync(join(root, rel)),
+    dirHasPrefix(rel, prefix) {
+      try {
+        return readdirSync(join(root, rel)).some((f) => f.startsWith(prefix))
+      } catch {
+        return false
+      }
+    },
+  }
+}

package/lib/recipe-helpers.mjs

@@ -0,0 +1,281 @@
+// 항목 파일이 거의 다 쓰는 레시피 세 갈래. 명령 문법은 2026-10-24 이 머신의
+// --help 실측(claude 2.1.304, codex-cli 0.163.0, agy)과 opencode.ai/docs/cli를
+// 따른다.
+import { existsSync, rmSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { repoPathStrict } from './context.mjs'
+import { ensureGitignoreEntries } from './gitignore.mjs'
+import { LocalizedError } from './i18n/index.mjs'
+import { readJson, removeKey, setKey } from './jsonfile.mjs'
+import { VSCODE_MCP_FILE, copilotMcpFile, readOpencodeConfig } from './probe.mjs'
+import { SHARED } from './recipe.mjs'
+import { SHARED_SKILLS, findSkillDir, isSafeSkillName, lockedSkills, pruneLock, sourceKey } from './skills-registry.mjs'
+
+const SKILLS = ['npx', '-y', 'skills@latest']
+
+// 전역 설치 에이전트. skills@1.7.4 docs/agents.md의 전역 경로 기준:
+// claude-code → ~/.claude/skills, codex → ~/.agents/skills,
+// antigravity-cli → ~/.gemini/antigravity-cli/skills(agy가 읽는 전역 경로,
+// antigravity.google/docs/skills). OpenCode는 ~/.claude/skills와
+// ~/.agents/skills를 둘 다 읽으므로(opencode.ai/docs/skills) 따로 넣지 않는다 —
+// 넣으면 같은 스킬을 세 번 본다. Copilot CLI(`copilot skill --help`, 1.0.105)와
+// VS Code Copilot(code.visualstudio.com/docs/copilot/customization/agent-skills,
+// 2026-11-06)도 ~/.agents/skills를 읽으므로 codex가 깐 것을 그대로 본다.
+export const SKILLS_AGENTS = ['claude-code', 'codex', 'antigravity-cli']
+
+const OPENCODE_FILE = {
+  project: 'the project config ./opencode.jsonc (or ./opencode.json if only that one exists)',
+  user: 'the global config ~/.config/opencode/opencode.json (or opencode.jsonc there if only that one exists)',
+}
+
+// `opencode mcp add`는 대화형뿐이라 OpenCode 에이전트에게 편집을 맡긴다.
+// 지시문에는 큰따옴표를 남기지 않는다 — Windows에서 명령 한 줄은 cmd.exe를
+// 거치고, shellQuote는 그 안의 큰따옴표를 안전하게 이스케이프할 수 없어 거부한다.
+export function opencodePrompt(scope, task) {
+  return `Edit ${OPENCODE_FILE[scope]}. ${task} Keep comments and every other key unchanged. Do not run any other command. Reply only DONE.`
+    .replace(/"/g, "'")
+}
+
+// JSON을 작은따옴표로 적고 "파일에는 표준 JSON으로"라고 덧붙인다.
+const quotedJson = (value) => `${JSON.stringify(value)} (written with single quotes here; use standard JSON double quotes in the file)`
+
+// LLM 실행이라 결과가 비결정적이다 — 파일을 다시 읽는 이 단계가 유일한 성공 근거다.
+function verifyOpencode(scope, check, describe) {
+  return {
+    describe,
+    fn: ({ root }) => {
+      const { file, data } = readOpencodeConfig({ root, scope, home: homedir() })
+      if (!check(data)) throw new LocalizedError('error.opencodeVerify', { file })
+    },
+  }
+}
+
+const fileName = (scope) => (scope === 'project' ? './opencode.jsonc' : '~/.config/opencode/opencode.json')
+
+// `codex mcp add --url`은 OAuth를 쓰는 서버면 설정을 쓴 뒤 로그인 콜백을 기다리다
+// 약 5분 뒤 실패로 끝난다(2026-10-24 supabase 실측, codex-cli 0.163.0). 등록은 이미
+// 끝났으므로 짧게 끊고, 목록 명령으로 등록됐는지 확인한다. 로그인은 사용자가
+// `codex mcp login <이름>`으로 따로 한다(postInstall 안내).
+const CODEX_LOGIN_WAIT_MS = 20 * 1000
+
+function verifyCodexMcp(name) {
+  return {
+    describe: `check codex mcp list has ${name}`,
+    fn: async ({ root, exec }) => {
+      const r = await exec('codex', ['mcp', 'list', '--json'], { cwd: root })
+      let names = []
+      try { names = JSON.parse(r.output).map((s) => s.name) } catch { /* 목록을 못 읽으면 아래에서 실패로 보고한다 */ }
+      if (!r.ok || !names.includes(name)) throw new LocalizedError('error.codexMcpVerify', { name })
+    },
+  }
+}
+
+// VS Code Copilot에는 MCP 설치 명령이 없다. `code --add-mcp`는 JSON을 인자로 받는데
+// 그 큰따옴표를 Windows 인용(shellQuote)이 거부하고, 제거·목록 명령도 없다.
+// 그래서 파일을 고친다 — jsonfile.mjs는 사용자 주석과 들여쓰기를 지킨다.
+//   프로젝트: .vscode/mcp.json의 servers (플래그 없이 읽히는 유일한 프로젝트 경로)
+//   전역: ~/.copilot/mcp-config.json의 mcpServers — VS Code의 Global > Copilot이
+//         쓰는 파일이고 `copilot mcp add`도 같은 파일에 쓴다.
+function vscodeMcp(name, server) {
+  const http = server.kind === 'http'
+  const project = http ? { type: 'http', url: server.url } : { type: 'stdio', command: server.command, args: server.args }
+  // `copilot mcp add`가 쓰는 모양 그대로(2026-11-06 실측) — 어느 쪽이 먼저 써도 같은 파일이다.
+  const user = http ? { tools: ['*'], type: 'http', url: server.url } : { tools: ['*'], type: 'local', command: server.command, args: server.args }
+  return {
+    project: {
+      install: [{
+        describe: `add servers.${name} to ${VSCODE_MCP_FILE}`,
+        fn: ({ root }) => {
+          setKey(repoPathStrict(root, VSCODE_MCP_FILE), ['servers', name], project)
+          // `.vscode/*`를 무시하는 저장소(VisualStudio.gitignore)에서는 이 부정 항목이 없으면
+          // mcp.json이 조용히 커밋에서 빠진다. 무시 파일이 없으면 지킬 것이 없다.
+          if (existsSync(repoPathStrict(root, '.gitignore'))) ensureGitignoreEntries(root, [`!${VSCODE_MCP_FILE}`])
+        },
+      }],
+      uninstall: [{
+        describe: `remove servers.${name} from ${VSCODE_MCP_FILE}`,
+        fn: ({ root }) => removeKey(repoPathStrict(root, VSCODE_MCP_FILE), ['servers', name]),
+      }],
+    },
+    user: {
+      install: [{
+        describe: `add mcpServers.${name} to ~/.copilot/mcp-config.json (shared with Copilot CLI)`,
+        fn: () => {
+          const file = copilotMcpFile({ home: homedir() })
+          // Copilot CLI 단계가 같은 실행에서 먼저 썼을 수 있다 — 있으면 덮지 않는다.
+          if (readJson(file)?.mcpServers?.[name] !== undefined) return
+          setKey(file, ['mcpServers', name], user)
+        },
+      }],
+      uninstall: [{
+        describe: `remove mcpServers.${name} from ~/.copilot/mcp-config.json`,
+        fn: () => removeKey(copilotMcpFile({ home: homedir() }), ['mcpServers', name]),
+      }],
+    },
+  }
+}
+
+// copilot: `{ marketplace?, id, source? }`. marketplace가 있으면 먼저 등록하고(이미 있으면
+// 참는다), source가 있으면 그것을 설치 인자로 쓴다(마켓 없이 `owner/repo:경로`로 직접
+// 설치). id는 설치 인자이자 제거·감지에 쓰는 `이름@마켓`/`이름`이다.
+export function marketplacePlugin({ claude, codex, opencode, antigravity, copilot }) {
+  const recipes = {}
+  const detect = {}
+  if (claude) {
+    const at = (scope) => ({
+      install: [
+        ...(claude.marketplace ? [{ argv: ['claude', 'plugin', 'marketplace', 'add', claude.marketplace, '--scope', scope], tolerateFail: true }] : []),
+        ['claude', 'plugin', 'install', claude.id, '--scope', scope],
+      ],
+      uninstall: [['claude', 'plugin', 'uninstall', claude.id, '--scope', scope]],
+    })
+    recipes.claude = { project: at('project'), user: at('user') }
+    detect.claude = (p) => p.claudePlugin(claude.detectIds ?? [claude.id])
+  }
+  if (codex) {
+    // Codex는 범위 플래그가 없다 — 활성 CODEX_HOME 하나에 깔린다(전역).
+    recipes.codex = {
+      user: {
+        install: [{ argv: ['codex', 'plugin', 'marketplace', 'add', codex.marketplace], tolerateFail: true }, ['codex', 'plugin', 'add', codex.id]],
+        uninstall: [['codex', 'plugin', 'remove', codex.id]],
+      },
+    }
+    detect.codex = (p) => p.codexPlugin(codex.id)
+  }
+  if (opencode) {
+    // 설치 명령은 있지만 제거 명령은 문서에 없다 — 제거는 run 지시문 + 검증이다.
+    const at = (scope) => ({
+      install: [['opencode', 'plugin', opencode.module, ...(scope === 'user' ? ['-g'] : [])]],
+      uninstall: [
+        ['opencode', 'run', opencodePrompt(scope, `Remove the string '${opencode.module}' from the top-level 'plugin' array; delete the array if it becomes empty.`)],
+        verifyOpencode(scope, (d) => !(Array.isArray(d?.plugin) && d.plugin.includes(opencode.module)), `check ${fileName(scope)} no longer lists plugin ${opencode.module}`),
+      ],
+    })
+    recipes.opencode = { project: at('project'), user: at('user') }
+    detect.opencode = (p) => p.opencodePlugin(opencode.module)
+  }
+  if (antigravity) {
+    // agy plugin install에도 범위 플래그가 없다 — ~/.gemini 아래 전역에 깔린다.
+    recipes.antigravity = {
+      user: {
+        install: [['agy', 'plugin', 'install', antigravity.source]],
+        uninstall: [['agy', 'plugin', 'uninstall', antigravity.name]],
+      },
+    }
+    detect.antigravity = (p) => p.agyPlugin(antigravity.name)
+  }
+  if (copilot) {
+    // `copilot plugin install`에도 범위 플래그가 없다 — ~/.copilot 아래 전역에 깔린다.
+    // 다른 copilot 세션이 떠 있으면 install·uninstall이 "os error 5"로 실패할 수 있다
+    // (2026-08-15 실측) — 세션을 닫고 다시 하면 된다.
+    recipes.copilot = {
+      user: {
+        install: [
+          ...(copilot.marketplace ? [{ argv: ['copilot', 'plugin', 'marketplace', 'add', copilot.marketplace], tolerateFail: true }] : []),
+          ['copilot', 'plugin', 'install', copilot.source ?? copilot.id],
+        ],
+        uninstall: [['copilot', 'plugin', 'uninstall', copilot.id]],
+      },
+    }
+    detect.copilot = (p) => p.copilotPlugin(copilot.id)
+  }
+  return { recipes, detect }
+}
+
+export function mcpServer({ name, server, clis = ['claude', 'codex', 'opencode', 'antigravity', 'copilot', 'vscode'] }) {
+  const http = server.kind === 'http'
+  // stdio 명령 앞의 `--`: 인자가 `-y`처럼 대시로 시작해도 CLI가 자기 플래그로 읽지 않는다.
+  const tail = http ? [] : ['--', server.command, ...server.args]
+  const entry = http
+    ? { type: 'remote', url: server.url, enabled: true }
+    : { type: 'local', command: [server.command, ...server.args], enabled: true }
+  const opencodeAt = (scope) => ({
+    install: [
+      ['opencode', 'run', opencodePrompt(scope, `Under the top-level 'mcp' object (create it, and the file with '$schema': 'https://opencode.ai/config.json', if missing) set the key '${name}' to this value: ${quotedJson(entry)}.`)],
+      verifyOpencode(scope, (d) => d?.mcp?.[name] !== undefined, `check ${fileName(scope)} has mcp.${name}`),
+    ],
+    uninstall: [
+      ['opencode', 'run', opencodePrompt(scope, `Delete the key '${name}' from the top-level 'mcp' object.`)],
+      verifyOpencode(scope, (d) => d?.mcp?.[name] === undefined, `check ${fileName(scope)} no longer has mcp.${name}`),
+    ],
+  })
+  const claudeAt = (scope) => ({
+    install: [http ? ['claude', 'mcp', 'add', '-s', scope, '-t', 'http', name, server.url] : ['claude', 'mcp', 'add', '-s', scope, name, ...tail]],
+    uninstall: [['claude', 'mcp', 'remove', '-s', scope, name]],
+  })
+  const all = {
+    claude: { project: claudeAt('project'), user: claudeAt('user') },
+    // Codex·Antigravity의 mcp add에는 범위 플래그가 없다 — 사용자 전역 설정에 쓴다.
+    codex: {
+      user: {
+        install: http
+          ? [{ argv: ['codex', 'mcp', 'add', name, '--url', server.url], tolerateFail: true, timeout: CODEX_LOGIN_WAIT_MS }, verifyCodexMcp(name)]
+          : [['codex', 'mcp', 'add', name, ...tail]],
+        uninstall: [['codex', 'mcp', 'remove', name]],
+      },
+    },
+    opencode: { project: opencodeAt('project'), user: opencodeAt('user') },
+    antigravity: { user: { install: [http ? ['agy', 'mcp', 'add', name, server.url] : ['agy', 'mcp', 'add', name, ...tail]], uninstall: [['agy', 'mcp', 'remove', name]] } },
+    // `copilot mcp add`는 사용자 설정(~/.copilot/mcp-config.json)에만 쓴다(2026-11-06 실측).
+    // 프로젝트 `.mcp.json`·`.github/mcp.json`은 읽기만 하고 쓰는 명령이 없다.
+    copilot: {
+      user: {
+        install: [http ? ['copilot', 'mcp', 'add', '--transport', 'http', name, server.url] : ['copilot', 'mcp', 'add', name, ...tail]],
+        uninstall: [['copilot', 'mcp', 'remove', name]],
+      },
+    },
+    vscode: vscodeMcp(name, server),
+  }
+  const recipes = Object.fromEntries(clis.map((c) => [c, all[c]]))
+  const detect = Object.fromEntries(clis.map((c) => [c, (p) => p.mcp(c, name)]))
+  return { recipes, detect }
+}
+
+// 레지스트리의 remove는 --agent universal에서 "Done!"을 찍고도 디렉터리와
+// 잠금 항목을 남긴다(실측) — 남은 것을 우리가 치운다. 남겨 두면 detect가
+// 계속 설치됨으로 읽고, 동료가 잠금 파일로 복원하면 지운 스킬이 되살아난다.
+// 잠금 항목은 lockNames 전부를 지운다 — 인자·경로로 못 써 건너뛴 이름까지.
+// 남기면 다음 제거가 같은 자리에서 또 멈춘다.
+function cleanup(root, names, lockNames = names) {
+  for (const name of names) {
+    const dir = findSkillDir(root, name)
+    if (dir) rmSync(repoPathStrict(root, `${SHARED_SKILLS}/${dir}`), { recursive: true, force: true })
+  }
+  pruneLock(root, lockNames)
+}
+
+export function skillsAdd({ source, skill, anchor = null }) {
+  const wildcard = skill === '*'
+  // 스킬 전부(*)를 넣으면 detect가 볼 이름을 정해 둬야 한다 — 없으면 설치해도
+  // 계속 absent로 읽히는 항목이 조용히 카탈로그에 들어간다.
+  if (wildcard && !anchor) throw new LocalizedError('error.registrySkillAnchor', { id: sourceKey(source) })
+  const probeName = anchor ?? skill
+  const project = {
+    install: [[...SKILLS, 'add', source, '--skill', skill, '--agent', 'universal', '--yes', '--copy']],
+    uninstall: wildcard
+      ? [{
+          describe: `npx -y skills@latest remove <each skill from ${sourceKey(source)} in skills-lock.json> --agent universal --yes, then remove leftover ${SHARED_SKILLS} dirs`,
+          fn: async ({ root, exec }) => {
+            // 잠금 파일의 이름은 상류 frontmatter에서 온다 — 인자·경로로 못 쓰는 이름은 건너뛴다.
+            const locked = lockedSkills(root, source)
+            const all = locked.length > 0 ? locked : [probeName]
+            const names = all.filter(isSafeSkillName)
+            for (const name of names) await exec('npx', ['-y', 'skills@latest', 'remove', name, '--agent', 'universal', '--yes'], { cwd: root })
+            cleanup(root, names, all)
+          },
+        }]
+      : [
+          { argv: [...SKILLS, 'remove', skill, '--agent', 'universal', '--yes'], tolerateFail: true },
+          { describe: `remove leftover ${SHARED_SKILLS}/${skill} and its skills-lock.json entry`, fn: ({ root }) => cleanup(root, [skill]) },
+        ],
+  }
+  const byScope = { project }
+  // 한 상류의 스킬 전부(*)는 전역에서 무엇을 지울지 추적할 근거가 없다.
+  if (!wildcard) {
+    byScope.user = {
+      install: [[...SKILLS, 'add', source, '--skill', skill, '-g', '-a', ...SKILLS_AGENTS, '--yes', '--copy']],
+      uninstall: [[...SKILLS, 'remove', skill, '-g', '-a', ...SKILLS_AGENTS, '--yes']],
+    }
+  }
+  return { recipes: { [SHARED]: byScope }, detect: { [SHARED]: (p) => p.skill(probeName) } }
+}

package/lib/recipe.mjs

@@ -0,0 +1,181 @@
+// 레시피 = CLI·범위별 설치 명령 목록. 항목 파일은 데이터만 적고, 이 모듈이
+// 그것을 엔진·TUI가 아는 항목 모양으로 바꾼다. 실행(install)과 출력(--print)이
+// 같은 steps()에서 명령을 얻으므로 둘이 어긋날 수 없다.
+import { join } from 'node:path'
+import { CLIS, CLI_IDS as RECIPE_CLIS } from './clis.mjs'
+import { LocalizedError, msg } from './i18n/index.mjs'
+
+export const SCOPES = ['project', 'user']
+// 한 단계 묶음이 네 CLI를 한꺼번에 덮는 자리(.agents/skills).
+export const SHARED = 'shared'
+// 실패 보고에 싣는 출력 줄 수. 설치 로그 전체는 화면을 덮는다.
+const TAIL_LINES = 5
+
+export function normalizeStep(step, cli) {
+  if (Array.isArray(step)) return { cli, argv: step, cwd: null, tolerateFail: false, undo: null, timeout: null }
+  if (step && Array.isArray(step.argv)) {
+    return { cli, argv: step.argv, cwd: step.cwd ?? null, tolerateFail: Boolean(step.tolerateFail), undo: step.undo ?? null, timeout: step.timeout ?? null }
+  }
+  if (step && typeof step.fn === 'function' && step.describe) return { cli, fn: step.fn, describe: String(step.describe) }
+  return null
+}
+
+function assertRecipe(def) {
+  const bad = (why) => { throw new LocalizedError('error.recipeInvalid', { id: def?.id ?? '?', why }) }
+  for (const field of ['id', 'category', 'label']) if (!def?.[field]) bad(`missing ${field}`)
+  const entries = Object.entries(def.recipes ?? {})
+  if (entries.length === 0) bad('no recipes')
+  if (def.recipes[SHARED] && entries.length > 1) bad('shared cannot be combined with per-CLI recipes')
+  for (const [cli, byScope] of entries) {
+    if (cli !== SHARED && !RECIPE_CLIS.includes(cli)) bad(`unknown CLI ${cli}`)
+    for (const [scope, recipe] of Object.entries(byScope)) {
+      if (!SCOPES.includes(scope)) bad(`unknown scope ${scope}`)
+      for (const action of ['install', 'uninstall']) {
+        if (!Array.isArray(recipe?.[action])) bad(`${cli}.${scope}.${action} is not a list`)
+        for (const raw of recipe[action]) {
+          const step = normalizeStep(raw, cli)
+          if (!step || (step.argv && (step.argv.length === 0 || !step.argv.every((a) => typeof a === 'string')))) {
+            bad(`${cli}.${scope}.${action} has a bad step`)
+          }
+        }
+      }
+    }
+    if (typeof def.detect?.[cli] !== 'function') bad(`detect.${cli} missing`)
+  }
+}
+
+export function defineRecipe(def) {
+  assertRecipe(def)
+  return { ...def, kind: 'recipe' }
+}
+
+const reasonOf = (r) => (typeof r === 'string' ? msg(r) : r)
+
+export function bindScope(def, scope) {
+  const shared = def.recipes[SHARED]
+  if (shared && !shared[scope]) return null
+  const supports = shared ? [...RECIPE_CLIS] : RECIPE_CLIS.filter((c) => def.recipes[c]?.[scope])
+  if (supports.length === 0) return null
+
+  // 다른 범위엔 레시피가 있으면 "범위를 바꾸면 된다"가 사유다. 어느 범위에도
+  // 없을 때만 항목이 사유를 직접 대야 한다 — 빠뜨리면 로드 오류로 막는다.
+  const other = scope === 'project' ? 'user' : 'project'
+  const unsupported = {}
+  for (const cli of RECIPE_CLIS) {
+    if (supports.includes(cli)) continue
+    if (def.recipes[cli]?.[other]) unsupported[cli] = msg(`item.unsupported.${other}Only`)
+    else if (def.reasons?.[cli]) unsupported[cli] = reasonOf(def.reasons[cli])
+    else throw new LocalizedError('error.itemReasonMissing', { id: def.id, cli })
+  }
+
+  const recipeOf = (cli) => def.recipes[cli][scope]
+
+  return {
+    id: def.id, category: def.category, label: def.label,
+    group: def.group ?? null, exclusive: def.exclusive ?? null, note: def.note ?? null,
+    verified: def.verified ?? null, hooks: Boolean(def.hooks), postInstall: def.postInstall ?? null,
+    scope, supports, unsupported,
+
+    async detect({ probe }) {
+      const reach = supports.filter((c) => probe.has(c))
+      // 공유 스킬은 CLI가 아니라 디렉터리에 깔린다 — PATH와 무관하다.
+      const excluded = shared ? [] : supports.filter((c) => !reach.includes(c))
+      const targets = shared ? [SHARED] : reach
+      const present = []
+      const failed = []
+      for (const cli of targets) {
+        try {
+          if (await def.detect[cli](probe)) present.push(cli)
+        } catch {
+          // 목록 명령 실패(로그인 만료 등)를 "없음"으로 읽으면 깔린 것을 또 깐다.
+          failed.push(cli)
+        }
+      }
+      const live = targets.filter((c) => !failed.includes(c))
+      const status = present.length === 0 ? 'absent' : present.length === live.length ? 'installed' : 'partial'
+      let detail = null
+      if (failed.length > 0) detail = msg('item.probeFailed', { list: failed.join(', ') })
+      else if (status === 'partial') {
+        detail = msg('item.plugin.partial', { present: present.join(', '), missing: live.filter((c) => !present.includes(c)).join(', ') })
+      } else if (targets.length === 0) detail = msg('item.global.noCli', { list: excluded.join(', ') })
+      return { status, detail, excluded, present, failed, targets, reach }
+    },
+
+    steps(action, state = {}) {
+      const present = state.present ?? []
+      const failed = state.failed ?? []
+      const targets = state.targets ?? (shared ? [SHARED] : supports)
+      const removing = action === 'uninstall'
+      const clis = removing
+        ? targets.filter((c) => present.includes(c))
+        : targets.filter((c) => !present.includes(c) && !failed.includes(c))
+      return clis.flatMap((cli) => recipeOf(cli)[removing ? 'uninstall' : 'install'].map((s) => normalizeStep(s, cli)))
+    },
+
+    async install(ctx) {
+      const state = ctx.state ?? {}
+      const steps = this.steps('install', state)
+      // 실행할 명령이 없는데 ✔로 끝나면 --set을 쓰는 CI가 무동작을 성공으로 받는다.
+      // 감지 실패는 실패로, CLI가 이 머신에 없는 것은 사연 있는 성공으로 돌려준다.
+      if (steps.length === 0) {
+        const failed = state.failed ?? []
+        const excluded = state.excluded ?? []
+        if (failed.length > 0) throw new LocalizedError('item.probeFailed', { list: failed.join(', ') })
+        if (excluded.length > 0) return { message: msg('item.global.noCli', { list: excluded.join(', ') }) }
+        return undefined
+      }
+      await runSteps(steps, ctx)
+      return undefined
+    },
+
+    async uninstall(ctx) {
+      await runSteps(this.steps('uninstall', ctx.state), ctx)
+    },
+  }
+}
+
+function tail(output) {
+  return String(output ?? '').trim().split(/\r?\n/).slice(-TAIL_LINES).join('\n    ')
+}
+
+const cliLabel = (cli) => CLIS[cli]?.label ?? cli
+
+// 한 CLI의 단계가 실패하면 그 CLI의 남은 단계만 건너뛴다. 다른 CLI는 계속
+// 간다 — 로그인이 풀린 Codex 하나 때문에 Claude 설치까지 막을 이유가 없다.
+export async function runSteps(steps, ctx) {
+  const { root, exec, dryRun = false, log = () => {} } = ctx
+  const broken = new Set()
+  // 참아 준 실패(마켓플레이스 "이미 등록됨")는 뒤 단계가 실패할 때만 함께 보인다.
+  const soft = new Map()
+  const failures = []
+  for (const step of steps) {
+    if (broken.has(step.cli)) continue
+    if (step.fn) {
+      if (dryRun) { log(`  [dry-run] ${step.describe}`); continue }
+      try {
+        await step.fn(ctx)
+      } catch (err) {
+        failures.push({ cli: step.cli, what: step.describe, output: err.message })
+        broken.add(step.cli)
+      }
+      continue
+    }
+    const [cmd, ...args] = step.argv
+    const opts = { cwd: step.cwd ? join(root, step.cwd) : root }
+    if (step.timeout) opts.timeout = step.timeout
+    const r = await exec(cmd, args, opts)
+    if (r.ok) continue
+    const failure = { cli: step.cli, what: step.argv.join(' '), output: tail(r.output) }
+    if (step.tolerateFail) { soft.set(step.cli, failure); continue }
+    if (step.undo && !dryRun) {
+      try { await step.undo(ctx) } catch { /* 되돌리기 실패가 원래 실패를 가리면 안 된다 */ }
+    }
+    if (soft.has(step.cli)) failures.push(soft.get(step.cli))
+    failures.push(failure)
+    broken.add(step.cli)
+  }
+  if (failures.length > 0) {
+    const details = failures.map((f) => `  ${cliLabel(f.cli)}: ${f.what}${f.output ? `\n    ${f.output}` : ''}`).join('\n')
+    throw new LocalizedError('error.stepsFailed', { details })
+  }
+}