@rch4com/agent-setup 1.0.0 → 1.3.0

package/lib/args.mjs

@@ -6,72 +6,16 @@
 // 예전에는 --set만 process.exit(2)로 빠져나가 같은 사용자 오류가
 // 경로에 따라 1과 2로 갈렸다.
 
-// `bootstrap` 서브커맨드 사용법. install.mjs와 두 런처(setup-agents.sh/.ps1) 모두에서 안내한다.
-export const BOOTSTRAP_USAGE = `사용법: npx @rch4com/agent-setup bootstrap [--skill-mode auto|link|copy] [--dry-run]
-       node install.mjs bootstrap [옵션]   # 저장소에 설치기를 두고 쓸 때
-
-옵션:
-  --skill-mode auto|link|copy  스킬 연결 방식을 지정합니다. (기본값: auto)
-                                  auto: 심볼릭 링크를 먼저 시도하고, 실패하면 복사로 전환합니다.
-                                  link: 심볼릭 링크만 시도합니다. 실패하면 오류로 종료합니다.
-                                  copy: 항상 복제본을 만듭니다.
-  --dry-run                    아무것도 바꾸지 않고 예정된 동작만 출력합니다.
-  -h, --help                   이 도움말을 출력하고 종료합니다.
-
-런처로도 사용할 수 있습니다:
-  ./setup-agents.sh [옵션]
-  pwsh -File ./setup-agents.ps1 [옵션]
-  --tui (또는 -Tui)를 주면 의존성을 설치하고 대화형 화면을 엽니다.
-  거기서 부트스트랩·에이전트·design.md를 한 목록에서 검색하고 고릅니다.`
+import { LOCALES, LocalizedError, createT } from './i18n/index.mjs'
 
+// 사용법은 모듈 로드 시점에 로케일을 모르므로 상수가 될 수 없다.
+// `bootstrap` 서브커맨드 사용법. install.mjs와 두 런처(setup-agents.sh/.ps1) 모두에서 안내한다.
+export const bootstrapUsage = (t) => t('usage.bootstrap')
 // 서브커맨드 없는 최상위 사용법. `design`은 자기 사용법을 따로 갖는다.
-export const ROOT_USAGE = `사용법: npx @rch4com/agent-setup [옵션]
-       npx @rch4com/agent-setup bootstrap [옵션]
-       npx @rch4com/agent-setup design [옵션]
-
-저장소에 설치기를 두고 쓸 때는 npx @rch4com/agent-setup 자리에
-node install.mjs 를 넣으면 됩니다.
-
-옵션이 없으면 대화형 화면을 엽니다 — 부트스트랩·에이전트·design.md를
-한 목록에서 검색하고 고릅니다.
-
-옵션:
-  --list                       현재 설치 상태만 출력하고 종료합니다.
-  --set <목록>                 쉼표로 구분한 항목을 목표 상태로 맞춥니다.
-                               전체 제거는 --set "" 로 명시하세요.
-  --skill-mode auto|link|copy  대화형 화면에서 실행하는 부트스트랩의 스킬
-                               연결 방식입니다. (기본값: auto)
-  --design-dir <경로>          design.md 소스를 더합니다. <소스id>=<경로>
-                               형식도 받으며 반복 지정할 수 있습니다.
-  --dry-run                    아무것도 바꾸지 않고 예정된 동작만 출력합니다.
-  -h, --help                   이 도움말을 출력하고 종료합니다.
-
---list와 --set은 동작을 고르는 플래그라 함께 쓸 수 없습니다.
-
-서브커맨드 도움말: npx @rch4com/agent-setup bootstrap --help
-                   npx @rch4com/agent-setup design --help`
-
-export const DESIGN_USAGE = `사용법: npx @rch4com/agent-setup design [옵션]
-       node install.mjs design [옵션]   # 저장소에 설치기를 두고 쓸 때
-
-옵션이 없으면 대화형 화면을 엽니다 — DESIGN.MD 섹션이 그 안에 있습니다.
-
-옵션:
-  --list                 카탈로그와 설치 상태를 출력합니다.
-  --set <목록>           쉼표로 구분한 항목을 목표 상태로 맞춥니다.
-                         토큰은 <이름> 또는 <제공자>/<이름> 입니다.
-                         전체 제거는 --set "" 로 명시하세요.
-  --preview <목록>       미리보기를 엽니다.
-  --sync=installed       설치본을 원본 최신으로 다시 받습니다.
-  --sync=catalog         사용 가능 목록·카테고리를 소스에서 다시 만듭니다.
-  --sync=stale           설치본을 원본과 해시 비교합니다.
-  --design-dir <경로>    design.md 소스를 더합니다. <소스id>=<경로>
-                         형식도 받으며 반복 지정할 수 있습니다.
-  --dry-run              아무것도 바꾸지 않고 예정된 동작만 출력합니다.
-  -h, --help             이 도움말을 출력하고 종료합니다.
-
---list, --set, --preview, --sync는 동작을 고르는 플래그라
-한 번에 하나만 지정할 수 있습니다.`
+export const rootUsage = (t) => t('usage.root')
+export const designUsage = (t) => t('usage.design')
+export const updateUsage = (t) => t('usage.update')
+export const statusUsage = (t) => t('usage.status')
 
 const SKILL_MODES = ['auto', 'link', 'copy']
 
@@ -79,16 +23,18 @@ const SKILL_MODES = ['auto', 'link', 'copy']
 // 미지 인자를 조용히 삼키지 않기 위한 것이다 — 오타(`--dryrun`)나 지원하지
 // 않는 형식(`--set=a`)이 무시되면 사용자는 명령이 먹혔다고 믿지만 아무 일도
 // 일어나지 않는다. bootstrap 파서만 지키던 규칙을 세 파서 모두로 넓힌다.
-const HELP_SPEC = { '-h': 'bool', '--help': 'bool' }
+const COMMON_SPEC = { '-h': 'bool', '--help': 'bool', '--lang': 'value' }
 const ROOT_SPEC = {
-  ...HELP_SPEC, '--dry-run': 'bool', '--list': 'bool',
+  ...COMMON_SPEC, '--dry-run': 'bool', '--list': 'bool',
   '--set': 'value', '--skill-mode': 'value', '--design-dir': 'value',
 }
 const DESIGN_SPEC = {
-  ...HELP_SPEC, '--dry-run': 'bool', '--list': 'bool', '--set': 'value',
+  ...COMMON_SPEC, '--dry-run': 'bool', '--list': 'bool', '--set': 'value',
   '--preview': 'value', '--sync': 'value', '--design-dir': 'value',
 }
-const BOOTSTRAP_SPEC = { ...HELP_SPEC, '--dry-run': 'bool', '--skill-mode': 'value' }
+const BOOTSTRAP_SPEC = { ...COMMON_SPEC, '--dry-run': 'bool', '--adopt': 'bool', '--skill-mode': 'value' }
+const UPDATE_SPEC = { ...COMMON_SPEC, '--dry-run': 'bool', '--force': 'bool' }
+const STATUS_SPEC = { ...COMMON_SPEC, '--json': 'bool' }
 
 export function assertKnownArgs(argv, spec, usage) {
   for (let i = 0; i < argv.length; i++) {
@@ -96,8 +42,8 @@ export function assertKnownArgs(argv, spec, usage) {
     const eq = token.startsWith('--') ? token.indexOf('=') : -1
     const name = eq > 0 ? token.slice(0, eq) : token
     const kind = spec[name]
-    if (kind === undefined) throw new Error(`알 수 없는 인자입니다: ${token}\n\n${usage}`)
-    if (kind === 'bool' && eq > 0) throw new Error(`${name}에는 값을 줄 수 없습니다: ${token}\n\n${usage}`)
+    if (kind === undefined) throw new LocalizedError('error.unknownArg', { token, usage })
+    if (kind === 'bool' && eq > 0) throw new LocalizedError('error.flagTakesNoValue', { name, token, usage })
     // `--플래그 값` 형태는 값 한 칸을 건너뛴다. `--플래그=값`은 이미 한 토큰이다.
     if (kind === 'value' && eq < 0) i++
   }
@@ -111,13 +57,13 @@ export function assertSingleAction(argv, names, usage) {
   const given = names.filter((name) => hasFlag(argv, name))
   if (given.length > 1) {
     // 조사를 붙이지 않는다 — 플래그 이름에 따라 은/는이 갈려 문장이 어색해진다.
-    throw new Error(`함께 쓸 수 없습니다: ${given.join(', ')} — 동작 플래그는 한 번에 하나만 지정하세요.\n\n${usage}`)
+    throw new LocalizedError('error.singleAction', { given: given.join(', '), usage })
   }
 }
 
 function checkSkillMode(value, usage) {
   if (!SKILL_MODES.includes(value)) {
-    throw new Error(`--skill-mode는 ${SKILL_MODES.join(', ')} 중 하나여야 합니다: ${value}\n\n${usage}`)
+    throw new LocalizedError('error.badSkillMode', { list: SKILL_MODES.join(', '), value, usage })
   }
   return value
 }
@@ -130,7 +76,7 @@ export function parseSkillMode(argv, usage) {
     if (a === '--skill-mode') {
       const value = argv[i + 1]
       if (value === undefined || value.startsWith('--')) {
-        throw new Error(`--skill-mode 뒤에 값이 필요합니다 (${SKILL_MODES.join(', ')} 중 하나).\n\n${usage}`)
+        throw new LocalizedError('error.skillModeNeedsValue', { list: SKILL_MODES.join(', '), usage })
       }
       mode = checkSkillMode(value, usage)
       i++
@@ -141,6 +87,45 @@ export function parseSkillMode(argv, usage) {
   return mode
 }
 
+function checkLang(value, usage) {
+  if (!LOCALES.includes(value)) {
+    throw new LocalizedError('error.badLang', { list: LOCALES.join(', '), value, usage })
+  }
+  return value
+}
+
+// `--lang <값>`과 `--lang=<값>`을 모두 받는다. 없으면 null —
+// 이 자리에서 기본값을 정하지 않는다. 우선순위 판단은 resolveLocale의 몫이다.
+export function parseLang(argv, usage) {
+  let lang = null
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--lang') {
+      const value = argv[i + 1]
+      if (value === undefined || value.startsWith('--')) {
+        throw new LocalizedError('error.langNeedsValue', { list: LOCALES.join(', '), usage })
+      }
+      lang = checkLang(value, usage)
+      i++
+    } else if (a.startsWith('--lang=')) {
+      lang = checkLang(a.slice('--lang='.length), usage)
+    }
+  }
+  return lang
+}
+
+// 진입점이 로케일을 정하기 **전에** 부르는 관대한 사전 스캔이다.
+// 여기서 던지면 인자 오류가 늘 영어로 나온다 — 정식 파서가 지역화된
+// 오류를 내도록 미지원 값은 조용히 null로 넘긴다.
+export function preScanLang(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    const value = a === '--lang' ? argv[i + 1] : a.startsWith('--lang=') ? a.slice('--lang='.length) : null
+    if (typeof value === 'string' && LOCALES.includes(value)) return value
+  }
+  return null
+}
+
 function wantsHelp(argv) {
   return argv.includes('-h') || argv.includes('--help')
 }
@@ -155,12 +140,12 @@ export function requireValue(argv, name) {
   const eq = argv.find((a) => a.startsWith(`${name}=`))
   if (eq !== undefined) {
     const value = eq.slice(name.length + 1)
-    if (!value) throw new Error(`${name} 뒤에 값이 필요합니다.`)
+    if (!value) throw new LocalizedError('error.needsValue', { name })
     return value
   }
   const value = argv[argv.indexOf(name) + 1]
   if (value === undefined || value.startsWith('--')) {
-    throw new Error(`${name} 뒤에 값이 필요합니다.`)
+    throw new LocalizedError('error.needsValue', { name })
   }
   return value
 }
@@ -171,12 +156,12 @@ export function collectValues(argv, name) {
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === name) {
       const value = argv[i + 1]
-      if (value === undefined || value.startsWith('--')) throw new Error(`${name} 뒤에 값이 필요합니다.`)
+      if (value === undefined || value.startsWith('--')) throw new LocalizedError('error.needsValue', { name })
       values.push(value)
       i++
     } else if (argv[i].startsWith(`${name}=`)) {
       const value = argv[i].slice(name.length + 1)
-      if (!value) throw new Error(`${name} 뒤에 값이 필요합니다.`)
+      if (!value) throw new LocalizedError('error.needsValue', { name })
       values.push(value)
     }
   }
@@ -192,7 +177,7 @@ export function parseSetArg(argv) {
   if (!argv.includes('--set')) return null
   const value = argv[argv.indexOf('--set') + 1]
   if (value === undefined || value.startsWith('--')) {
-    throw new Error('--set 뒤에 항목 목록이 필요합니다. 전체 제거는 --set "" 로 명시하세요.')
+    throw new LocalizedError('error.setNeedsValue')
   }
   return value
 }
@@ -201,12 +186,13 @@ export function parseSetArg(argv) {
 // 먼저 내밀 이유가 없다. 아래 두 파서가 같은 규칙을 따른다.
 
 // 서브커맨드 없는 최상위 인자.
-export function parseRootArgs(argv) {
+export function parseRootArgs(argv, t = createT('en')) {
+  const usage = rootUsage(t)
   if (wantsHelp(argv)) {
-    return { help: true, dryRun: false, listOnly: false, setArg: null, skillMode: 'auto', designDirs: [], interactive: false }
+    return { help: true, dryRun: false, listOnly: false, setArg: null, skillMode: 'auto', designDirs: [], lang: null, interactive: false }
   }
-  assertKnownArgs(argv, ROOT_SPEC, ROOT_USAGE)
-  assertSingleAction(argv, ['--list', '--set'], ROOT_USAGE)
+  assertKnownArgs(argv, ROOT_SPEC, usage)
+  assertSingleAction(argv, ['--list', '--set'], usage)
   const setArg = parseSetArg(argv)
   return {
     help: false,
@@ -215,20 +201,23 @@ export function parseRootArgs(argv) {
     setArg,
     // 대화형 화면에서 실행하는 부트스트랩이 이 값을 쓴다. 예전에는 루트에서
     // 읽지 않아, 런처가 넘긴 --skill-mode가 조용히 버려졌다.
-    skillMode: parseSkillMode(argv, ROOT_USAGE),
+    skillMode: parseSkillMode(argv, usage),
     designDirs: collectValues(argv, '--design-dir'),
-    // 목록·집합 지정이 없으면 대화형 화면으로 간다.
+    lang: parseLang(argv, usage),
+    // 목록·집합 지정이 없으면 대화형 화면으로 간다. --lang은 동작 플래그가
+    // 아니므로 여기에 끼지 않는다.
     interactive: !argv.includes('--list') && setArg === null,
   }
 }
 
 // `design` 서브커맨드 플래그.
-export function parseDesignArgs(argv) {
+export function parseDesignArgs(argv, t = createT('en')) {
+  const usage = designUsage(t)
   if (wantsHelp(argv)) {
-    return { help: true, dryRun: false, list: false, set: null, preview: null, sync: null, designDirs: [], interactive: false }
+    return { help: true, dryRun: false, list: false, set: null, preview: null, sync: null, designDirs: [], lang: null, interactive: false }
   }
-  assertKnownArgs(argv, DESIGN_SPEC, DESIGN_USAGE)
-  assertSingleAction(argv, ['--list', '--set', '--preview', '--sync'], DESIGN_USAGE)
+  assertKnownArgs(argv, DESIGN_SPEC, usage)
+  assertSingleAction(argv, ['--list', '--set', '--preview', '--sync'], usage)
   const list = argv.includes('--list')
   const set = parseSetArg(argv)
   const preview = hasFlag(argv, '--preview') ? requireValue(argv, '--preview') : null
@@ -237,7 +226,7 @@ export function parseDesignArgs(argv) {
   const s = argv.find((a) => a === '--sync' || a.startsWith('--sync='))
   if (s) {
     const m = /^--sync=(installed|catalog|stale)$/.exec(s)
-    if (!m) throw new Error('--sync=installed|catalog|stale 형식으로 지정하세요.')
+    if (!m) throw new LocalizedError('error.badSync')
     sync = m[1]
   }
 
@@ -249,18 +238,39 @@ export function parseDesignArgs(argv) {
     preview,
     sync,
     designDirs: collectValues(argv, '--design-dir'),
+    lang: parseLang(argv, usage),
     interactive: !list && set === null && preview === null && sync === null,
   }
 }
 
-// `bootstrap`에 허용되는 플래그: --dry-run, --skill-mode(+값)/--skill-mode=값, -h/--help.
+// `bootstrap`에 허용되는 플래그: --dry-run, --adopt,
+// --skill-mode(+값)/--skill-mode=값, --lang(+값)/--lang=값, -h/--help.
 // 그 외 인자는 거부한다 — 조용히 삼켜지는 것을 막기 위해서다.
-export function parseBootstrapArgs(argv) {
-  if (wantsHelp(argv)) return { dryRun: false, skillMode: 'auto', help: true }
-  assertKnownArgs(argv, BOOTSTRAP_SPEC, BOOTSTRAP_USAGE)
+export function parseBootstrapArgs(argv, t = createT('en')) {
+  const usage = bootstrapUsage(t)
+  if (wantsHelp(argv)) return { dryRun: false, skillMode: 'auto', adopt: false, help: true, lang: null }
+  assertKnownArgs(argv, BOOTSTRAP_SPEC, usage)
   return {
     dryRun: argv.includes('--dry-run'),
-    skillMode: parseSkillMode(argv, BOOTSTRAP_USAGE),
+    adopt: argv.includes('--adopt'),
+    skillMode: parseSkillMode(argv, usage),
+    lang: parseLang(argv, usage),
     help: false,
   }
 }
+
+// `update`에 허용되는 플래그: --dry-run, --force, --lang(+값)/--lang=값, -h/--help.
+export function parseUpdateArgs(argv, t = createT('en')) {
+  const usage = updateUsage(t)
+  if (wantsHelp(argv)) return { help: true, dryRun: false, force: false, lang: null }
+  assertKnownArgs(argv, UPDATE_SPEC, usage)
+  return { help: false, dryRun: argv.includes('--dry-run'), force: argv.includes('--force'), lang: parseLang(argv, usage) }
+}
+
+// `status`에 허용되는 플래그: --json, --lang(+값)/--lang=값, -h/--help.
+export function parseStatusArgs(argv, t = createT('en')) {
+  const usage = statusUsage(t)
+  if (wantsHelp(argv)) return { help: true, json: false, lang: null }
+  assertKnownArgs(argv, STATUS_SPEC, usage)
+  return { help: false, json: argv.includes('--json'), lang: parseLang(argv, usage) }
+}

package/lib/bootstrap/adapter.mjs

@@ -1,95 +1,96 @@
-// 스킬 어댑터 — .agents/skills를 도구별 경로에서 보이게 한다.
-// Windows는 Junction을 쓴다. 관리자 권한이 필요 없고, MSYS(Git Bash)의 ln -s가
-// 링크 대신 복사를 만드는 문제도 우회한다.
-import { cpSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
-import { dirname, join, relative, resolve } from 'node:path'
-import { repoPath, repoPathStrict } from '../context.mjs'
-import { pathExists } from './apply.mjs'
-
-const MARKER = '.agent-kit-managed-copy'
-const SOURCE_REL = '.agents/skills'
-
-// 심볼릭 링크/Junction이면 가리키는 절대 경로를, 아니면 null을 돌려준다.
-function linkTarget(target) {
-  try {
-    if (!lstatSync(target).isSymbolicLink()) return null
-    return resolve(dirname(target), readlinkSync(target))
-  } catch {
-    return null
-  }
-}
-
-function createLink(source, target) {
-  if (process.platform === 'win32') {
-    // Junction은 절대 경로를 요구한다.
-    symlinkSync(source, target, 'junction')
-  } else {
-    symlinkSync(relative(dirname(target), source), target)
-  }
-}
-
-function createCopy(source, target) {
-  mkdirSync(target, { recursive: true })
-  cpSync(source, target, { recursive: true })
-  writeFileSync(join(target, MARKER), '', { encoding: 'utf8' })
-}
-
-export function configureAdapter(root, { tool, path: rel }, { dryRun = false, skillMode = 'auto', log }) {
-  // 기존 상태를 살펴보는 데에는 어휘적 경로를 쓴다. target이 저장소 밖을 가리키는
-  // 링크일 수 있는데, 그 경우도 "보존 + 경고"가 정답이라 지켜야 할 쓰기가 없다.
-  // repoPathStrict를 여기서 쓰면 이탈 링크에서 예외가 던져져 경고 대신 죽는다.
-  const target = repoPath(root, rel)
-
-  const linked = linkTarget(target)
-  if (linked !== null) {
-    if (linked === repoPath(root, SOURCE_REL)) {
-      log(`${tool} 스킬 링크 확인: ${rel}`)
-      return { ok: true, action: 'skip', path: rel }
-    }
-    log(`경고: ${rel} 경로가 다른 위치를 가리키는 링크입니다. 변경하지 않습니다.`)
-    return { ok: true, action: 'warn', path: rel, message: '다른 위치를 가리키는 링크' }
-  }
-
-  const managedCopy = pathExists(target) && pathExists(join(target, MARKER))
-  if (pathExists(target) && !managedCopy) {
-    log(`경고: ${rel} 경로가 이미 존재하며 agent-kit 관리 대상이 아닙니다. 변경하지 않습니다.`)
-    return { ok: true, action: 'warn', path: rel, message: '관리 대상이 아닌 기존 항목' }
-  }
-
-  // 여기부터는 실제로 링크/복사본을 만드는 경로다. 엄격 검사는 dry-run 여부와
-  // 무관하게 항상 하고(dry-run에서도 이탈 경로를 걸러내려면), 실제 파일시스템
-  // 쓰기만 !dryRun으로 막는다 — apply.mjs의 ensureDirs와 같은 형태.
-  // source(.agents/skills)는 실제로 읽어 복사하는 대상이므로 여기서 함께 검사한다.
-  const source = repoPathStrict(root, SOURCE_REL)
-  const strictTarget = repoPathStrict(root, rel)
-
-  if (dryRun) {
-    log(`${tool} 스킬 어댑터 생성 예정: ${rel} (${skillMode})`)
-    return { ok: true, action: 'skip', path: rel }
-  }
-
-  if (managedCopy) {
-    log(`${tool} 스킬 복제본 동기화: ${rel}`)
-    // 마커가 확인된 복사본만 지운다.
-    rmSync(strictTarget, { recursive: true, force: true })
-  }
-
-  mkdirSync(dirname(strictTarget), { recursive: true })
-
-  if (skillMode !== 'copy') {
-    try {
-      createLink(source, strictTarget)
-      log(`${tool} 스킬 링크 생성: ${rel} -> ${SOURCE_REL}`)
-      return { ok: true, action: 'link', path: rel }
-    } catch (err) {
-      if (skillMode === 'link') {
-        return { ok: false, action: 'link', path: rel, message: `링크 생성 실패: ${err.message}` }
-      }
-      log(`경고: ${tool} 링크 생성에 실패하여 복사 방식으로 전환합니다.`)
-    }
-  }
-
-  createCopy(source, strictTarget)
-  log(`${tool} 스킬 복제본 생성: ${rel}`)
-  return { ok: true, action: 'copy', path: rel }
-}
+// 스킬 어댑터 — .agents/skills를 도구별 경로에서 보이게 한다.
+// Windows는 Junction을 쓴다. 관리자 권한이 필요 없고, MSYS(Git Bash)의 ln -s가
+// 링크 대신 복사를 만드는 문제도 우회한다.
+import { cpSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { repoPath, repoPathStrict } from '../context.mjs'
+import { createT, msg } from '../i18n/index.mjs'
+import { pathExists } from './apply.mjs'
+
+const MARKER = '.agent-kit-managed-copy'
+const SOURCE_REL = '.agents/skills'
+
+// 심볼릭 링크/Junction이면 가리키는 절대 경로를, 아니면 null을 돌려준다.
+function linkTarget(target) {
+  try {
+    if (!lstatSync(target).isSymbolicLink()) return null
+    return resolve(dirname(target), readlinkSync(target))
+  } catch {
+    return null
+  }
+}
+
+function createLink(source, target) {
+  if (process.platform === 'win32') {
+    // Junction은 절대 경로를 요구한다.
+    symlinkSync(source, target, 'junction')
+  } else {
+    symlinkSync(relative(dirname(target), source), target)
+  }
+}
+
+function createCopy(source, target) {
+  mkdirSync(target, { recursive: true })
+  cpSync(source, target, { recursive: true })
+  writeFileSync(join(target, MARKER), '', { encoding: 'utf8' })
+}
+
+export function configureAdapter(root, { tool, path: rel }, { dryRun = false, skillMode = 'auto', log, t = createT('en') }) {
+  // 기존 상태를 살펴보는 데에는 어휘적 경로를 쓴다. target이 저장소 밖을 가리키는
+  // 링크일 수 있는데, 그 경우도 "보존 + 경고"가 정답이라 지켜야 할 쓰기가 없다.
+  // repoPathStrict를 여기서 쓰면 이탈 링크에서 예외가 던져져 경고 대신 죽는다.
+  const target = repoPath(root, rel)
+
+  const linked = linkTarget(target)
+  if (linked !== null) {
+    if (linked === repoPath(root, SOURCE_REL)) {
+      log(t('log.skill.linkOk', { tool, path: rel }))
+      return { ok: true, action: 'skip', path: rel }
+    }
+    log(t('log.skill.warnForeignLink', { path: rel }))
+    return { ok: true, action: 'warn', path: rel, message: msg('msg.foreignLink') }
+  }
+
+  const managedCopy = pathExists(target) && pathExists(join(target, MARKER))
+  if (pathExists(target) && !managedCopy) {
+    log(t('log.skill.warnUnmanaged', { path: rel }))
+    return { ok: true, action: 'warn', path: rel, message: msg('msg.unmanagedExisting') }
+  }
+
+  // 여기부터는 실제로 링크/복사본을 만드는 경로다. 엄격 검사는 dry-run 여부와
+  // 무관하게 항상 하고(dry-run에서도 이탈 경로를 걸러내려면), 실제 파일시스템
+  // 쓰기만 !dryRun으로 막는다 — apply.mjs의 ensureDirs와 같은 형태.
+  // source(.agents/skills)는 실제로 읽어 복사하는 대상이므로 여기서 함께 검사한다.
+  const source = repoPathStrict(root, SOURCE_REL)
+  const strictTarget = repoPathStrict(root, rel)
+
+  if (dryRun) {
+    log(t('log.skill.plan', { tool, path: rel, mode: skillMode }))
+    return { ok: true, action: 'skip', path: rel }
+  }
+
+  if (managedCopy) {
+    log(t('log.skill.copySync', { tool, path: rel }))
+    // 마커가 확인된 복사본만 지운다.
+    rmSync(strictTarget, { recursive: true, force: true })
+  }
+
+  mkdirSync(dirname(strictTarget), { recursive: true })
+
+  if (skillMode !== 'copy') {
+    try {
+      createLink(source, strictTarget)
+      log(t('log.skill.linkCreate', { tool, path: rel, target: SOURCE_REL }))
+      return { ok: true, action: 'link', path: rel }
+    } catch (err) {
+      if (skillMode === 'link') {
+        return { ok: false, action: 'link', path: rel, message: msg('msg.linkFailed', { message: err.message }) }
+      }
+      log(t('log.skill.linkFellBack', { tool }))
+    }
+  }
+
+  createCopy(source, strictTarget)
+  log(t('log.skill.copyCreate', { tool, path: rel }))
+  return { ok: true, action: 'copy', path: rel }
+}