@rch4com/agent-setup 1.9.0 → 1.10.0

package/lib/bootstrap/flow.mjs

@@ -1,140 +1,140 @@
-// 부트스트랩 진입점 — 순서와 보고만 담당한다.
-// 무엇을 만들지는 manifest.mjs가, 어떻게 만들지는 apply.mjs·adapter.mjs가 안다.
-import { MANIFEST } from './manifest.mjs'
-import {
-  configureAdapterSafe, ensureBlocks, ensureDirs, ensureFiles, ensureIgnore, ensureJsonKeys,
-} from './apply.mjs'
-import { RECORD_REL, collectManaged, emptyRecord, readRecord, writeRecord } from './record.mjs'
-import { createT, LocalizedError, toText } from '../i18n/index.mjs'
-import { width } from '../width.mjs'
-
-const SKILL_MODES = ['auto', 'link', 'copy']
-
-// 오른쪽 정렬. width.mjs의 pad()는 오른쪽에 공백을 채워 왼쪽 정렬만 하므로
-// 숫자에는 못 쓴다 — 자릿수가 9에서 10으로 늘 때 열이 흔들리지 않으려면
-// 왼쪽에 채워야 한다. 숫자만 다루니 실제로는 문자 수와 같지만, 이 저장소의
-// 다른 폭 계산과 방식을 맞추려고 width()로 잰다.
-function alignRight(text, w) {
-  return ' '.repeat(Math.max(0, w - width(text))) + text
-}
-
-// "[ 3/39]" 꼴의 단계 번호. total의 자릿수에 맞춰 n을 오른쪽 정렬한다.
-function counterTag(n, total) {
-  const totalText = String(total)
-  return `[${alignRight(String(n), width(totalText))}/${totalText}]`
-}
-
-export function runBootstrap(root, opts = {}) {
-  const { dryRun = false, skillMode = 'auto', adopt = false, log = console.log, manifest = MANIFEST, onProgress = null, t = createT('en') } = opts
-
-  if (!SKILL_MODES.includes(skillMode)) {
-    throw new LocalizedError('error.badSkillModeRuntime', { list: SKILL_MODES.join(', '), value: skillMode })
-  }
-
-  const say = (message) => log(`[agent-setup] ${message}`)
-  const ctx = { dryRun, log: say, t }
-
-  say(t('log.repoRoot', { path: root }))
-  say(t('log.noGlobalWrites'))
-
-  // 총 단계 수. 동기 파일 작업이라 단계 바만 돌지만, 무엇이 남았는지는
-  // 알려 줄 수 있다. adopt는 파일을 만들지 않으므로 기록 쓰기 한 단계뿐이다.
-  // 예측일 뿐이다 — ensureIgnore는 부정 항목이 기존 .gitignore에 가려지면
-  // manifest.ignore.length보다 많은 결과(경고 포함)를 돌려줄 수 있다.
-  let total = adopt
-    ? 1
-    : manifest.dirs.length + manifest.files.length + (manifest.settings ?? []).length
-      + manifest.blocks.length + manifest.adapters.length + manifest.ignore.length + 1
-  let done = 0
-  const step = (results) => {
-    const list = Array.isArray(results) ? results : [results]
-    for (const r of list) {
-      done++
-      // 실제 진행이 예측을 앞지르면 천장을 함께 올린다. total을 고정해 두면
-      // done > total인 알림이 나가 진행률이 100%를 넘고 바가 자기 너비를
-      // 넘겨 그려진다 — done을 total에 맞춰 죽이면 화면은 멈춘 것처럼 보이는데
-      // 남은 단계가 조용히 계속 도는, 더 나쁜 오류가 된다.
-      if (done > total) total = done
-      if (onProgress) onProgress({ done, total, path: r?.path ?? null })
-    }
-    return list
-  }
-
-  // 단계 안에서 나온 로그는 모아 뒀다가 step()이 done/total을 확정한 뒤에
-  // 번호를 붙여 낸다. ensureDirs는 이미 있는 항목을 건너뛸 때 아예 로그를
-  // 내지 않고, ensureIgnore는 여러 항목을 한 줄로 묶어 보고한다 — "몇 번째
-  // 줄이 찍혔는가"와 "몇 번째 항목을 처리했는가"가 그래서 어긋난다. 번호는
-  // 항목 순서가 아니라 처리 위치(done)를 보여 주는 것이 목적이므로, 이
-  // 구간이 시작한 위치(before)부터 실제로 찍힌 줄 수만큼만 순서대로 매긴다.
-  // 못 채운 자리는 건너뛰지만, 다음 구간은 항상 정확한 위치에서 이어져
-  // 마지막 줄은 반드시 total 가까이에서 끝난다.
-  //
-  // onProgress는 그대로 step()이 몬다 — 기계가 읽는 진행 이벤트와 사람이
-  // 읽는 로그 줄은 타이밍이 다르다(ensureX 호출이 끝나야 결과 배열이
-  // 나오고, 그제서야 done/total이 확정된다). 두 소비자를 하나의 흐름으로
-  // 우겨넣는 대신, 같은 done/total 계산을 공유하는 별도 경로로 뒀다.
-  const runStep = (run) => {
-    const buffer = []
-    const before = done
-    const list = step(run({ ...ctx, log: (message) => buffer.push(message) }))
-    let n = before
-    for (const message of buffer) {
-      n++
-      say(`${counterTag(n, total)} ${message}`)
-    }
-    return list
-  }
-
-  // --adopt는 이미 있는 저장소를 기록 체계로 끌어오는 용도라 파일을 만들지
-  // 않는다. 설치기를 복사해 쓰던 저장소가 여기로 들어온다.
-  const results = adopt ? [] : [
-    ...runStep((c) => ensureDirs(root, manifest.dirs, c)),
-    ...runStep((c) => ensureFiles(root, manifest.files, c)),
-    ...runStep((c) => ensureJsonKeys(root, manifest.settings ?? [], c)),
-    ...runStep((c) => ensureBlocks(root, manifest.blocks, c)),
-  ]
-
-  if (!adopt) {
-    // 어댑터는 항목별로 실패를 격리한다 — 하나가 실패해도 나머지를 계속한다.
-    // update.mjs도 같은 격리를 써야 하므로 apply.mjs가 단일 출처다.
-    for (const entry of manifest.adapters) {
-      results.push(...runStep((c) => configureAdapterSafe(root, entry, { ...c, skillMode })))
-    }
-
-    results.push(...runStep((c) => ensureIgnore(root, manifest.ignore, c)))
-  }
-
-  // 기존 기록의 items·design은 보존한다 — 부트스트랩은 배선만 다루므로
-  // 사용자가 고른 설치 항목을 지울 권한이 없다. dry-run에서는 읽지 않는다:
-  // 깨진 기록이 "무엇이 바뀔지 확인"까지 막을 이유가 없다.
-  const previous = dryRun ? null : readRecord(root)
-  const record = {
-    ...emptyRecord({ skillMode }),
-    // 부트스트랩은 배선만 다룬다. 사용자가 고른 언어·항목을 지울 권한이 없다.
-    lang: previous?.lang ?? null,
-    items: previous?.items ?? [],
-    design: previous?.design ?? [],
-    managed: collectManaged(root, manifest),
-  }
-  results.push(...runStep((c) => writeRecord(root, record, c)))
-
-  // 실제 결과 수가 예측과 다르면 마지막 알림으로 100%를 맞춘다.
-  // 진행 바가 87%에서 끝나면 사용자는 무엇이 실패했다고 읽는다.
-  if (onProgress && done !== total) onProgress({ done: total, total, path: null })
-
-  const failed = results.filter((r) => !r.ok)
-  log('')
-  if (failed.length > 0) {
-    say(t('bootstrap.failures', { count: failed.length }))
-    for (const f of failed) say(`  ✖ ${f.path} — ${toText(t, f.message)}`)
-  }
-  say(t('bootstrap.done'))
-  say(t('bootstrap.sharedGuide'))
-  say(t('bootstrap.sharedSkills'))
-  say(t('bootstrap.tools', { list: manifest.tools.join(', ') }))
-  say(t('bootstrap.repoOnly'))
-  say(t('bootstrap.noOverwrite'))
-  say(t('bootstrap.record', { path: RECORD_REL }))
-
-  return { results, failed, record }
-}
+// 부트스트랩 진입점 — 순서와 보고만 담당한다.
+// 무엇을 만들지는 manifest.mjs가, 어떻게 만들지는 apply.mjs·adapter.mjs가 안다.
+import { MANIFEST } from './manifest.mjs'
+import {
+  configureAdapterSafe, ensureBlocks, ensureDirs, ensureFiles, ensureIgnore, ensureJsonKeys,
+} from './apply.mjs'
+import { RECORD_REL, collectManaged, emptyRecord, readRecord, writeRecord } from './record.mjs'
+import { createT, LocalizedError, toText } from '../i18n/index.mjs'
+import { width } from '../width.mjs'
+
+const SKILL_MODES = ['auto', 'link', 'copy']
+
+// 오른쪽 정렬. width.mjs의 pad()는 오른쪽에 공백을 채워 왼쪽 정렬만 하므로
+// 숫자에는 못 쓴다 — 자릿수가 9에서 10으로 늘 때 열이 흔들리지 않으려면
+// 왼쪽에 채워야 한다. 숫자만 다루니 실제로는 문자 수와 같지만, 이 저장소의
+// 다른 폭 계산과 방식을 맞추려고 width()로 잰다.
+function alignRight(text, w) {
+  return ' '.repeat(Math.max(0, w - width(text))) + text
+}
+
+// "[ 3/39]" 꼴의 단계 번호. total의 자릿수에 맞춰 n을 오른쪽 정렬한다.
+function counterTag(n, total) {
+  const totalText = String(total)
+  return `[${alignRight(String(n), width(totalText))}/${totalText}]`
+}
+
+export function runBootstrap(root, opts = {}) {
+  const { dryRun = false, skillMode = 'auto', adopt = false, log = console.log, manifest = MANIFEST, onProgress = null, t = createT('en') } = opts
+
+  if (!SKILL_MODES.includes(skillMode)) {
+    throw new LocalizedError('error.badSkillModeRuntime', { list: SKILL_MODES.join(', '), value: skillMode })
+  }
+
+  const say = (message) => log(`[agent-setup] ${message}`)
+  const ctx = { dryRun, log: say, t }
+
+  say(t('log.repoRoot', { path: root }))
+  say(t('log.noGlobalWrites'))
+
+  // 총 단계 수. 동기 파일 작업이라 단계 바만 돌지만, 무엇이 남았는지는
+  // 알려 줄 수 있다. adopt는 파일을 만들지 않으므로 기록 쓰기 한 단계뿐이다.
+  // 예측일 뿐이다 — ensureIgnore는 부정 항목이 기존 .gitignore에 가려지면
+  // manifest.ignore.length보다 많은 결과(경고 포함)를 돌려줄 수 있다.
+  let total = adopt
+    ? 1
+    : manifest.dirs.length + manifest.files.length + (manifest.settings ?? []).length
+      + manifest.blocks.length + manifest.adapters.length + manifest.ignore.length + 1
+  let done = 0
+  const step = (results) => {
+    const list = Array.isArray(results) ? results : [results]
+    for (const r of list) {
+      done++
+      // 실제 진행이 예측을 앞지르면 천장을 함께 올린다. total을 고정해 두면
+      // done > total인 알림이 나가 진행률이 100%를 넘고 바가 자기 너비를
+      // 넘겨 그려진다 — done을 total에 맞춰 죽이면 화면은 멈춘 것처럼 보이는데
+      // 남은 단계가 조용히 계속 도는, 더 나쁜 오류가 된다.
+      if (done > total) total = done
+      if (onProgress) onProgress({ done, total, path: r?.path ?? null })
+    }
+    return list
+  }
+
+  // 단계 안에서 나온 로그는 모아 뒀다가 step()이 done/total을 확정한 뒤에
+  // 번호를 붙여 낸다. ensureDirs는 이미 있는 항목을 건너뛸 때 아예 로그를
+  // 내지 않고, ensureIgnore는 여러 항목을 한 줄로 묶어 보고한다 — "몇 번째
+  // 줄이 찍혔는가"와 "몇 번째 항목을 처리했는가"가 그래서 어긋난다. 번호는
+  // 항목 순서가 아니라 처리 위치(done)를 보여 주는 것이 목적이므로, 이
+  // 구간이 시작한 위치(before)부터 실제로 찍힌 줄 수만큼만 순서대로 매긴다.
+  // 못 채운 자리는 건너뛰지만, 다음 구간은 항상 정확한 위치에서 이어져
+  // 마지막 줄은 반드시 total 가까이에서 끝난다.
+  //
+  // onProgress는 그대로 step()이 몬다 — 기계가 읽는 진행 이벤트와 사람이
+  // 읽는 로그 줄은 타이밍이 다르다(ensureX 호출이 끝나야 결과 배열이
+  // 나오고, 그제서야 done/total이 확정된다). 두 소비자를 하나의 흐름으로
+  // 우겨넣는 대신, 같은 done/total 계산을 공유하는 별도 경로로 뒀다.
+  const runStep = (run) => {
+    const buffer = []
+    const before = done
+    const list = step(run({ ...ctx, log: (message) => buffer.push(message) }))
+    let n = before
+    for (const message of buffer) {
+      n++
+      say(`${counterTag(n, total)} ${message}`)
+    }
+    return list
+  }
+
+  // --adopt는 이미 있는 저장소를 기록 체계로 끌어오는 용도라 파일을 만들지
+  // 않는다. 설치기를 복사해 쓰던 저장소가 여기로 들어온다.
+  const results = adopt ? [] : [
+    ...runStep((c) => ensureDirs(root, manifest.dirs, c)),
+    ...runStep((c) => ensureFiles(root, manifest.files, c)),
+    ...runStep((c) => ensureJsonKeys(root, manifest.settings ?? [], c)),
+    ...runStep((c) => ensureBlocks(root, manifest.blocks, c)),
+  ]
+
+  if (!adopt) {
+    // 어댑터는 항목별로 실패를 격리한다 — 하나가 실패해도 나머지를 계속한다.
+    // update.mjs도 같은 격리를 써야 하므로 apply.mjs가 단일 출처다.
+    for (const entry of manifest.adapters) {
+      results.push(...runStep((c) => configureAdapterSafe(root, entry, { ...c, skillMode })))
+    }
+
+    results.push(...runStep((c) => ensureIgnore(root, manifest.ignore, c)))
+  }
+
+  // 기존 기록의 items·design은 보존한다 — 부트스트랩은 배선만 다루므로
+  // 사용자가 고른 설치 항목을 지울 권한이 없다. dry-run에서는 읽지 않는다:
+  // 깨진 기록이 "무엇이 바뀔지 확인"까지 막을 이유가 없다.
+  const previous = dryRun ? null : readRecord(root)
+  const record = {
+    ...emptyRecord({ skillMode }),
+    // 부트스트랩은 배선만 다룬다. 사용자가 고른 언어·항목을 지울 권한이 없다.
+    lang: previous?.lang ?? null,
+    items: previous?.items ?? [],
+    design: previous?.design ?? [],
+    managed: collectManaged(root, manifest),
+  }
+  results.push(...runStep((c) => writeRecord(root, record, c)))
+
+  // 실제 결과 수가 예측과 다르면 마지막 알림으로 100%를 맞춘다.
+  // 진행 바가 87%에서 끝나면 사용자는 무엇이 실패했다고 읽는다.
+  if (onProgress && done !== total) onProgress({ done: total, total, path: null })
+
+  const failed = results.filter((r) => !r.ok)
+  log('')
+  if (failed.length > 0) {
+    say(t('bootstrap.failures', { count: failed.length }))
+    for (const f of failed) say(`  ✖ ${f.path} — ${toText(t, f.message)}`)
+  }
+  say(t('bootstrap.done'))
+  say(t('bootstrap.sharedGuide'))
+  say(t('bootstrap.sharedSkills'))
+  say(t('bootstrap.tools', { list: manifest.tools.join(', ') }))
+  say(t('bootstrap.repoOnly'))
+  say(t('bootstrap.noOverwrite'))
+  say(t('bootstrap.record', { path: RECORD_REL }))
+
+  return { results, failed, record }
+}

package/lib/bootstrap/record.mjs

@@ -1,154 +1,154 @@
-// 저장소에 커밋되는 설치 기록.
-//
-// 이 파일은 "의도"다 — 실제 상태의 근거는 여전히 스캔이다. 기록이 더하는
-// 것은 재현성(팀원이 같은 결과를 얻는다)과 버전 고정, 그리고 "우리가 쓴
-// 그대로인가"를 판정할 해시다.
-//
-// 설치기 안의 manifest.mjs(무엇을 생성할지 선언)와 이름이 겹치지 않게
-// 저장소 쪽 파일은 '설치 기록'이라 부른다.
-//
-// 부트스트랩 그래프에 속하므로 node: 내장 모듈만 쓴다.
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname } from 'node:path'
-import { repoPath, repoPathStrict } from '../context.mjs'
-import { LOCALES, LocalizedError } from '../i18n/index.mjs'
-import { hashBody, normalizeBody } from './text.mjs'
-
-export const RECORD_REL = '.agent-kit/agent-setup.json'
-export const FORMAT_VERSION = 1
-
-// 발행된 패키지에도 package.json은 항상 들어간다(npm이 무조건 포함한다).
-// createRequire 대신 URL로 읽어 의존성 0을 유지한다.
-let cachedVersion
-export function toolVersion() {
-  if (!cachedVersion) {
-    const url = new URL('../../package.json', import.meta.url)
-    cachedVersion = JSON.parse(readFileSync(url, 'utf8')).version
-  }
-  return cachedVersion
-}
-
-export function emptyRecord({ skillMode = 'auto', lang = null } = {}) {
-  return {
-    formatVersion: FORMAT_VERSION,
-    pinnedVersion: toolVersion(),
-    skillMode,
-    lang,
-    items: [],
-    design: [],
-    managed: {},
-  }
-}
-
-// 없으면 null. 있으면 필드를 채워 돌려준다 — 손으로 편집해 필드가 빠져도
-// 죽지 않아야 한다. 형식 버전이 다르면 추측하지 않고 던진다.
-export function readRecord(root) {
-  const target = repoPath(root, RECORD_REL)
-  let text
-  try {
-    text = readFileSync(target, 'utf8')
-  } catch (err) {
-    if (err.code === 'ENOENT') return null
-    throw new LocalizedError('error.recordUnreadable', { path: RECORD_REL, code: err.code ?? err.message })
-  }
-
-  let parsed
-  try {
-    parsed = JSON.parse(text)
-  } catch (err) {
-    throw new LocalizedError('error.recordNotJson', { path: RECORD_REL, message: err.message })
-  }
-
-  if (parsed.formatVersion !== FORMAT_VERSION) {
-    throw new LocalizedError('error.recordVersion', { path: RECORD_REL, found: parsed.formatVersion, expected: FORMAT_VERSION })
-  }
-
-  return {
-    formatVersion: parsed.formatVersion,
-    pinnedVersion: parsed.pinnedVersion ?? null,
-    skillMode: parsed.skillMode ?? 'auto',
-    // 손으로 편집된 값 때문에 도구가 죽으면 안 된다. 모르는 값은 없는 것으로 본다.
-    lang: LOCALES.includes(parsed.lang) ? parsed.lang : null,
-    items: Array.isArray(parsed.items) ? parsed.items : [],
-    design: Array.isArray(parsed.design) ? parsed.design : [],
-    managed: parsed.managed && typeof parsed.managed === 'object' ? parsed.managed : {},
-  }
-}
-
-// pinnedVersion은 여기서 실행 중 버전으로 맞춘다 — 기록을 쓰는 명령만
-// 버전을 옮길 수 있어야 고정이 거짓말하지 않는다.
-//
-// log를 주면 t도 반드시 줘야 한다. 영어 리터럴 폴백을 두면 t를 빠뜨린
-// 호출부가 한국어 출력 한가운데에 영어 한 줄을 흘리면서도 아무 신호를 내지
-// 않는다 — update.mjs가 실제로 그렇게 새어 나갔다.
-export function writeRecord(root, record, { dryRun = false, log, t } = {}) {
-  const target = repoPathStrict(root, RECORD_REL)
-  const body = `${JSON.stringify({ ...record, pinnedVersion: toolVersion() }, null, 2)}\n`
-  log?.(t('log.record.write', { path: RECORD_REL }))
-  if (!dryRun) {
-    mkdirSync(dirname(target), { recursive: true })
-    writeFileSync(target, body, { encoding: 'utf8' })
-  }
-  return { ok: true, action: dryRun ? 'skip' : 'write', path: RECORD_REL }
-}
-
-// 언어만 바꾼다. 기록이 없으면 만든다 — 부트스트랩 전에 언어를 골라도
-// 유지되어야 하기 때문이다. 나머지 필드는 있는 그대로 옮긴다.
-export function writeLang(root, lang, { dryRun = false, log, t } = {}) {
-  const previous = readRecord(root)
-  return writeRecord(root, { ...(previous ?? emptyRecord()), lang }, { dryRun, log, t })
-}
-
-// 마커는 apply.mjs의 ensureBlocks(생성)와 updateBlocks(갱신), 그리고 여기의
-// extractBlock(판정)이 함께 쓴다. 정의가 둘로 갈리면 한쪽만 고치는 회귀가
-// 생기므로 이 모듈이 단일 출처가 되고 apply.mjs가 import한다.
-export const BEGIN_MARKER = '<!-- agent-kit:begin -->'
-export const END_MARKER = '<!-- agent-kit:end -->'
-
-// 블록은 파일 전체가 아니라 마커 사이 본문만 관리 대상이다. 파일 전체 해시와
-// 섞이지 않게 키에 접미사를 붙인다.
-export const BLOCK_SUFFIX = '#agent-kit'
-
-export function managedKey(rel, isBlock) {
-  return isBlock ? `${rel}${BLOCK_SUFFIX}` : rel
-}
-
-// 마커 사이 본문을 정규화해 돌려준다. 마커가 없거나 순서가 뒤집혀 있으면 null.
-export function extractBlock(text) {
-  const begin = text.indexOf(BEGIN_MARKER)
-  if (begin === -1) return null
-  const end = text.indexOf(END_MARKER, begin + BEGIN_MARKER.length)
-  if (end === -1) return null
-  return normalizeBody(text.slice(begin + BEGIN_MARKER.length, end))
-}
-
-function readOrNull(root, rel) {
-  try {
-    return readFileSync(repoPath(root, rel), 'utf8')
-  } catch {
-    return null
-  }
-}
-
-// 채택 규칙: 현재 내용이 이 버전의 템플릿과 정규화 후 일치하는 것만 해시를
-// 남긴다. 그러지 않으면 사용자가 이미 고쳐 둔 파일이 "우리가 쓴 그대로"로
-// 위장되어 다음 update에 날아간다. 값이 null인 키는 update가 절대 덮어쓰지
-// 않으며, 없는 파일도 키를 남겨 update의 생성 분기가 집어간다.
-export function collectManaged(root, manifest) {
-  const managed = {}
-
-  for (const { path: rel, template } of manifest.files ?? []) {
-    const text = readOrNull(root, rel)
-    const wanted = hashBody(template)
-    managed[rel] = text !== null && hashBody(text) === wanted ? wanted : null
-  }
-
-  for (const { path: rel, block } of manifest.blocks ?? []) {
-    const text = readOrNull(root, rel)
-    const wanted = hashBody(extractBlock(block) ?? block)
-    const current = text === null ? null : extractBlock(text)
-    managed[managedKey(rel, true)] = current !== null && hashBody(current) === wanted ? wanted : null
-  }
-
-  return managed
-}
+// 저장소에 커밋되는 설치 기록.
+//
+// 이 파일은 "의도"다 — 실제 상태의 근거는 여전히 스캔이다. 기록이 더하는
+// 것은 재현성(팀원이 같은 결과를 얻는다)과 버전 고정, 그리고 "우리가 쓴
+// 그대로인가"를 판정할 해시다.
+//
+// 설치기 안의 manifest.mjs(무엇을 생성할지 선언)와 이름이 겹치지 않게
+// 저장소 쪽 파일은 '설치 기록'이라 부른다.
+//
+// 부트스트랩 그래프에 속하므로 node: 내장 모듈만 쓴다.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { repoPath, repoPathStrict } from '../context.mjs'
+import { LOCALES, LocalizedError } from '../i18n/index.mjs'
+import { hashBody, normalizeBody } from './text.mjs'
+
+export const RECORD_REL = '.agent-kit/agent-setup.json'
+export const FORMAT_VERSION = 1
+
+// 발행된 패키지에도 package.json은 항상 들어간다(npm이 무조건 포함한다).
+// createRequire 대신 URL로 읽어 의존성 0을 유지한다.
+let cachedVersion
+export function toolVersion() {
+  if (!cachedVersion) {
+    const url = new URL('../../package.json', import.meta.url)
+    cachedVersion = JSON.parse(readFileSync(url, 'utf8')).version
+  }
+  return cachedVersion
+}
+
+export function emptyRecord({ skillMode = 'auto', lang = null } = {}) {
+  return {
+    formatVersion: FORMAT_VERSION,
+    pinnedVersion: toolVersion(),
+    skillMode,
+    lang,
+    items: [],
+    design: [],
+    managed: {},
+  }
+}
+
+// 없으면 null. 있으면 필드를 채워 돌려준다 — 손으로 편집해 필드가 빠져도
+// 죽지 않아야 한다. 형식 버전이 다르면 추측하지 않고 던진다.
+export function readRecord(root) {
+  const target = repoPath(root, RECORD_REL)
+  let text
+  try {
+    text = readFileSync(target, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return null
+    throw new LocalizedError('error.recordUnreadable', { path: RECORD_REL, code: err.code ?? err.message })
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch (err) {
+    throw new LocalizedError('error.recordNotJson', { path: RECORD_REL, message: err.message })
+  }
+
+  if (parsed.formatVersion !== FORMAT_VERSION) {
+    throw new LocalizedError('error.recordVersion', { path: RECORD_REL, found: parsed.formatVersion, expected: FORMAT_VERSION })
+  }
+
+  return {
+    formatVersion: parsed.formatVersion,
+    pinnedVersion: parsed.pinnedVersion ?? null,
+    skillMode: parsed.skillMode ?? 'auto',
+    // 손으로 편집된 값 때문에 도구가 죽으면 안 된다. 모르는 값은 없는 것으로 본다.
+    lang: LOCALES.includes(parsed.lang) ? parsed.lang : null,
+    items: Array.isArray(parsed.items) ? parsed.items : [],
+    design: Array.isArray(parsed.design) ? parsed.design : [],
+    managed: parsed.managed && typeof parsed.managed === 'object' ? parsed.managed : {},
+  }
+}
+
+// pinnedVersion은 여기서 실행 중 버전으로 맞춘다 — 기록을 쓰는 명령만
+// 버전을 옮길 수 있어야 고정이 거짓말하지 않는다.
+//
+// log를 주면 t도 반드시 줘야 한다. 영어 리터럴 폴백을 두면 t를 빠뜨린
+// 호출부가 한국어 출력 한가운데에 영어 한 줄을 흘리면서도 아무 신호를 내지
+// 않는다 — update.mjs가 실제로 그렇게 새어 나갔다.
+export function writeRecord(root, record, { dryRun = false, log, t } = {}) {
+  const target = repoPathStrict(root, RECORD_REL)
+  const body = `${JSON.stringify({ ...record, pinnedVersion: toolVersion() }, null, 2)}\n`
+  log?.(t('log.record.write', { path: RECORD_REL }))
+  if (!dryRun) {
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, body, { encoding: 'utf8' })
+  }
+  return { ok: true, action: dryRun ? 'skip' : 'write', path: RECORD_REL }
+}
+
+// 언어만 바꾼다. 기록이 없으면 만든다 — 부트스트랩 전에 언어를 골라도
+// 유지되어야 하기 때문이다. 나머지 필드는 있는 그대로 옮긴다.
+export function writeLang(root, lang, { dryRun = false, log, t } = {}) {
+  const previous = readRecord(root)
+  return writeRecord(root, { ...(previous ?? emptyRecord()), lang }, { dryRun, log, t })
+}
+
+// 마커는 apply.mjs의 ensureBlocks(생성)와 updateBlocks(갱신), 그리고 여기의
+// extractBlock(판정)이 함께 쓴다. 정의가 둘로 갈리면 한쪽만 고치는 회귀가
+// 생기므로 이 모듈이 단일 출처가 되고 apply.mjs가 import한다.
+export const BEGIN_MARKER = '<!-- agent-kit:begin -->'
+export const END_MARKER = '<!-- agent-kit:end -->'
+
+// 블록은 파일 전체가 아니라 마커 사이 본문만 관리 대상이다. 파일 전체 해시와
+// 섞이지 않게 키에 접미사를 붙인다.
+export const BLOCK_SUFFIX = '#agent-kit'
+
+export function managedKey(rel, isBlock) {
+  return isBlock ? `${rel}${BLOCK_SUFFIX}` : rel
+}
+
+// 마커 사이 본문을 정규화해 돌려준다. 마커가 없거나 순서가 뒤집혀 있으면 null.
+export function extractBlock(text) {
+  const begin = text.indexOf(BEGIN_MARKER)
+  if (begin === -1) return null
+  const end = text.indexOf(END_MARKER, begin + BEGIN_MARKER.length)
+  if (end === -1) return null
+  return normalizeBody(text.slice(begin + BEGIN_MARKER.length, end))
+}
+
+function readOrNull(root, rel) {
+  try {
+    return readFileSync(repoPath(root, rel), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+// 채택 규칙: 현재 내용이 이 버전의 템플릿과 정규화 후 일치하는 것만 해시를
+// 남긴다. 그러지 않으면 사용자가 이미 고쳐 둔 파일이 "우리가 쓴 그대로"로
+// 위장되어 다음 update에 날아간다. 값이 null인 키는 update가 절대 덮어쓰지
+// 않으며, 없는 파일도 키를 남겨 update의 생성 분기가 집어간다.
+export function collectManaged(root, manifest) {
+  const managed = {}
+
+  for (const { path: rel, template } of manifest.files ?? []) {
+    const text = readOrNull(root, rel)
+    const wanted = hashBody(template)
+    managed[rel] = text !== null && hashBody(text) === wanted ? wanted : null
+  }
+
+  for (const { path: rel, block } of manifest.blocks ?? []) {
+    const text = readOrNull(root, rel)
+    const wanted = hashBody(extractBlock(block) ?? block)
+    const current = text === null ? null : extractBlock(text)
+    managed[managedKey(rel, true)] = current !== null && hashBody(current) === wanted ? wanted : null
+  }
+
+  return managed
+}