@rch4com/agent-setup 1.28.0 → 2.0.0

package/lib/catalog.mjs

@@ -1,24 +1,28 @@
-import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { readdirSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
-import { CLIS, CLI_IDS, MCP_CLI_IDS } from './clis.mjs'
-import { isPluginEnabled, enablePlugin, disablePlugin } from './claude-plugins.mjs'
-import { repoPath, repoPathStrict } from './context.mjs'
-import { LocalizedError, msg } from './i18n/index.mjs'
-// design-md가 아니라 잎 모듈에서 가져온다 — deps.test.mjs의 "의존성 없는
-// 트리"는 design-md를 통째로 빼고 --list를 돌린다(bootstrap.isolation.test.mjs).
-import { escapeRegExp, isSafeSegment } from './untrusted.mjs'
+import { LocalizedError } from './i18n/index.mjs'
+import { bindScope } from './recipe.mjs'
 
 const ITEMS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'items')
 
-export async function loadItems() {
+// 레시피 항목은 범위마다 다른 모양으로 묶인다. 그 범위에 레시피가 없는
+// 항목(예: gstack의 전역)은 목록에서 빠진다. 파일을 직접 쓰는 함수형 항목은
+// 자기 scope와 같은 범위에서만 나온다.
+export async function loadItems({ scope = 'project' } = {}) {
   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))
+    if (mod.default?.kind === 'recipe') {
+      const item = bindScope(mod.default, scope)
+      if (item) items.push(item)
+      continue
+    }
+    const item = validate(mod.default, f)
+    if ((item.scope ?? 'project') === scope) items.push(item)
   }
   return items
 }
@@ -30,14 +34,6 @@ function validate(item, file) {
   return item
 }
 
-function assertReasons(id, supports, unsupported) {
-  for (const cli of CLI_IDS) {
-    if (!supports.includes(cli) && !unsupported[cli]) {
-      throw new LocalizedError('error.itemReasonMissing', { id, cli })
-    }
-  }
-}
-
 // shell 모드에서 Node는 명령과 인자를 공백으로 이어붙일 뿐 quote하지 않으므로
 // 직접 감싼다. 공백이 있을 때만 감싸면 셸 메타문자가 그대로 노출된다 —
 // `D:\R&D\repo` 아래에서 gstack clone 대상이 명령 두 개로 쪼개졌다.
@@ -124,225 +120,3 @@ export function makeExec(dryRun, log = console.log, t = null) {
     }
   }
 }
-
-// supports 기본값은 프로젝트 MCP 파일이 있는 CLI(MCP_CLI_IDS)다. Antigravity는
-// 그 파일이 없어 빠지고, 사유가 기본으로 붙는다.
-//
-// stdio 서버도 copilot에 그대로 배선한다. Copilot CLI는 루트 .mcp.json(Claude
-// 파일)을 우선 읽고 거기엔 `type: "stdio"`가 쓰이는데, 한때 README는 그 형식이
-// 붙지 않는다고 적었다. 2026-09-05에 Copilot CLI 1.0.82의 app.js를 읽어 확인한
-// 바로는 로컬 서버 판정이 `type === undefined || type === "local" || type ===
-// "stdio"`이고 스키마도 `enum(["local", "stdio"])`라 stdio를 받는다 — 두 파일에
-// 각자 형식으로 써도 어느 쪽이 이기든 붙는다.
-export function defineMcp({ id, label, server, supports = [...MCP_CLI_IDS], unsupported: reasons = {}, note, group = null, verified = null }) {
-  const unsupported = { ...reasons }
-  for (const cli of CLI_IDS) {
-    if (!supports.includes(cli) && !unsupported[cli] && !MCP_CLI_IDS.includes(cli)) unsupported[cli] = msg('item.unsupported.noProjectMcp')
-  }
-  assertReasons(id, supports, unsupported)
-  const name = id.replace(/^mcp\./, '')
-  return {
-    id, category: 'mcp', label, scope: 'project', supports, unsupported, note, group, verified,
-    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: msg('item.mcp.partial', {
-          present: present.join(', '),
-          missing: supports.filter((c) => !present.includes(c)).join(', '),
-        }),
-      }
-    },
-    async install({ root, dryRun, log = () => {}, t }) {
-      for (const cli of supports) {
-        if (!CLIS[cli].has(root, name)) {
-          if (dryRun) log(t('log.mcp.add', { cli: CLIS[cli].label, name }))
-          else CLIS[cli].add(root, name, server)
-        }
-      }
-    },
-    async uninstall({ root, dryRun, log = () => {}, t }) {
-      for (const cli of supports) {
-        if (CLIS[cli].has(root, name)) {
-          if (dryRun) log(t('log.mcp.remove', { cli: CLIS[cli].label, name }))
-          else CLIS[cli].remove(root, name)
-        }
-      }
-    },
-  }
-}
-
-// 배선은 Claude 한 곳이라도 미배선 "사유"는 CLI마다 다를 수 있다 — 상류가
-// 자체 경로로 지원하는 CLI에 일괄 "Claude 전용" 사유를 붙이면 거짓 정보가 된다.
-// 항목이 사유를 넘기면 그 CLI만 덮고, 나머지는 기본 사유로 채운다.
-export function definePlugin({ id, label, installId, detectIds, marketplace, note, group = null, exclusive = null, unsupported: reasons = {}, verified = null }) {
-  const unsupported = Object.fromEntries(
-    CLI_IDS.filter((c) => c !== 'claude').map((c) => [c, reasons[c] ?? msg('item.unsupported.claudePlugin')]),
-  )
-  return {
-    id, category: 'plugin', label, scope: 'project', supports: ['claude'], unsupported, note, group, exclusive, verified,
-    async detect({ root }) {
-      return { status: isPluginEnabled(root, detectIds) ? 'installed' : 'absent' }
-    },
-    async install(ctx) {
-      const { root, dryRun, exec } = ctx
-      if (marketplace) await exec('claude', ['plugin', 'marketplace', 'add', marketplace.repo], { cwd: root })
-      const r = await exec('claude', ['plugin', 'install', installId, '--scope', 'project'], { cwd: root })
-      if (!r.ok) {
-        if (!dryRun) enablePlugin(root, installId, marketplace)
-        return { fallback: true, message: msg('item.plugin.deferred') }
-      }
-    },
-    async uninstall(ctx) {
-      const { root, dryRun, exec } = ctx
-      const r = await exec('claude', ['plugin', 'uninstall', installId], { cwd: root })
-      if (!r.ok && !dryRun) disablePlugin(root, detectIds)
-    },
-  }
-}
-
-// supports는 이 항목이 실제로 배선하는 CLI다. 기본값이 claude 하나인 것은
-// 대부분의 스킬 상류가 Claude 경로만 주기 때문이고, 상류가 런타임별 설치를
-// 주는 항목(skill.gsd)은 목록을 직접 넘긴다 — 넘긴 CLI는 미배선 사유 대상에서
-// 빠진다.
-export function defineSkill({ id, label, scope, detect, install, uninstall, note, group = null, supports = ['claude'], unsupported: reasons = {}, verified = null }) {
-  const unsupported = Object.fromEntries(
-    CLI_IDS.filter((c) => !supports.includes(c)).map((c) => [c, reasons[c] ?? msg('item.unsupported.claudeSkill')]),
-  )
-  return { id, category: 'skill', label, scope, supports: [...supports], unsupported, note, group, verified, detect, install, uninstall }
-}
-
-// 이 저장소가 공유 스킬 자리로 쓰는 디렉터리. vercel-labs/skills 레지스트리의
-// `--agent universal` 프로젝트 경로와 같은 값이다 — 그래서 레지스트리 설치가
-// 우리 배선 위에 그대로 얹힌다.
-const SHARED_SKILLS = '.agents/skills'
-
-function skillDirs(root) {
-  const dir = repoPath(root, SHARED_SKILLS)
-  if (!existsSync(dir)) return []
-  return readdirSync(dir).filter((name) => {
-    try {
-      return statSync(join(dir, name)).isDirectory()
-    } catch {
-      return false
-    }
-  })
-}
-
-// 설치된 디렉터리 이름이 스킬 이름과 다를 수 있다(레지스트리는 SKILL.md의
-// frontmatter name으로 고르는데, 저장소의 폴더 이름은 다른 경우가 있다 —
-// taste-skill/이 design-taste-frontend를 담는 식이다). 이름이 같은 디렉터리를
-// 먼저 보고, 없으면 frontmatter를 읽어 찾는다. 디렉터리 이름만 보면 설치해
-// 놓고도 계속 '미설치'로 읽힌다.
-function findSkillDir(root, skill) {
-  const base = repoPath(root, SHARED_SKILLS)
-  if (existsSync(join(base, skill, 'SKILL.md'))) return skill
-  for (const name of skillDirs(root)) {
-    const file = join(base, name, 'SKILL.md')
-    if (!existsSync(file)) continue
-    const head = readFileSync(file, 'utf8').slice(0, 2000)
-    if (new RegExp(`^name:\\s*['"]?${escapeRegExp(skill)}['"]?\\s*$`, 'm').test(head)) return name
-  }
-  return null
-}
-
-// 잠금 파일의 이름은 상류 SKILL.md frontmatter에서 온다 — 신뢰 경계 밖이다.
-// `npx skills remove <이름>`의 인자이자 `.agents/skills/<이름>` 경로가 되므로,
-// 플래그로 읽히는 선행 대시와 경로 구분자·상위 이동은 어느 쪽으로도 쓸 수 없다.
-function isSafeSkillName(name) {
-  return isSafeSegment(name) && !name.startsWith('-')
-}
-
-// 레지스트리가 저장소 루트에 남기는 잠금 파일. 스킬 이름마다 어느 출처에서
-// 왔는지를 적어 두므로, 한 상류가 여러 스킬을 깔았을 때 "우리가 넣은 것"만
-// 골라 지울 수 있는 유일한 근거다.
-const SKILLS_LOCK = 'skills-lock.json'
-
-// 잠금 파일의 source는 `owner/repo`로 정규화돼 있고 항목은 URL을 넘긴다.
-function sourceKey(source) {
-  return String(source).replace(/^https?:\/\/github\.com\//, '').replace(/\.git$/, '').replace(/\/+$/, '')
-}
-
-function readLock(root) {
-  const file = repoPath(root, SKILLS_LOCK)
-  if (!existsSync(file)) return null
-  try {
-    return JSON.parse(readFileSync(file, 'utf8'))
-  } catch {
-    // 잠금 파일이 깨졌다고 제거를 막지는 않는다 — 디렉터리 스캔 폴백이 있다.
-    return null
-  }
-}
-
-function lockedSkills(root, source) {
-  const want = sourceKey(source)
-  return Object.entries(readLock(root)?.skills ?? {})
-    .filter(([, v]) => sourceKey(v?.source ?? '') === want)
-    .map(([name]) => name)
-}
-
-// 레지스트리의 remove는 디렉터리도, 잠금 파일의 항목도 남긴다(실측). 디렉터리는
-// 아래에서 우리가 지우는데 잠금 항목을 그대로 두면 파일이 "설치돼 있다"고
-// 거짓말한다 — 커밋해서 팀과 나누는 파일이라, 동료가 experimental_install로
-// 복원하면 지운 스킬이 되살아난다.
-function pruneLock(root, names) {
-  const parsed = readLock(root)
-  const skills = parsed?.skills
-  if (!skills) return
-  const gone = names.filter((n) => Object.hasOwn(skills, n))
-  if (gone.length === 0) return
-  for (const n of gone) delete skills[n]
-  const file = repoPathStrict(root, SKILLS_LOCK)
-  // 남은 스킬이 없으면 파일째 지운다. 이 파일은 레지스트리가 만든 산출물이라
-  // 빈 껍데기를 남기면 우리가 만든 흔적이 저장소에 계속 남는다.
-  if (Object.keys(skills).length === 0) rmSync(file, { force: true })
-  else writeFileSync(file, `${JSON.stringify(parsed, null, 2)}\n`)
-}
-
-// vercel-labs/skills 레지스트리로 설치하는 스킬. `--agent universal`의 프로젝트
-// 경로가 .agents/skills라, 한 번 설치하면 10개 CLI가 함께 본다 — Claude·Kiro·
-// Grok은 부트스트랩이 만든 Junction으로, 나머지는 그 경로를 네이티브로 읽는다
-// (도구별 실측 근거는 bootstrap/manifest.mjs의 adapters 주석에 있다).
-// `--copy`로 실물을 남긴다: 커밋해서 팀과 나누는 자리라 링크는 클론 뒤 깨진다.
-//
-// skill에 `*`를 주면 그 상류의 스킬을 전부 넣는다. 그때 detect가 볼 대표
-// 스킬을 anchor로 지정해야 한다 — 디렉터리가 여럿이라 "무엇이 있으면 설치된
-// 것인가"를 이름 하나로 정해 두지 않으면 판정이 흔들린다.
-//
-// exclusive는 같은 상류를 플러그인으로도 넣을 수 있을 때 쓴다. 두 경로가 겹치면
-// 같은 스킬이 두 번 등록되므로 하나만 고르게 막는다.
-export function defineRegistrySkill({ id, label, source, skill, anchor = null, note, group = null, exclusive = null, verified = null }) {
-  const probe = anchor ?? skill
-  if (skill === '*' && !anchor) throw new LocalizedError('error.registrySkillAnchor', { id })
-  return {
-    id, category: 'skill', label, scope: 'project', supports: [...CLI_IDS], unsupported: {}, note, group, exclusive, verified,
-    async detect({ root }) {
-      return { status: findSkillDir(root, probe) ? 'installed' : 'absent' }
-    },
-    async install({ root, exec }) {
-      const r = await exec('npx', ['-y', 'skills@latest', 'add', source, '--skill', skill, '--agent', 'universal', '--yes', '--copy'], { cwd: root })
-      if (!r.ok) throw new LocalizedError('error.registrySkillInstall', { skill, output: r.output })
-    },
-    async uninstall({ root, dryRun, exec }) {
-      // 지울 이름을 먼저 정한다. 여러 스킬을 깐 항목은 잠금 파일이 알려 주고,
-      // 잠금 파일이 없거나 깨졌으면 대표 스킬 하나라도 치운다.
-      const names = skill === '*' ? lockedSkills(root, source) : [skill]
-      const targets = names.length > 0 ? names : [probe]
-      for (const name of targets) {
-        // 인자·경로로 쓸 수 없는 이름은 건너뛴다. 잠금 항목은 아래 pruneLock이
-        // 함께 지운다 — 남기면 다음 제거가 같은 자리에서 또 멈춘다.
-        if (!isSafeSkillName(name)) continue
-        // 레지스트리의 remove는 --agent universal에서 "Done!"을 찍고도 디렉터리를
-        // 남긴다(실측). 그래서 성공/실패와 무관하게 남은 디렉터리를 우리가 지운다 —
-        // 남겨 두면 detect가 계속 installed로 읽어 제거가 안 된 채 성공으로 보인다.
-        await exec('npx', ['-y', 'skills@latest', 'remove', name, '--agent', 'universal', '--yes'], { cwd: root })
-        if (dryRun) continue
-        const dir = findSkillDir(root, name)
-        if (dir) rmSync(repoPathStrict(root, `${SHARED_SKILLS}/${dir}`), { recursive: true, force: true })
-      }
-      if (!dryRun) pruneLock(root, targets)
-    },
-  }
-}

package/lib/clis.mjs

@@ -1,122 +1,11 @@
-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 {
-    // 경로를 밖으로 낸다 — 상세 패널이 "이 항목이 어디에 쓰이나"를 보여 준다.
-    // 어댑터가 실제로 쓰는 값과 같은 변수라 두 곳이 갈릴 수 없다.
-    file: relFile,
-    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(', ')}]`,
-  ]
-}
-
-// codex·grok은 TOML을 쓴다. jsonAdapter와 같은 이유로 경로를 한 번만 적는다.
-function tomlAdapter(file) {
-  return {
-    file,
-    has: (root, name) => hasSection(repoPath(root, file), name),
-    add: (root, name, s) => appendSection(repoPathStrict(root, file), name, tomlLines(s)),
-    remove: (root, name) => removeSection(repoPathStrict(root, file), name),
-  }
-}
-
+// 2.0.0이 지원하는 네 CLI. 설치는 각 CLI의 공식 명령이 맡으므로 여기에는
+// 이름과 실행 파일만 둔다 — 설정 파일 경로와 쓰기 어댑터는 더는 없다.
 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',
-    ...tomlAdapter('.codex/config.toml'),
-  },
-  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',
-    ...tomlAdapter('.grok/config.toml'),
-  },
-  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 }),
-  },
-  // Antigravity는 프로젝트 스코프 MCP 파일이 없다 — MCP는 홈 글로벌
-  // (~/.gemini/config/mcp_config.json)에서만 설정한다(bootstrap/manifest.mjs
-  // 주석·README). 그래서 어댑터(file·has·add·remove)가 없다. 그래도 목록에
-  // 두는 이유는 부트스트랩이 지원하는 11개 도구와 화면의 CLI 수가 어긋나면
-  // 안 되기 때문이다 — 공유 .agents/skills를 네이티브로 읽으므로 레지스트리
-  // 스킬은 실제로 닿고, MCP 항목은 "왜 안 닿는지"를 사유로 밝힌다.
-  antigravity: {
-    label: 'Antigravity',
-  },
+  claude: { label: 'Claude Code', bin: 'claude' },
+  codex: { label: 'Codex', bin: 'codex' },
+  opencode: { label: 'OpenCode', bin: 'opencode' },
+  // Antigravity CLI의 실행 파일 이름은 agy다.
+  antigravity: { label: 'Antigravity', bin: 'agy' },
 }
 
 export const CLI_IDS = Object.keys(CLIS)
-// 프로젝트 설정 파일에 MCP를 쓸 수 있는 CLI — 어댑터가 있는 것만.
-export const MCP_CLI_IDS = CLI_IDS.filter((id) => typeof CLIS[id].add === 'function')

package/lib/commands.mjs

@@ -0,0 +1,47 @@
+// 출력 모드(--print). 실행 모드와 같은 item.steps()에서 명령을 얻는다 —
+// 사용자가 복사해 직접 돌리는 명령과 설치기가 도는 명령이 같아야 한다.
+import { CLIS, CLI_IDS } from './clis.mjs'
+import { shellQuote } from './catalog.mjs'
+import { SHARED } from './recipe.mjs'
+
+const ORDER = [SHARED, ...CLI_IDS, 'files']
+// 따옴표 없이도 셸이 한 인자로 읽는 문자만. 복사해 붙일 줄이 읽기 쉬워야 한다.
+const PLAIN = /^[A-Za-z0-9_@+=:,./-]+$/
+
+export function quoteArg(arg, platform = process.platform) {
+  return PLAIN.test(arg) ? arg : shellQuote(arg, platform)
+}
+
+export function planCommands(changes) {
+  const groups = new Map()
+  const push = (key, entry) => {
+    if (!groups.has(key)) groups.set(key, { key, entries: [] })
+    groups.get(key).entries.push(entry)
+  }
+  for (const { item, action, state } of changes) {
+    // 파일을 직접 쓰는 항목(.gitmessage.txt 등)은 명령이 없다.
+    if (typeof item.steps !== 'function') { push('files', { item, action, manual: true }); continue }
+    for (const step of item.steps(action, state)) push(step.cli, { item, action, step })
+  }
+  return ORDER.filter((k) => groups.has(k)).map((k) => groups.get(k))
+}
+
+export function formatCommands(groups, { t, scope, platform = process.platform }) {
+  if (groups.length === 0) return [t('print.none')]
+  const lines = [t('print.title'), '']
+  for (const g of groups) {
+    const title = g.key === SHARED ? t('print.shared') : g.key === 'files' ? t('print.files') : CLIS[g.key].label
+    lines.push(`# ${title} — ${t(`scope.${scope}`)}`)
+    for (const e of g.entries) {
+      if (e.manual) lines.push(`# ${t('print.fileItem', { label: e.item.label })}`)
+      else if (e.step.fn) lines.push(`#   ${e.step.describe}`)
+      else {
+        // 작업 디렉터리가 필요한 단계 — 복사해 붙이는 사람이 위치를 알아야 한다.
+        if (e.step.cwd) lines.push(`#   (run in ${e.step.cwd})`)
+        lines.push(e.step.argv.map((a) => quoteArg(a, platform)).join(' '))
+      }
+    }
+    lines.push('')
+  }
+  return lines
+}

package/lib/engine.mjs

@@ -1,14 +1,19 @@
 import { makeExec } from './catalog.mjs'
 import { createT, LocalizedError, msg } from './i18n/index.mjs'
+import { createProbe } from './probe.mjs'
 
-export async function scan(root, items) {
+// probe는 스캔 하나가 공유하는 감지 캐시다. 없으면 여기서 만든다 — design.md
+// 항목처럼 probe를 안 쓰는 detect는 그냥 무시한다.
+export async function scan(root, items, { probe = null, scope = 'project' } = {}) {
+  const shared = probe ?? createProbe({ root, scope, exec: makeExec(false) })
   const states = []
   for (const item of items) {
     try {
-      const r = await item.detect({ root })
-      // excluded는 전역 항목이 "이 머신에 없는 CLI"를 알리는 자리다 — 행 힌트가
-      // supports를 나열할 때 그 CLI를 빼고 따로 표시한다.
-      states.push({ item, status: r.status, detail: r.detail, excluded: r.excluded ?? [] })
+      const r = await item.detect({ root, probe: shared })
+      // excluded는 "이 머신에 없는 CLI"를 알리는 자리다 — 행 힌트가 supports를
+      // 나열할 때 그 CLI를 빼고 따로 표시한다. result는 감지 결과 전체로,
+      // 레시피 항목의 steps()가 어느 CLI에 이미 있는지(present)를 읽는다.
+      states.push({ item, status: r.status, detail: r.detail, excluded: r.excluded ?? [], result: r })
     } catch (err) {
       states.push({ item, status: 'absent', detail: msg('item.scanFailed', { message: err.message }) })
     }
@@ -33,11 +38,11 @@ export function assertExclusive(items, selectedIds) {
 
 export function planChanges(states, selectedIds) {
   const changes = []
-  for (const { item, status } of states) {
+  for (const { item, status, result } 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' })
+    if (selected && status === 'absent') changes.push({ item, action: 'install', state: result })
+    else if (selected && status === 'partial') changes.push({ item, action: 'complete', state: result })
+    else if (!selected && status !== 'absent') changes.push({ item, action: 'uninstall', state: result })
   }
   return changes
 }
@@ -74,7 +79,7 @@ export async function apply(root, changes, { dryRun = false, log = console.log,
   }
 
   for (let index = 0; index < total; index++) {
-    const { item, action } = changes[index]
+    const { item, action, state } = changes[index]
 
     // 중단은 **항목 경계에서만** 본다. 외부 명령을 중간에 죽이면 반쯤 설치된
     // 상태가 남는다 — 그래서 AbortSignal이 아니라 술어(predicate)다.
@@ -98,7 +103,7 @@ export async function apply(root, changes, { dryRun = false, log = console.log,
     // log까지 넘긴다 — 파일을 직접 쓰는 항목(MCP·design.md)은 exec를 거치지
     // 않아 dry-run에서 아무것도 보고하지 못했다. 결과줄은 ✔ 설치라고 찍히는데
     // 무엇이 바뀔지는 알 수 없는 상태였다.
-    const ctx = { root, dryRun, exec, log, t }
+    const ctx = { root, dryRun, exec, log, t, state }
     let result
     try {
       const fn = action === 'uninstall' ? item.uninstall : item.install