@rch4com/agent-setup 1.1.0 → 1.3.0

package/lib/bootstrap/flow.mjs

@@ -1,70 +1,73 @@
-// 부트스트랩 진입점 — 순서와 보고만 담당한다.
-// 무엇을 만들지는 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'
-
-const SKILL_MODES = ['auto', 'link', 'copy']
-
-export function runBootstrap(root, opts = {}) {
-  const { dryRun = false, skillMode = 'auto', adopt = false, log = console.log, manifest = MANIFEST } = opts
-
-  if (!SKILL_MODES.includes(skillMode)) {
-    throw new Error(`--skill-mode는 ${SKILL_MODES.join(', ')} 중 하나여야 합니다: ${skillMode}`)
-  }
-
-  const say = (message) => log(`[agent-setup] ${message}`)
-  const ctx = { dryRun, log: say }
-
-  say(`저장소 루트: ${root}`)
-  say('글로벌 설정 경로는 읽거나 수정하지 않습니다.')
-
-  // --adopt는 이미 있는 저장소를 기록 체계로 끌어오는 용도라 파일을 만들지
-  // 않는다. 설치기를 복사해 쓰던 저장소가 여기로 들어온다.
-  const results = adopt ? [] : [
-    ...ensureDirs(root, manifest.dirs, ctx),
-    ...ensureFiles(root, manifest.files, ctx),
-    ...ensureJsonKeys(root, manifest.settings ?? [], ctx),
-    ...ensureBlocks(root, manifest.blocks, ctx),
-  ]
-
-  if (!adopt) {
-    // 어댑터는 항목별로 실패를 격리한다 — 하나가 실패해도 나머지를 계속한다.
-    // update.mjs도 같은 격리를 써야 하므로 apply.mjs가 단일 출처다.
-    for (const entry of manifest.adapters) {
-      results.push(configureAdapterSafe(root, entry, { ...ctx, skillMode }))
-    }
-
-    results.push(...ensureIgnore(root, manifest.ignore, ctx))
-  }
-
-  // 기존 기록의 items·design은 보존한다 — 부트스트랩은 배선만 다루므로
-  // 사용자가 고른 설치 항목을 지울 권한이 없다. dry-run에서는 읽지 않는다:
-  // 깨진 기록이 "무엇이 바뀔지 확인"까지 막을 이유가 없다.
-  const previous = dryRun ? null : readRecord(root)
-  const record = {
-    ...emptyRecord({ skillMode }),
-    items: previous?.items ?? [],
-    design: previous?.design ?? [],
-    managed: collectManaged(root, manifest),
-  }
-  results.push(writeRecord(root, record, ctx))
-
-  const failed = results.filter((r) => !r.ok)
-  log('')
-  if (failed.length > 0) {
-    say(`실패 ${failed.length}건:`)
-    for (const f of failed) say(`  ✖ ${f.path} — ${f.message}`)
-  }
-  say('완료되었습니다.')
-  say('공통 지침: AGENTS.md')
-  say('공통 스킬: .agents/skills/')
-  say(`적용 도구: ${manifest.tools.join(', ')}`)
-  say('도구별 설정은 모두 현재 저장소 안에만 생성되었습니다.')
-  say('기존 설정 파일은 덮어쓰지 않았습니다.')
-  say(`설치 기록: ${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'
+
+const SKILL_MODES = ['auto', 'link', 'copy']
+
+export function runBootstrap(root, opts = {}) {
+  const { dryRun = false, skillMode = 'auto', adopt = false, log = console.log, manifest = MANIFEST, 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는 이미 있는 저장소를 기록 체계로 끌어오는 용도라 파일을 만들지
+  // 않는다. 설치기를 복사해 쓰던 저장소가 여기로 들어온다.
+  const results = adopt ? [] : [
+    ...ensureDirs(root, manifest.dirs, ctx),
+    ...ensureFiles(root, manifest.files, ctx),
+    ...ensureJsonKeys(root, manifest.settings ?? [], ctx),
+    ...ensureBlocks(root, manifest.blocks, ctx),
+  ]
+
+  if (!adopt) {
+    // 어댑터는 항목별로 실패를 격리한다 — 하나가 실패해도 나머지를 계속한다.
+    // update.mjs도 같은 격리를 써야 하므로 apply.mjs가 단일 출처다.
+    for (const entry of manifest.adapters) {
+      results.push(configureAdapterSafe(root, entry, { ...ctx, skillMode }))
+    }
+
+    results.push(...ensureIgnore(root, manifest.ignore, ctx))
+  }
+
+  // 기존 기록의 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(writeRecord(root, record, ctx))
+
+  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,142 +1,154 @@
-// 저장소에 커밋되는 설치 기록.
-//
-// 이 파일은 "의도"다 — 실제 상태의 근거는 여전히 스캔이다. 기록이 더하는
-// 것은 재현성(팀원이 같은 결과를 얻는다)과 버전 고정, 그리고 "우리가 쓴
-// 그대로인가"를 판정할 해시다.
-//
-// 설치기 안의 manifest.mjs(무엇을 생성할지 선언)와 이름이 겹치지 않게
-// 저장소 쪽 파일은 '설치 기록'이라 부른다.
-//
-// 부트스트랩 그래프에 속하므로 node: 내장 모듈만 쓴다.
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname } from 'node:path'
-import { repoPath, repoPathStrict } from '../context.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' } = {}) {
-  return {
-    formatVersion: FORMAT_VERSION,
-    pinnedVersion: toolVersion(),
-    skillMode,
-    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 Error(`${RECORD_REL}을 읽을 수 없습니다 (${err.code ?? err.message})`)
-  }
-
-  let parsed
-  try {
-    parsed = JSON.parse(text)
-  } catch (err) {
-    throw new Error(`${RECORD_REL}을 읽을 수 없습니다 — JSON이 아닙니다 (${err.message})`)
-  }
-
-  if (parsed.formatVersion !== FORMAT_VERSION) {
-    throw new Error(
-      `${RECORD_REL}의 형식 버전이 ${parsed.formatVersion}입니다. ` +
-      `이 도구는 ${FORMAT_VERSION}을 씁니다 — 도구를 올리거나 기록을 다시 만드세요.`,
-    )
-  }
-
-  return {
-    formatVersion: parsed.formatVersion,
-    pinnedVersion: parsed.pinnedVersion ?? null,
-    skillMode: parsed.skillMode ?? 'auto',
-    items: Array.isArray(parsed.items) ? parsed.items : [],
-    design: Array.isArray(parsed.design) ? parsed.design : [],
-    managed: parsed.managed && typeof parsed.managed === 'object' ? parsed.managed : {},
-  }
-}
-
-// pinnedVersion은 여기서 실행 중 버전으로 맞춘다 — 기록을 쓰는 명령만
-// 버전을 옮길 수 있어야 고정이 거짓말하지 않는다.
-export function writeRecord(root, record, { dryRun = false, log } = {}) {
-  const target = repoPathStrict(root, RECORD_REL)
-  const body = `${JSON.stringify({ ...record, pinnedVersion: toolVersion() }, null, 2)}\n`
-  log?.(`설치 기록 기록: ${RECORD_REL}`)
-  if (!dryRun) {
-    mkdirSync(dirname(target), { recursive: true })
-    writeFileSync(target, body, { encoding: 'utf8' })
-  }
-  return { ok: true, action: dryRun ? 'skip' : 'write', path: RECORD_REL }
-}
-
-// 마커는 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
+}