@rch4com/agent-setup 1.19.0 → 1.20.0

package/install.mjs

@@ -125,7 +125,11 @@ async function main() {
   // 살아남는다. 조용히 되돌아가는 대신 화면이 그 사실을 알리게 한다.
   const localeForced = isLocaleForced({ flag, env: process.env })
 
-  if (root === null) throw new LocalizedError('error.notGitRepo')
+  // 도움말은 저장소가 필요 없다. 이 검사를 먼저 하면 `--help`가 Git 저장소
+  // 밖에서 "Run this inside a Git repository"로 죽는다 — 사용법을 보려는
+  // 사람에게 그 오류를 내밀 이유가 없다.
+  const wantsHelp = argv.includes('-h') || argv.includes('--help')
+  if (root === null && !wantsHelp) throw new LocalizedError('error.notGitRepo')
 
   if (argv[0] === 'bootstrap') {
     const opts = parseBootstrapArgs(argv.slice(1), t)
@@ -140,7 +144,8 @@ async function main() {
     if (opts.help) { console.log(updateUsage(t)); return }
     // 항목 수렴을 위해 스캔이 필요해 의존성 있는 모듈에 닿는다.
     const { runUpdate } = await withDeps(() => import('./lib/update.mjs'), t)
-    await runUpdate(root, { ...opts, t })
+    const { failed } = await runUpdate(root, { ...opts, t })
+    if (failed.length > 0) process.exitCode = 1
     return
   }
 

package/lib/catalog.mjs

@@ -67,6 +67,12 @@ const execFileAsync = promisify(execFile)
 // 보고된다. 호출부가 opts.timeout으로 바꿀 수 있다.
 export const EXEC_TIMEOUT_MS = 10 * 60 * 1000
 
+// 자식 출력의 상한. execFile 기본값(1MB)을 넘기면 Node가 자식을 **죽이고**
+// "maxBuffer length exceeded"로 실패시킨다 — gsd(3,500파일)·hallmark
+// (references 100개 이상)처럼 파일마다 한 줄씩 찍는 설치가 반쯤 깔린 채
+// 실패로 보고됐다. 64MB면 어떤 설치 로그도 넉넉히 담긴다.
+export const EXEC_MAX_BUFFER = 64 * 1024 * 1024
+
 // 비동기다. 동기 실행은 이벤트 루프를 통째로 막아, npx가 도는 수십 초 동안
 // 진행 화면을 한 번도 다시 그릴 수 없었다. 반환 형태({ ok, output })는
 // 그대로라 호출부는 await만 더하면 된다.
@@ -91,6 +97,7 @@ export function makeExec(dryRun, log = console.log, t = null) {
       const p = execFileAsync(file, fileArgs, {
         encoding: 'utf8',
         timeout: EXEC_TIMEOUT_MS,
+        maxBuffer: EXEC_MAX_BUFFER,
         ...opts,
         shell,
       })

package/lib/i18n/catalog/en.mjs

@@ -150,6 +150,7 @@ export default {
   'log.record.write': 'install record written: {path}',
   'error.recordUnreadable': 'Cannot read {path} ({code})',
   'error.recordNotJson': 'Cannot read {path} — not JSON ({message})',
+  'error.jsonInvalid': 'Cannot read {path} — invalid JSON: {message}. Fix the file by hand; nothing was written.',
   'error.recordVersion': '{path} has format version {found}. This tool uses {expected} — upgrade the tool or recreate the record.',
 
   'log.repoRoot': 'repository root: {path}',

package/lib/i18n/catalog/ko.mjs

@@ -144,6 +144,7 @@ export default {
   'log.record.write': '설치 기록 기록: {path}',
   'error.recordUnreadable': '{path}을 읽을 수 없습니다 ({code})',
   'error.recordNotJson': '{path}을 읽을 수 없습니다 — JSON이 아닙니다 ({message})',
+  'error.jsonInvalid': '{path}을 읽을 수 없습니다 — JSON이 깨져 있습니다: {message}. 파일을 손으로 고치세요. 아무것도 쓰지 않았습니다.',
   'error.recordVersion': '{path}의 형식 버전이 {found}입니다. 이 도구는 {expected}을 씁니다 — 도구를 올리거나 기록을 다시 만드세요.',
 
   'log.repoRoot': '저장소 루트: {path}',

package/lib/jsonfile.mjs

@@ -1,22 +1,41 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
 import { dirname } from 'node:path'
-import { parse, modify, applyEdits } from 'jsonc-parser'
+import { parse, modify, applyEdits, printParseErrorCode } from 'jsonc-parser'
+import { LocalizedError } from './i18n/index.mjs'
 
 const FORMAT = { formattingOptions: { insertSpaces: true, tabSize: 2 } }
+// 이 파일들은 도구가 읽는 JSONC다 — 주석과 후행 콤마는 정상이다.
+const PARSE = { allowTrailingComma: true }
 
 function readText(file) {
   return existsSync(file) ? readFileSync(file, 'utf8') : ''
 }
 
+// jsonc-parser의 parse는 던지지 않는다 — 닫는 괄호가 빠진 파일도 "복구한"
+// 값을 돌려준다. 그대로 두면 깨진 파일에 키를 끼워 넣고 has()는 설치됨으로
+// 읽어, 사용자는 파일이 깨진 것을 끝까지 모른다. 오류 목록을 받아 하나라도
+// 있으면 record.mjs의 readRecord처럼 어느 파일이 왜 깨졌는지 말하며 던진다.
+function parseStrict(text, file) {
+  const errors = []
+  const data = parse(text, errors, PARSE)
+  if (errors.length > 0) {
+    const [first] = errors
+    const line = text.slice(0, first.offset).split('\n').length
+    throw new LocalizedError('error.jsonInvalid', { path: file, message: `${printParseErrorCode(first.error)} (line ${line})` })
+  }
+  return data
+}
+
 export function readJson(file) {
   const text = readText(file)
   if (!text.trim()) return undefined
-  return parse(text)
+  return parseStrict(text, file)
 }
 
 export function setKey(file, path, value) {
   let text = readText(file)
   if (!text.trim()) text = '{}\n'
+  else parseStrict(text, file)
   const edits = modify(text, path, value, FORMAT)
   mkdirSync(dirname(file), { recursive: true })
   writeFileSync(file, applyEdits(text, edits))
@@ -25,7 +44,7 @@ export function setKey(file, path, value) {
 export function removeKey(file, path) {
   const text = readText(file)
   if (!text.trim()) return
-  if (getIn(parse(text), path) === undefined) return
+  if (getIn(parseStrict(text, file), path) === undefined) return
   const edits = modify(text, path, undefined, FORMAT)
   writeFileSync(file, applyEdits(text, edits))
 }

package/lib/status.mjs

@@ -103,9 +103,27 @@ export function formatStatus(report, t = createT('en')) {
   return lines.join('\n')
 }
 
-export async function runStatus(root, { json = false, log = console.log, t = createT('en') } = {}) {
+// 레지스트리의 최신 발행 버전. status는 진단 명령이라 네트워크가 없거나
+// 느려도 죽으면 안 된다 — 어떤 실패든 null로 떨어뜨리고 화면은 "최신"
+// 자리만 비운다. 시간 제한은 짧게 둔다: 이 한 줄 때문에 status가 20초를
+// 기다리면 진단 도구가 아니다.
+export const LATEST_TIMEOUT_MS = 5000
+const LATEST_URL = 'https://registry.npmjs.org/@rch4com%2Fagent-setup/latest'
+
+export async function fetchLatestVersion(fetchImpl = fetch) {
+  try {
+    const res = await fetchImpl(LATEST_URL, { signal: AbortSignal.timeout(LATEST_TIMEOUT_MS) })
+    if (!res.ok) return null
+    const version = (await res.json())?.version
+    return typeof version === 'string' && version ? version : null
+  } catch {
+    return null
+  }
+}
+
+export async function runStatus(root, { json = false, log = console.log, fetchImpl = fetch, t = createT('en') } = {}) {
   const { loadItems } = await import('./catalog.mjs')
-  const report = await collectStatus(root, { items: await loadItems() })
+  const report = await collectStatus(root, { items: await loadItems(), latest: await fetchLatestVersion(fetchImpl) })
   log(json ? JSON.stringify(report, null, 2) : formatStatus(report, t))
   return report
 }

package/lib/update.mjs

@@ -11,9 +11,11 @@ import { RECORD_REL, managedKey, readRecord, toolVersion, writeRecord } from './
 import { LocalizedError, createT, toText } from './i18n/index.mjs'
 
 // git이 유일한 되돌리기 수단이다. 커밋되지 않은 변경 위에 덮어쓰면 사용자가
-// 잃은 것을 복구할 방법이 없다.
+// 잃은 것을 복구할 방법이 없다. 추적되지 않는 파일은 세지 않는다 — 갱신
+// 대상은 기록에 해시가 있는 추적 파일뿐이라, 스크래치 파일 하나가 --force를
+// 막을 이유가 없다.
 function assertCleanWorktree(root) {
-  const out = execFileSync('git', ['-C', root, 'status', '--porcelain'], { encoding: 'utf8' })
+  const out = execFileSync('git', ['-C', root, 'status', '--porcelain', '--untracked-files=no'], { encoding: 'utf8' })
   if (out.trim()) {
     throw new LocalizedError('error.forceNeedsCleanTree')
   }
@@ -65,10 +67,18 @@ export async function runUpdate(root, opts = {}) {
   const drift = results.filter((r) => r.action === 'drift')
   const updated = results.filter((r) => r.action === 'update')
   const created = results.filter((r) => r.action === 'create')
+  // 어댑터가 격리해 돌려준 실패다. 요약이 갱신·신규·드리프트만 세면 이
+  // 결과는 아무 데도 나오지 않고 종료 코드도 0이라, 링크가 끊긴 채 "갱신
+  // 0건"으로 끝난다. flow.mjs의 bootstrap과 같은 형식으로 보고한다.
+  const failed = results.filter((r) => !r.ok)
 
   if (!dryRun) writeRecord(root, { ...record, managed }, { dryRun, log: say, t })
 
   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('update.summary', { updated: updated.length, created: created.length, drift: drift.length }))
   if (drift.length > 0) {
     say(t('update.driftHeader'))
@@ -81,5 +91,5 @@ export async function runUpdate(root, opts = {}) {
     say(t('update.driftHint'))
   }
 
-  return { results, drift, record: { ...record, managed } }
+  return { results, drift, failed, record: { ...record, managed } }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rch4com/agent-setup",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "Repository-scoped bootstrap and optional-item installer for using multiple coding-agent CLIs in one repository | 여러 코딩 에이전트 CLI를 한 저장소에서 함께 쓰기 위한 저장소 범위 부트스트랩과 선택 항목 설치기",
   "keywords": [
     "agents-md",