@rch4com/agent-setup 1.6.0 → 1.8.0

package/install.mjs

@@ -51,7 +51,7 @@ async function openTui(root, { dryRun, skillMode, designDirs, t, localeForced })
 // --list / --set 전용 비대화형 경로.
 async function runClassic(root, { dryRun, listOnly, setArg, t }) {
   const { loadItems } = await withDeps(() => import('./lib/catalog.mjs'), t)
-  const { scan, planChanges, apply } = await withDeps(() => import('./lib/engine.mjs'), t)
+  const { scan, planChanges, apply, assertExclusive } = await withDeps(() => import('./lib/engine.mjs'), t)
   const { plainLine } = await withDeps(() => import('./lib/tui/progress.mjs'), t)
   const items = await loadItems()
   const states = await scan(root, items)
@@ -68,6 +68,7 @@ async function runClassic(root, { dryRun, listOnly, setArg, t }) {
   const selectedIds = new Set(setArg.split(',').map((s) => s.trim()).filter(Boolean))
   const known = new Set(items.map((i) => i.id))
   for (const id of selectedIds) if (!known.has(id)) throw new LocalizedError('error.unknownItem', { id })
+  assertExclusive(items, selectedIds)
 
   const changes = planChanges(states, selectedIds)
   if (changes.length === 0) { console.log(t('apply.noChanges')); return }

package/lib/engine.mjs

@@ -1,5 +1,5 @@
 import { makeExec } from './catalog.mjs'
-import { createT, msg } from './i18n/index.mjs'
+import { createT, LocalizedError, msg } from './i18n/index.mjs'
 
 export async function scan(root, items) {
   const states = []
@@ -14,6 +14,21 @@ export async function scan(root, items) {
   return states
 }
 
+// item.exclusive는 "이 항목들은 같은 파일 하나를 두고 다툰다"는 표시다.
+// TUI는 고르는 순간에 배타를 지키지만(state.mjs), --set은 목록을 통째로 받는다 —
+// 둘을 함께 주면 나중 항목이 앞선 항목을 덮어써 성공한 것처럼 끝난다.
+// 조용히 하나를 고르는 대신 어느 쪽을 원했는지 되묻는다.
+export function assertExclusive(items, selectedIds) {
+  const groups = new Map()
+  for (const item of items) {
+    if (!item.exclusive || !selectedIds.has(item.id)) continue
+    groups.set(item.exclusive, [...(groups.get(item.exclusive) ?? []), item.id])
+  }
+  for (const ids of groups.values()) {
+    if (ids.length > 1) throw new LocalizedError('error.exclusiveItems', { ids: ids.join(', ') })
+  }
+}
+
 export function planChanges(states, selectedIds) {
   const changes = []
   for (const { item, status } of states) {

package/lib/gitmessage.mjs

@@ -0,0 +1,230 @@
+// 커밋 메시지 템플릿(.gitmessage.txt) 항목의 단일 출처.
+//
+// 한 파일에 언어가 다른 두 판이 있다 — 그래서 항목도 둘이지만 대상 파일은
+// 하나다. 둘을 동시에 고를 수 없게 하는 것은 TUI(state.mjs)와 --set
+// (engine.mjs의 assertExclusive)이 exclusive 키로 맡는다. 여기서는 "내가 쓴
+// 판이 지금 놓여 있는가"만 판정하고, 아니면 아무것도 건드리지 않는다.
+//
+// 항목 파일(lib/items/*.mjs)에 두지 않는 이유: loadItems가 그 디렉터리의
+// 모든 .mjs를 항목으로 읽어 검증하므로, 보조 모듈이 하나라도 섞이면 로드가
+// 통째로 실패한다.
+import { execFileSync } from 'node:child_process'
+import { readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { normalizeBody } from './bootstrap/text.mjs'
+import { repoPath, repoPathStrict } from './context.mjs'
+import { LocalizedError, msg } from './i18n/index.mjs'
+
+export const GITMESSAGE_REL = '.gitmessage.txt'
+// 한 파일을 두고 다투는 항목들의 묶음 이름.
+export const GITMESSAGE_EXCLUSIVE = 'gitmessage'
+
+const CONFIG_KEY = 'commit.template'
+
+// 이 저장소 루트의 .gitmessage.txt와 같은 내용이다 —
+// test/items.gitmessage.test.mjs가 두 값이 갈리지 않게 고정한다.
+export const GITMESSAGE_KO = `# Commit message template ( * 주석 처리(#)된 부분들은 커밋 메시지에 포함되지 않으니 참고해서 작성)
+# <타입(<영역>)>: <주제>
+#  - 타입은 필수 작성. 해당 커밋의 성격을 나타내며 타입의 종류 중 하나만 선택, 영어 소문자로 시작
+#  - 영역은 필요 시 작성. 변경된 부분을 직접적으로 나타냄 ex) refactor(MemberService): loginMember 메소드 명을 login으로 수정
+#  - 주제는 필수 작성. 최대 50글자까지, 끝에 마침표 금지, 한글로 간단 명료하게 작성, 현재형 사용
+# 바로 밑줄에 작성
+
+# 바로 아래 한 줄 공백 유지 (타입 본문의 분리를 위함)
+
+################################
+# <본문> - 필요시 작성. 한 줄당 최대 72자까지, 72자 초과시 줄바꿈, ”왜”, “무엇을 위해” 작업했는지에 초점을 맞춰 작성
+# 바로 밑줄에 작성
+
+# 바로 아래 한 줄 공백 유지 (본문과 바닥글의 분리를 위함)
+
+################################
+# <바닥글> - 필요시 작성
+# 바로 밑줄에 작성 (이슈 해결 시에는 resolve: #99와 같이 작성)
+
+######## [타입 리스트] ############
+# feat: 새로운 기능 추가
+# fix: 버그 수정
+# style: 코드의 의미에 영향을 주지 않는 변경 사항(공백, 형식 지정, 세미콜론 누락 등), 클래스명 수정&가독성을 위해 변수명을 변경한 경우도 포함
+# refactor: 버그 수정, 기능 추가도 아닌 코드 변경
+# chore: 소스코드의 변경이 없으며 나열된 타입 이외 간단 변경
+# add: feat 이외의 부수적인 코드, 라이브러리 등을 추가한 경우, 새로운 파일(Component나 Activity 등)을 생성한 경우도 포함
+# remove: 코드, 파일을 삭제한 경우, 필요 없는 주석 삭제도 포함
+# move: fix, refactor 등과 관계 없이 코드, 파일 등의 위치를 이동하는 작업만 수행한 경우
+# comment: 필요한 주석을 추가, 수정한 경우( * 필요 없는 주석을 삭제한 경우는 remove)
+# perf: 성능을 향상시키는 코드 변경
+# test: 테스트 코드를 추가, 수정, 삭제한 경우
+# docs: 문서를 추가, 수정한 경우
+# design: CSS 등 사용자 UI 디자인을 추가, 수정한 경우
+# revert: 이전 커밋을 되돌린 경우
+# !BREAKING CHANGE: 커다란 API 변경의 경우 (MAJOR 버전과 상관 관계)
+# !HOTFIX: 급하게 치명적인 버그를 고쳐야하는 경우
+######## [커밋 메시지 예시] #########
+# fix: 로그인 기능 구현
+#
+# 로그인 시 JWT 발급
+#
+# resolve: #232
+# ref: #122
+# related to: #30, #50
+# ------------------
+# [* 지켜야 할 보편적 규칙]
+#  1. 언어는 한국어를 사용한다.
+#    - 예외 사항) 최초 커밋 메시지는 “Initial commit”으로 한다.
+#  2. 문장의 구성
+#    1) 문장은 간결하게 구성한다.
+#    2) 현재형을 사용한다.
+#  3. 작성한 당사자가 아닌 제 3자가 이해할 수 있도록 작성한다.
+#  4. 단순한 문장일수록 좋다.
+# ------------------
+# [* 커밋 타이밍]
+#  - 의미 있는 코드의 변화가 있다면 커밋을 진행한다.
+#  - 의미가 있다면 사소한 것을 커밋 하는 것은 전혀 잘못된 것이 아니다.
+#  - 다만 의미 없는 잦은 커밋은 히스토리 추적에 불편함을 주므로 의미 없는 커밋은 자제한다.
+################################
+`
+
+// 한국어판을 줄 단위로 옮긴 것이다. 타입 목록과 구획선은 같은 자리에 둔다 —
+// 두 판을 오가도 커밋 히스토리의 모양이 달라지지 않아야 한다.
+export const GITMESSAGE_EN = `# Commit message template ( * Lines that start with # are comments and never reach the commit message)
+# <type(<scope>)>: <subject>
+#  - Type is required. It names the nature of this commit. Pick exactly one from the list below, lowercase English
+#  - Scope is optional. It points straight at what changed ex) refactor(MemberService): rename loginMember to login
+#  - Subject is required. 50 characters at most, no trailing period, plain and clear, present tense
+# Write it on the line right below
+
+# Keep one blank line right below (it separates the subject from the body)
+
+################################
+# <Body> - optional. 72 characters per line at most, wrap past that, focus on "why" and "what for"
+# Write it on the line right below
+
+# Keep one blank line right below (it separates the body from the footer)
+
+################################
+# <Footer> - optional
+# Write it on the line right below (for a resolved issue, write resolve: #99)
+
+######## [Type list] ############
+# feat: add a new feature
+# fix: fix a bug
+# style: changes that do not affect the meaning of the code (whitespace, formatting, missing semicolons), including class or variable renames made for readability
+# refactor: a code change that is neither a bug fix nor a new feature
+# chore: no source change; small changes outside the types listed here
+# add: supporting code, libraries and the like added outside feat, including brand new files (a Component, an Activity)
+# remove: code or files deleted, including the removal of comments that are no longer needed
+# move: only moving code or files around, unrelated to fix, refactor and the rest
+# comment: a needed comment added or reworded ( * deleting a comment that is not needed is remove)
+# perf: a code change that improves performance
+# test: test code added, changed or deleted
+# docs: documentation added or changed
+# design: user-facing UI design added or changed (CSS and the like)
+# revert: an earlier commit rolled back
+# !BREAKING CHANGE: a large API change (tied to the MAJOR version)
+# !HOTFIX: an urgent fix for a critical bug
+######## [Example commit message] #########
+# fix: implement the login feature
+#
+# Issue a JWT on login
+#
+# resolve: #232
+# ref: #122
+# related to: #30, #50
+# ------------------
+# [* Universal rules]
+#  1. Write in English.
+#    - Exception) the very first commit message of a repository is "Initial commit".
+#  2. Sentence shape
+#    1) Keep sentences short.
+#    2) Use the present tense.
+#  3. Write so that a third party, not only the author, can follow it.
+#  4. The simpler the sentence, the better.
+# ------------------
+# [* When to commit]
+#  - Commit whenever there is a meaningful change in the code.
+#  - Committing something small is not wrong at all as long as it means something.
+#  - Frequent meaningless commits make the history hard to follow, so hold those back.
+################################
+`
+
+export const GITMESSAGE_BODIES = [GITMESSAGE_EN, GITMESSAGE_KO].map(normalizeBody)
+
+function readCurrent(root) {
+  try {
+    return readFileSync(repoPath(root, GITMESSAGE_REL), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+// 저장소 설정만 본다. --local이 없으면 전역·시스템 설정까지 함께 읽혀,
+// 사용자가 ~/.gitconfig에 같은 값을 둔 것만으로 이 저장소가 설치된 것처럼
+// 보인다 — 이 도구는 저장소 안만 건드리므로 판정도 저장소 안만 봐야 한다.
+// 값이 없으면 git이 종료 코드 1로 끝나므로 예외가 곧 "설정 없음"이다.
+// git이 아예 없어도 같은 길로 떨어진다 — 그때는 상태 판정만 보수적으로
+// 흐를 뿐, 화면이 죽지는 않는다.
+function pointsHere(root) {
+  try {
+    const out = execFileSync('git', ['config', '--local', '--get', CONFIG_KEY], {
+      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return out.trim() === GITMESSAGE_REL
+  } catch {
+    return false
+  }
+}
+
+// supports를 두지 않는다. 이 항목은 CLI 배선이 아니라 저장소 규약이라
+// "10개 중 몇 개"라는 물음 자체가 성립하지 않는다 — 힌트의 커버리지 줄,
+// 상세 패널의 배선표, CLI 필터가 모두 supports 없는 항목을 건너뛴다.
+export function defineGitmessage({ id, label, body, note }) {
+  const wanted = normalizeBody(body)
+
+  return {
+    id,
+    category: 'config',
+    label,
+    scope: 'project',
+    group: '__commit',
+    exclusive: GITMESSAGE_EXCLUSIVE,
+    // 이 항목이 손대는 파일. 그룹 헤더가 없는 평평한 목록에서도 무엇이
+    // 놓이는지 보이고, '.gitmessage'로 검색해도 걸린다.
+    target: GITMESSAGE_REL,
+    unsupported: {},
+    note,
+
+    async detect({ root }) {
+      const current = readCurrent(root)
+      if (current === null || normalizeBody(current) !== wanted) return { status: 'absent' }
+      // 파일만 놓여 있고 git이 그것을 모르면 템플릿은 한 번도 뜨지 않는다.
+      // 설치됨으로 찍으면 "왜 안 뜨지"를 사용자가 혼자 풀어야 한다.
+      return pointsHere(root) ? { status: 'installed' } : { status: 'partial', detail: msg('item.gitmessage.unregistered') }
+    },
+
+    async install({ root, dryRun, exec, log = () => {}, t }) {
+      const current = readCurrent(root)
+      // 손으로 쓴 템플릿은 덮지 않는다 — 이 저장소의 다른 모든 쓰기가 지키는
+      // 규칙이다. 우리가 아는 두 판 사이를 오가는 것만 덮어쓰기로 본다.
+      if (current !== null && !GITMESSAGE_BODIES.includes(normalizeBody(current))) {
+        throw new LocalizedError('error.gitmessageForeign', { path: GITMESSAGE_REL })
+      }
+      if (dryRun) log(t('log.gitmessage.write', { path: GITMESSAGE_REL }))
+      else writeFileSync(repoPathStrict(root, GITMESSAGE_REL), wanted, { encoding: 'utf8' })
+
+      const r = await exec('git', ['config', '--local', CONFIG_KEY, GITMESSAGE_REL], { cwd: root })
+      if (!r.ok) throw new LocalizedError('error.gitmessageConfig', { output: r.output })
+    },
+
+    async uninstall({ root, dryRun, exec, log = () => {}, t }) {
+      const current = readCurrent(root)
+      // 같은 적용 안에서 다른 언어 판이 먼저 설치돼 파일을 갈아 끼웠을 수
+      // 있다(en 설치 → ko 제거 순서). 그때 지우면 방금 쓴 파일이 날아간다 —
+      // 내용이 내 판일 때만 손댄다.
+      if (current === null || normalizeBody(current) !== wanted) return
+      if (dryRun) log(t('log.gitmessage.remove', { path: GITMESSAGE_REL }))
+      else rmSync(repoPathStrict(root, GITMESSAGE_REL), { force: true })
+
+      // 남의 값이나 빈 값에 --unset을 걸면 git이 실패를 돌려준다.
+      if (pointsHere(root)) await exec('git', ['config', '--local', '--unset', CONFIG_KEY], { cwd: root })
+    },
+  }
+}

package/lib/i18n/catalog/en.mjs

@@ -261,6 +261,16 @@ export default {
   'item.skill.karpathy.note': 'behavioral guidelines that curb overbuilding and vague success criteria',
   'item.skill.gstack.note': 'repo-local clone + setup (needs bash; Git Bash on Windows). Runtime state (~/.gstack) may be created globally.',
   'item.skill.gsd.note': 'npx @opengsd/gsd-core, installed per project. Upstream supports 18 runtimes (Codex, Antigravity, …); this item wires --claude only',
+  // 커밋 템플릿은 CLI 배선이 아니라 저장소 규약이다 — note가 "무엇이 놓이고
+  // 무엇이 설정되는가"를 대신 말한다(상세 패널에 배선표가 없다).
+  'item.config.gitmessage.en.note': 'commit messages in English. Writes the template and points git commit.template at it, so it opens in every editor and every tool in this repository',
+  'item.config.gitmessage.ko.note': 'commit messages in Korean. Writes the template and points git commit.template at it, so it opens in every editor and every tool in this repository',
+  'item.gitmessage.unregistered': 'file is in place, but commit.template does not point at it yet',
+  'log.gitmessage.write': '  [dry-run] write {path}',
+  'log.gitmessage.remove': '  [dry-run] remove {path}',
+  'error.gitmessageForeign': '{path} already exists and was not written by this tool. A hand-written template is never overwritten — move or delete it first.',
+  'error.gitmessageConfig': 'git config commit.template failed: {output}',
+  'error.exclusiveItems': 'These items write the same file, so only one can be chosen: {ids}',
   'error.gstackClone': 'gstack clone failed: {output}',
   'error.gstackSetup': 'gstack setup failed: {output}',
   'error.gsdInstall': 'GSD install failed: {output}',
@@ -277,6 +287,7 @@ export default {
   'section.plugin': 'PLUGIN',
   'section.mcp': 'MCP',
   'section.skill': 'SKILL',
+  'section.config': 'CONFIG',
   'section.design': 'DESIGN.MD',
 
   // TUI 목록·검토 화면 문구. item.*는 agentHint가, action.*.label/hint는
@@ -289,9 +300,11 @@ export default {
   'tui.empty.none': '  Nothing here.',
   'tui.hint.search': 'type to search (spaces included)   ↓ to list   Tab tab   Esc clear   Ctrl+F CLI   Ctrl+D detail',
   'tui.hint.list': 'Space select   ↑↓ move (↑ at top = search)   Tab tab   Enter run/submit   Ctrl+A all   Ctrl+O preview   Ctrl+F CLI   Ctrl+D detail',
+  // 힌트 줄 오른쪽 끝의 고정 자리. 나머지 힌트가 다 잘려 나가도 이 자리는 남는다.
+  'tui.hint.quit': 'Ctrl+Q quit',
   'tui.review.title': 'Review — {count} change(s)',
   'tui.review.more': '  …and {count} more',
-  'tui.review.hint': 'Enter apply   Esc cancel',
+  'tui.review.hint': 'Enter apply   Esc cancel   Ctrl+Q quit',
   'tui.notItemRow': 'Press Enter to run this row.',
   'tui.noPreview': 'This item has no preview.',
   'tui.opened': 'Opened: {target}',
@@ -299,6 +312,8 @@ export default {
   'tui.submitCancelled': 'Submission cancelled.',
   'tui.toggledAll': 'Selected every visible item in the {tab} tab.',
   'tui.toggledNone': 'Cleared every visible item in the {tab} tab.',
+  // 배타 묶음에서 형제가 함께 꺼졌을 때. 조용히 뒤집히면 오조작으로 읽힌다.
+  'tui.exclusiveSwitched': 'Switched to {kept} — they share one file, so {dropped} was cleared.',
   'tui.nonInteractive': 'The interactive screen only opens in a terminal. --list and --set work too.',
   'tui.pressAnyKey': 'Press any key to continue…',
   'tui.confirmSuffix': ' [y/N] ',
@@ -332,6 +347,7 @@ export default {
   'tui.filter.empty': '  Nothing in this tab is wired for {cli}.',
 
   'item.location.user': 'installs to: user global',
+  'item.target': 'file: {path}',
   // 커버리지는 전부 지원할 때도 찍는다 — 표시가 없는 것과 "10/10"은 뜻이 다르다.
   'item.cliCoverage': 'CLI {covered}/{total}',
   'item.unsupportedList': 'not wired for {count}: {groups}',
@@ -340,6 +356,7 @@ export default {
   'detail.unwired': 'unwired',
   'detail.provider': 'source',
   'detail.preview': 'preview',
+  'detail.target': 'file',
   'detail.scope.project': 'repo scope',
   'detail.scope.user': 'user global',
   'detail.more': '  …and {count} more line(s) — Ctrl+D to expand',
@@ -366,6 +383,9 @@ export default {
   'category.context': 'Code understanding',
   'category.style': 'Design taste',
   'category.flow': 'Way of working',
+  // 헤더 하나가 "무엇을 고르는 자리이고 규칙이 무엇인가"를 함께 말한다 —
+  // 대상 파일이 하나뿐인 배타 묶음이라 라디오 표시와 짝이 된다.
+  'category.commit': 'Commit template · .gitmessage.txt · pick one',
   'category.service': 'External services',
   'design.localSuffix': '{id} (local)',
   'design.localTag': 'local',

package/lib/i18n/catalog/ko.mjs

@@ -254,6 +254,15 @@ export default {
   'item.skill.karpathy.note': '과설계와 모호한 완료 기준을 줄이는 행동 지침',
   'item.skill.gstack.note': '저장소 로컬 clone + setup (bash 필요, Windows는 Git Bash). 런타임 상태(~/.gstack)는 전역에 생길 수 있음.',
   'item.skill.gsd.note': 'npx @opengsd/gsd-core 프로젝트 로컬 설치. 상류는 Codex·Antigravity 등 18개 런타임을 지원합니다(이 항목은 --claude)',
+  // 커밋 템플릿은 CLI 배선이 아니라 저장소 규약이다 — en.mjs 쪽 주석 참고.
+  'item.config.gitmessage.en.note': '커밋 메시지를 영어로 씁니다. 템플릿을 놓고 git commit.template이 그것을 가리키게 하므로, 저장소의 모든 편집기와 도구에서 함께 열립니다',
+  'item.config.gitmessage.ko.note': '커밋 메시지를 한국어로 씁니다. 템플릿을 놓고 git commit.template이 그것을 가리키게 하므로, 저장소의 모든 편집기와 도구에서 함께 열립니다',
+  'item.gitmessage.unregistered': '파일은 놓였지만 commit.template이 아직 가리키지 않습니다',
+  'log.gitmessage.write': '  [dry-run] {path} 생성',
+  'log.gitmessage.remove': '  [dry-run] {path} 제거',
+  'error.gitmessageForeign': '{path}가 이미 있고 이 도구가 쓴 내용이 아닙니다. 손으로 쓴 템플릿은 덮어쓰지 않습니다 — 먼저 옮기거나 지우세요.',
+  'error.gitmessageConfig': 'git config commit.template 실패: {output}',
+  'error.exclusiveItems': '같은 파일을 쓰는 항목이라 하나만 고를 수 있습니다: {ids}',
   'error.gstackClone': 'gstack clone 실패: {output}',
   'error.gstackSetup': 'gstack setup 실패: {output}',
   'error.gsdInstall': 'GSD 설치 실패: {output}',
@@ -270,6 +279,7 @@ export default {
   'section.plugin': 'PLUGIN',
   'section.mcp': 'MCP',
   'section.skill': 'SKILL',
+  'section.config': 'CONFIG',
   'section.design': 'DESIGN.MD',
 
   // TUI 목록·검토 화면 문구. en.mjs 쪽 주석 참고.
@@ -280,9 +290,11 @@ export default {
   'tui.empty.none': '  항목이 없습니다.',
   'tui.hint.search': '입력=검색어   ↓ 목록으로   Tab 탭이동   Esc 검색해제   Ctrl+F CLI   Ctrl+D 상세',
   'tui.hint.list': 'Space 선택   ↑↓ 이동   Tab 탭   Enter 실행/제출   Ctrl+A 전체   Ctrl+O 미리보기   Ctrl+F CLI   Ctrl+D 상세',
+  // 힌트 줄 오른쪽 끝의 고정 자리. en.mjs 쪽 주석 참고.
+  'tui.hint.quit': 'Ctrl+Q 종료',
   'tui.review.title': '제출 검토 — 변경 {count}건',
   'tui.review.more': '  …외 {count}건',
-  'tui.review.hint': 'Enter 적용   Esc 취소',
+  'tui.review.hint': 'Enter 적용   Esc 취소   Ctrl+Q 종료',
   'tui.notItemRow': '이 행은 Enter로 실행합니다.',
   'tui.noPreview': '이 항목은 미리보기를 제공하지 않습니다.',
   'tui.opened': '열었습니다: {target}',
@@ -290,6 +302,8 @@ export default {
   'tui.submitCancelled': '제출을 취소했습니다.',
   'tui.toggledAll': '{tab} 탭의 보이는 항목을 모두 선택했습니다.',
   'tui.toggledNone': '{tab} 탭의 보이는 항목을 모두 해제했습니다.',
+  // 배타 묶음에서 형제가 함께 꺼졌을 때. en.mjs 쪽 주석 참고.
+  'tui.exclusiveSwitched': '{kept}(으)로 바꿨습니다 — 같은 파일이라 {dropped}은(는) 해제했습니다.',
   'tui.nonInteractive': '대화형 화면은 터미널에서만 열립니다. --list · --set 으로도 다룰 수 있습니다.',
   'tui.pressAnyKey': '계속하려면 아무 키나 누르세요…',
   'tui.confirmSuffix': ' [y/N] ',
@@ -320,6 +334,7 @@ export default {
   'tui.filter.empty': '  이 탭에는 {cli}에 배선되는 항목이 없습니다.',
 
   'item.location.user': '설치 위치: 사용자 글로벌',
+  'item.target': '대상 파일: {path}',
   // en.mjs 쪽 주석 참고.
   'item.cliCoverage': 'CLI {covered}/{total}',
   'item.unsupportedList': '미배선 {count}곳: {groups}',
@@ -328,6 +343,7 @@ export default {
   'detail.unwired': '미배선',
   'detail.provider': '공급자',
   'detail.preview': '미리보기',
+  'detail.target': '대상 파일',
   'detail.scope.project': '저장소 스코프',
   'detail.scope.user': '사용자 전역',
   'detail.more': '  …외 {count}줄 — Ctrl+D로 펼치기',
@@ -353,6 +369,8 @@ export default {
   'category.context': '코드 이해',
   'category.style': '디자인 감각',
   'category.flow': '작업 방식',
+  // 헤더 하나가 무엇을 고르는 자리이고 규칙이 무엇인지 함께 말한다. en.mjs 쪽 주석 참고.
+  'category.commit': '커밋 메시지 템플릿 · .gitmessage.txt · 하나만 고릅니다',
   'category.service': '외부 서비스',
   'design.localSuffix': '{id} (로컬)',
   'design.localTag': '로컬',

package/lib/items/config.gitmessage.en.mjs

@@ -0,0 +1,10 @@
+import { defineGitmessage, GITMESSAGE_EN } from '../gitmessage.mjs'
+
+export default defineGitmessage({
+  id: 'config.gitmessage.en',
+  // 두 판을 가르는 낱말을 맨 앞에 둔다 — 라벨 자리(24칸)에서 눈이 먼저 닿는
+  // 곳이고, 그룹 헤더가 이미 "커밋 템플릿"을 말하고 있어 뒤쪽은 확인용이다.
+  label: 'English commit template',
+  body: GITMESSAGE_EN,
+  note: 'item.config.gitmessage.en.note',
+})

package/lib/items/config.gitmessage.ko.mjs

@@ -0,0 +1,10 @@
+import { defineGitmessage, GITMESSAGE_KO } from '../gitmessage.mjs'
+
+export default defineGitmessage({
+  id: 'config.gitmessage.ko',
+  // 라벨은 우리 카탈로그 데이터라 두 로케일에서 같은 값이 나간다 — 영어 화면에
+  // 한글('한국어')이 새면 그 자리는 번역 누락으로 읽힌다(i18n.en.test.mjs).
+  label: 'Korean commit template',
+  body: GITMESSAGE_KO,
+  note: 'item.config.gitmessage.ko.note',
+})

package/lib/tui/detail.mjs

@@ -8,7 +8,7 @@
 import { toText, createT } from '../i18n/index.mjs'
 import { CLIS } from '../clis.mjs'
 import { categoryLabel } from '../design-md/flow.mjs'
-import { cut, pad, width, wrap } from '../width.mjs'
+import { cut, labelWidth, pad, width, wrap } from '../width.mjs'
 
 // 미배선 사유를 **같은 사유끼리** 묶는다. 사유 하나가 CLI 아홉 개에 그대로
 // 반복되면 줄만 길어지고 "무엇이 왜 빠졌는가"는 오히려 묻힌다.
@@ -25,10 +25,16 @@ export function unsupportedGroups(item, t) {
   return [...byReason].map(([why, clis]) => ({ clis, why }))
 }
 
-// '배선  ' / '미배선 ' 라벨 자리. 로케일마다 길이가 달라 상수로 박으면 열이
-// 어긋난다 — 그 로케일의 실제 라벨에서 폭을 뽑는다.
+// 왼쪽 라벨 열('배선'·'미배선'·'출처'·'미리보기'·'대상 파일')의 폭. 로케일마다
+// 길이가 달라 상수로 박으면 열이 어긋나므로 그 로케일의 실제 라벨에서 뽑는다.
+//
+// **이 열에 놓이는 라벨을 하나도 빠뜨리면 안 된다.** 예전에는 배선·미배선만
+// 재서, 한국어의 '미리보기'(8칸)가 폭 7의 열에 들어가 '미리…'로 잘렸다 —
+// pad는 넘치는 글을 cut으로 버리기 때문에 조용히 사라진다.
+const LEAD_KEYS = ['detail.wired', 'detail.unwired', 'detail.provider', 'detail.preview', 'detail.target']
+
 function leadWidth(t) {
-  return Math.max(width(t('detail.wired')), width(t('detail.unwired'))) + 1
+  return labelWidth(t, LEAD_KEYS) + 1
 }
 
 function headLine(row, w, t) {
@@ -75,6 +81,9 @@ function agentLines(row, w, t) {
   const item = row.item
   const lead = leadWidth(t)
   const out = [headLine(row, w, t)]
+  // 대상 파일은 note보다 먼저 낸다 — MCP의 배선표가 "어느 파일에 쓰이나"를
+  // 답하는 자리와 같은 몫이고, 산문보다 먼저 눈에 들어와야 한다.
+  if (item.target) out.push(cut(`${pad(t('detail.target'), lead)}${item.target}`, w))
   if (item.note) out.push(...wrap(t(item.note), w))
   if (row.statusDetail) out.push(...wrap(row.statusDetail, w))
   out.push(...wiredLines(item, w, lead, t))

package/lib/tui/render.mjs

@@ -55,9 +55,15 @@ export function reviewBodyHeight(height) {
 
 const MARK = { action: '▶', on: '×', off: ' ' }
 
+// 대괄호는 "여러 개 고를 수 있다"는 보편적 신호다 — 한 파일에 한 벌만 놓이는
+// 배타 묶음(커밋 템플릿의 두 언어판)에 그대로 쓰면 화면이 거짓말을 한다.
+// 둥근 괄호로 바꿔 라디오임을 드러낸다. 안쪽 글자는 그대로 둔다: ×는 이미
+// 이 화면이 쓰는 글자라 폭 계산이 검증된 값이고, ●·•는 동아시아 폭이
+// 모호(Ambiguous)해 터미널에 따라 두 칸으로 그려져 열을 밀 수 있다.
 function checkbox(row, selected) {
   if (row.kind === 'action') return `[${MARK.action}]`
-  return `[${selected.has(row.id) ? MARK.on : MARK.off}]`
+  const mark = selected.has(row.id) ? MARK.on : MARK.off
+  return row.exclusive ? `(${mark})` : `[${mark}]`
 }
 
 // 탭 줄. 목록이 좁혀졌으면(검색어·CLI 필터 어느 쪽이든) 탭마다 적중 수를
@@ -211,9 +217,18 @@ export function render(state, opts = {}) {
     for (let i = shown.length; i < room; i++) lines.push('')
   }
 
+  // 종료 키는 힌트 줄 **오른쪽 끝에 고정**한다. 나머지 힌트는 좁은 터미널에서
+  // 뒤쪽부터 잘려 나가는데, 하필 그때 가장 절실한 것이 "여기서 어떻게
+  // 빠져나가나"다 — 잘려도 되는 안내와 절대 사라지면 안 되는 안내를 같은
+  // 줄에 이어 붙여 두면 늘 후자가 먼저 사라진다. 상태 메시지가 힌트를
+  // 대신할 때도 이 자리는 그대로 남는다.
   const hint = state.focus === 'search' ? t('tui.hint.search') : t('tui.hint.list')
+  const quit = t('tui.hint.quit')
+  const room = w - width(quit) - 2
   lines.push('')
-  lines.push(paint(DIM, cut(status || hint, w)))
+  lines.push(room < 8
+    ? paint(BOLD, cut(quit, w))
+    : `${paint(DIM, pad(status || hint, room))}  ${paint(BOLD, quit)}`)
   return lines
 }
 

package/lib/tui/rows.mjs

@@ -20,13 +20,16 @@ export const ACTION_SECTION = 'action'
 // design-md/scan.mjs의 BUNDLE_CATEGORY와 같은 값이다 — 카테고리를 못 얻은
 // 항목이 모이는 자리. 두 값이 갈리면 같은 그룹이 두 개로 쪼개진다.
 export const CATCH_ALL_CATEGORY = '__other'
-export const SECTION_ORDER = [ACTION_SECTION, 'plugin', 'mcp', 'skill', 'design']
+export const SECTION_ORDER = [ACTION_SECTION, 'plugin', 'mcp', 'skill', 'config', 'design']
 
 // 탭 안쪽 소분류는 **성격**으로 가른다 — 같은 탭에 "무엇으로 설치되는가"가 같고
 // "무엇을 해 주는가"가 다른 항목이 섞여 있어서, 기구(plugin·mcp·skill)만으로는
 // 고를 때 비교가 되지 않는다. 표시 순서는 이 배열이 정한다.
 // `__`로 시작하는 id만 categoryLabel이 번역한다(design.md 카테고리와 같은 규칙).
-export const GROUP_ORDER = ['__token', '__context', '__style', '__flow', '__service']
+// __commit은 CONFIG 탭에만 나오지만 규칙은 같다 — 헤더가 "무엇을 고르는
+// 자리인가"를 말한다. 커밋 템플릿은 대상 파일이 하나뿐이라 헤더에 그 파일
+// 이름과 "하나만"이라는 규칙까지 실어, 라디오 표시와 함께 읽히게 한다.
+export const GROUP_ORDER = ['__token', '__context', '__style', '__flow', '__commit', '__service']
 
 function groupRank(group) {
   const i = GROUP_ORDER.indexOf(group)
@@ -75,6 +78,10 @@ export function agentHint(item, state, t = createT('en')) {
   if (item.supports) parts.push(t('item.cliCoverage', { covered: item.supports.length, total: CLI_IDS.length }))
   const detail = toText(t, state.detail)
   if (detail) parts.push(detail)
+  // 대상 파일이 하나로 정해진 항목만 target을 갖는다. 평평한 목록(printPlain·
+  // --list)에는 그룹 헤더가 없어 무엇을 건드리는지 알 길이 없고, 검색어로도
+  // '.gitmessage'가 걸리지 않았다.
+  if (item.target) parts.push(t('item.target', { path: item.target }))
   if (item.scope === 'user') parts.push(t('item.location.user'))
   // note는 이제 카탈로그 키다.
   if (item.note) parts.push(t(item.note))
@@ -123,6 +130,10 @@ function itemRow({ id, section, label, hint, fullHint = hint, statusDetail = nul
     id,
     section,
     group,
+    // 같은 파일을 두고 다투는 항목들의 묶음 이름(.gitmessage.txt의 두 언어판).
+    // 선택 배타는 state.mjs가 이 값만 보고 처리한다 — 순수 리듀서가 항목의
+    // 속내를 몰라도 되게 행에 미리 올려 둔다.
+    exclusive: item?.exclusive ?? null,
     label,
     hint,
     // 화면에 안 찍히는 긴 힌트. 비대화형 목록(printPlain)과 검색이 쓴다 —
@@ -142,6 +153,7 @@ function actionRow({ id, label, hint, run = null, t = createT('en') }) {
     id,
     section: ACTION_SECTION,
     group: null,
+    exclusive: null,
     label,
     hint,
     fullHint: hint,

package/lib/tui/run.mjs

@@ -176,7 +176,13 @@ export async function runTui(root, opts = {}) {
   const select = () => {
     const row = currentRow(state)
     if (row?.kind !== 'item') return t('tui.notItemRow')
+    const before = state.selected
     state = toggle(state)
+    // 배타 묶음에서 형제가 함께 꺼졌으면 그 사실을 말한다. 체크가 조용히
+    // 뒤집히면 사용자는 자기가 잘못 눌렀다고 읽는다 — 검색으로 형제가
+    // 화면 밖에 있을 때는 아예 무슨 일이 일어났는지 볼 수조차 없다.
+    const dropped = state.rows.filter((r) => r.id !== row.id && before.has(r.id) && !state.selected.has(r.id))
+    if (dropped.length > 0) return t('tui.exclusiveSwitched', { kept: row.label, dropped: dropped.map((r) => r.label).join(', ') })
     return ''
   }
 
@@ -194,7 +200,7 @@ export async function runTui(root, opts = {}) {
     for (;;) {
       draw(renderReview(changes, { width: stdout.columns ?? 80, height: stdout.rows ?? 24, dryRun, color, t }))
       const key = await keys.next()
-      if (key.ctrl && key.name === 'c') return 'quit'
+      if (key.ctrl && (key.name === 'c' || key.name === 'q')) return 'quit'
       if (key.name === 'escape') return 'cancel'
       if (key.name === 'return' || key.name === 'enter') return 'apply'
     }
@@ -260,6 +266,14 @@ export async function runTui(root, opts = {}) {
       // 필터를 겹쳐 걸고 싶은 순간이다. 글자 키(c·d)를 쓰지 않는 이유는
       // 목록 포커스에서 아무 글자나 누르면 검색칸으로 올라가기 때문이다:
       // c를 필터에 배정하면 codex·claude를 검색어로 칠 수 없다.
+      // 종료 전용 키. Ctrl+C는 "중단"이고 Esc는 검색어·포커스를 먼저 되돌리느라
+      // 최대 세 번을 눌러야 나간다 — 어느 쪽도 "나가는 키"로 배우기 어렵다.
+      // Ctrl+Q는 두 포커스와 검토 화면에서 한 번에 통하며, 화면 오른쪽 끝에
+      // 늘 표시된다(render의 고정 자리). 글자 q를 쓰지 않는 이유는 Ctrl+F·
+      // Ctrl+D와 같다: 목록에서 아무 글자나 누르면 검색칸으로 올라간다.
+      // raw 모드가 IXON(흐름 제어)을 끄므로 Ctrl+Q는 터미널에 먹히지 않는다.
+      if (key.ctrl && key.name === 'q') break
+
       if (key.ctrl && (key.name === 'f' || key.name === 'b')) {
         state = cycleCliFilter(state, key.name === 'f' ? 1 : -1, CLI_OPTIONS)
         continue

package/lib/tui/state.mjs

@@ -135,13 +135,40 @@ export function move(state, delta) {
   return cursor === state.cursor ? state : { ...state, cursor }
 }
 
+// row.exclusive는 "이 항목들은 같은 파일 하나를 두고 다툰다"는 표시다
+// (.gitmessage.txt의 영어판·한국어판). 하나를 켜면 나머지는 꺼진다 — 둘을 함께
+// 고르면 나중에 적용된 쪽이 앞선 쪽을 조용히 덮어써, 화면의 체크 두 개가
+// 디스크의 한 파일을 가리키는 거짓말이 된다.
+//
+// 화면 밖(검색·CLI 필터로 가려진) 형제도 끈다. 보이는 것만 건드린다는 이
+// 모듈의 규칙에서 유일하게 벗어나는 자리인데, 여기서는 그래야 한다 —
+// 가려진 형제를 남겨 두면 사용자가 방금 명시적으로 고른 판이 적용 순서에
+// 따라 뒤집힐 수 있다.
+function dropSiblings(rows, selected, row) {
+  if (!row.exclusive) return
+  for (const other of rows) {
+    if (other.id !== row.id && other.exclusive === row.exclusive) selected.delete(other.id)
+  }
+}
+
+// 형제 중 하나라도 이미 켜져 있는가. 배타 묶음은 "전부 켜짐"이 불가능하므로
+// 전체 토글의 방향 판정도 이 기준으로 봐야 한다 — 아니면 Ctrl+A가 영원히
+// 켜기만 하고 끄지 못한다.
+function groupCovered(items, selected, row) {
+  return items.some((other) => other.exclusive === row.exclusive && selected.has(other.id))
+}
+
 // 커서가 항목 행일 때만 뒤집는다. 액션 행은 제거 개념이 없어 체크 대상이 아니다.
 export function toggle(state) {
   const row = currentRow(state)
   if (row?.kind !== 'item') return state
   const selected = new Set(state.selected)
-  if (selected.has(row.id)) selected.delete(row.id)
-  else selected.add(row.id)
+  if (selected.has(row.id)) {
+    selected.delete(row.id)
+  } else {
+    selected.add(row.id)
+    dropSiblings(state.rows, selected, row)
+  }
   return { ...state, selected }
 }
 
@@ -151,10 +178,14 @@ export function toggleVisible(state, on) {
   const items = state.filtered.filter((r) => r.kind === 'item')
   if (items.length === 0) return state
   const selected = new Set(state.selected)
-  const turnOn = on ?? !items.every((r) => selected.has(r.id))
+  const turnOn = on ?? !items.every((r) => selected.has(r.id) || (r.exclusive && groupCovered(items, selected, r)))
   for (const row of items) {
-    if (turnOn) selected.add(row.id)
-    else selected.delete(row.id)
+    if (!turnOn) { selected.delete(row.id); continue }
+    // 배타 묶음에서 이미 켜진 형제가 있으면 그 선택을 이긴다 — 전체 선택이
+    // 사용자가 고른 언어판을 목록 순서로 뒤집으면 안 된다.
+    if (row.exclusive && groupCovered(items, selected, row)) continue
+    selected.add(row.id)
+    dropSiblings(state.rows, selected, row)
   }
   return { ...state, selected }
 }

package/package.json

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