axmap-cli 1.0.0 → 1.0.1

package/bin/axmap.mjs

@@ -1172,6 +1172,32 @@ function busSetupFailed(r) {
   return 'failed'
 }
 
+/**
+ * 쪽지함만 준비한다. **장부는 건드리지 않는다.**
+ *
+ * 🔴 왜 `init` 을 부르지 않고 이 명령이 따로 있는가. 쪽지를 **읽는** 길에서
+ *    부를 자리가 필요해서다. `init` 은 장부(`axmap/claims`)까지 만들고 그것을
+ *    원격에 push 한다 — "내 쪽지 좀 보자" 가 남의 저장소에 **선점 장부**를
+ *    만드는 일이 되면 안 된다. 쪽지 브랜치는 쪽지함이 원래 사는 곳이므로
+ *    거기까지는 간다. 선을 긋는 자리는 "읽으려는 그것" 과 "그 밖의 것" 사이다.
+ *
+ *    그래서 `tools/bus.mjs` 는 쪽지함이 없을 때 이 명령을 부른다. 만드는 코드를
+ *    저쪽에 복사하지 않는 이유는 사본이 곧 두 벌이고, 두 벌은 반드시 어긋나기
+ *    때문이다 — 이 저장소가 팀 사본을 걷어낸 것과 같은 이유다.
+ */
+function cmdBusRepair() {
+  const root = repoRoot()
+  // .axmap 을 손으로 지웠어도 git 쪽에 worktree 등록이 남아 add 가 실패한다.
+  git(['worktree', 'prune'], { cwd: root })
+  const r = ensureBus(root)
+  if (r === 'failed') process.exit(1)
+  console.log(
+    r === 'ready'
+      ? `쪽지함이 이미 있습니다: ${BUS_REL}`
+      : `쪽지함을 만들었습니다: ${BUS_REL}  (${BUS_BRANCH})`,
+  )
+}
+
 function cmdInit(flags = {}) {
   const root = repoRoot()
   const dir = ledgerDir(root)
@@ -1664,7 +1690,16 @@ function collectCodeCommits(root, range) {
   for (const line of log.out ? log.out.split(NL) : []) {
     if (!line) continue
     const [sha, author, ct, subject] = line.split(NUL)
-    const files = git(['show', '--no-renames', '--name-only', '--format=', sha], { cwd: root }).out
+    // 🔴 `-c core.quotepath=false` 가 없으면 **한글 경로가 claim 과 안 맞는다.**
+    //    git 은 기본으로 ASCII 밖 글자를 역슬래시 + 8진수 세 자리로 감싸 내보낸다.
+    //    그 문자열은 장부에 적힌 경로와 절대 같아질 수 없고, 검사는 "안 겹친다" 로
+    //    **조용히 통과**한다 - 락에서 최악인 fail-open 이다.
+    //    팀 CI 가 잡 안에서 `git config core.quotepath false` 로 막고 있었다.
+    //    우회는 그 잡에만 걸린다. 부르는 자리에서 못을 박는다 (verify 와 같은 방식).
+    const files = git(
+      ['-c', 'core.quotepath=false', 'show', '--no-renames', '--name-only', '--format=', sha],
+      { cwd: root },
+    ).out
     out.push({
       sha,
       author,
@@ -2186,6 +2221,8 @@ const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
   axmap setup                        이 PC 와 이 저장소에 axMap 을 붙인다 (첫 한 번)
                                         [--remote <이름|git 주소>] [--name] [--dry-run]
   axmap init                         장부(고아 브랜치 + worktree)를 준비한다
+  axmap bus-repair                   쪽지함만 준비한다 (장부는 안 건드린다)
+                                     쪽지를 읽다가 "쪽지함을 못 열었습니다" 를 봤을 때
   axmap claim <경로...>              경로를 선점한다  [--task --intent --ttl 30m]
   axmap release [경로...]            반납한다 (경로 생략 시 전부)
   axmap renew                        TTL 을 연장한다  [--ttl 30m]
@@ -2197,6 +2234,7 @@ const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
   axmap doctor                       이 PC 에서 선점이 실제로 도는지 점검  [--json]
   axmap hook install                 verify 를 pre-commit 훅으로 설치
   axmap update                       새 버전이 있는지 묻는다 (바꾸지는 않는다)
+  axmap --version                    지금 도는 판 번호를 찍는다 (아래 version 명령과 다르다)
 
 딸린 프로그램 — 예전에는 파일 경로로 불렀다. 이제 이름으로 부른다.
 인자는 그대로 전달되고, 각각의 사용법은 그 프로그램이 답한다.
@@ -2219,6 +2257,27 @@ const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
 const { positional, flags } = parseArgs(process.argv.slice(2))
 const [cmd, ...rest] = positional
 
+/**
+ * 🔴 `--version` 은 명령이 아니라 **깃발**이라 아래 switch 에 안 걸린다.
+ *    그대로 default 로 떨어져 **도움말을 찍고 종료 코드 0** 을 냈다. 팀 CI 가
+ *    "어느 판이 돌았는지" 를 남기려고 넣은 줄이 조용히 쓸모없어졌고, 0 이라
+ *    아무도 못 알아챘다 (실측 2026-09-01, 팀 저장소 .gitlab-ci.yml eb3b56d).
+ *
+ * 🔴 `version` **명령과는 다른 것을 답한다.** 저쪽(tools/version.mjs)은
+ *    `process.cwd()` 의 git 태그를 읽는 도구라, 남의 저장소에서 부르면 그
+ *    저장소의 버전이 나온다. 여기가 답해야 하는 것은 "지금 도는 axMap 이 몇
+ *    판인가" 이고, 그 답은 설치본 자기 package.json 에만 있다.
+ *
+ *    못 읽으면 죽는다. 모르는 것을 빈 줄로 내면 CI 로그에는 "판을 확인했다" 는
+ *    흔적만 남고 실제로는 아무것도 확인되지 않는다.
+ */
+if (boolFlag(flags.version, 'version') && !cmd) {
+  const v = selfVersion()
+  if (!v) die('버전을 알 수 없습니다 - package.json 이 없는 사본입니다.')
+  console.log(v)
+  process.exit(0)
+}
+
 switch (cmd) {
   // 이름을 경로로 바꿔 주는 것들 (RUNNERS). 인자는 손대지 않고 그대로 간다.
   case 'setup':
@@ -2238,6 +2297,9 @@ switch (cmd) {
   case 'init':
     cmdInit(flags)
     break
+  case 'bus-repair':
+    cmdBusRepair()
+    break
   case 'claim':
     cmdClaim(rest, flags)
     break

package/package.json

@@ -1,7 +1,7 @@
 {
   "//name": "🔴 npm 의 'axmap' 은 2022년부터 남이 쓰고 있는 다른 꾸러미다(leozin_ 의 Map 라이브러리, 1.1.2). 그래서 `npx axmap` 은 우리 것이 아니고, 누구에게도 그렇게 안내하면 안 된다. 2026-08-28 에 axmap-cli 로 정했다 — 스코프(@사용자/이름)를 쓰지 않는 이유는 스코프가 npm 계정 이름에 묶여서 나중에 팀이나 조직으로 옮길 때 이름이 통째로 바뀌기 때문이다. 사람이 치는 **명령** 이름은 그대로 axmap 이다 (아래 bin) — 꾸러미 이름과 명령 이름은 달라도 된다.",
   "name": "axmap-cli",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "//private": "🔴 여기 있던 \"private\": true 를 2026-08-28 에 지웠다. 그 줄이 있는 동안 npm publish 는 거부됐다. 되돌리려면 다시 넣으면 되지만, 이미 올라간 버전은 그래도 안 사라진다 — npm 은 같은 번호를 덮어쓰지 못하고 삭제도 72시간 안에만 된다. 즉 이 줄을 되살리는 것은 '앞으로 안 올린다' 는 뜻이지 '올린 것을 없앤다' 는 뜻이 아니다.",
   "//publishConfig": "axmap-cli 는 스코프가 없어서 기본이 이미 공개다. 즉 지금은 없어도 된다. 그래도 남겨 두는 이유: 나중에 @조직/axmap 처럼 스코프를 붙이는 날 이 줄이 없으면 publish 가 '유료 플랜이 필요하다'는 엉뚱한 말로 실패한다.",
   "publishConfig": {

package/tools/bus.mjs

@@ -30,7 +30,7 @@
  *    에 한 줄로 적는 편이 빠르다 — 그건 `axmap status` 로 바로 보인다.
  */
 
-import { execFileSync } from 'node:child_process'
+import { execFileSync, spawnSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -114,6 +114,79 @@ function gitBus(argv, opts = {}) {
 
 const busReady = () => BUS_WT !== null && fs.existsSync(path.join(BUS_WT, '.git'))
 
+/**
+ * 쪽지함을 못 연 이유. `null` 이면 정상이다.
+ *
+ * 🔴 이 변수가 있는 이유는 하나다 — **"쪽지 없음" 과 "못 읽었음" 을 다른 문장으로
+ *    내기 위해서다.**
+ *
+ *    2026-09-03 실측: 원격 `axmap/bus` 에 쪽지 129건이 있고 그중 오늘 온 것이
+ *    있는데, 이 체크아웃에 worktree 가 없어서 `pull()` 이 **fetch 를 한 번도 안
+ *    하고 조용히 반환**했다. 읽는 자리는 옛 함(`docs/bus`)으로 떨어졌고 거기 있던
+ *    8월 것은 이미 읽음이라 화면에 나온 답은 `쪽지 없음.` 이었다. 경고도 없었다.
+ *
+ *    **보내기는 같은 상황에서 제대로 거부했다** (아래 `post`). 쓰기는 막고 읽기만
+ *    통과시킨 것이다. 락 시스템에서 최악의 실패는 거부해야 할 것을 조용히
+ *    통과시키는 것이고(CLAUDE.md 「애매하면 거부한다」), 쪽지함에서는 **못 읽은
+ *    것을 "없다" 고 답하는 것**이 바로 그 자리다. 잘못 막으면 사람이 메시지를
+ *    읽고 고치면 되지만, 조용히 없다고 하면 아무도 잘못됐다는 것을 모른다.
+ */
+let busProblem = null
+
+/** 옛 함(`docs/bus`)에서만 읽었는가. 새 함을 못 연 채로 성공한 것처럼 보이지 않게 한다. */
+let readFromLegacyOnly = false
+
+/**
+ * 쪽지함을 연다. **없으면 만든다. 만들었으면 만들었다고 말한다.**
+ *
+ * 🔴 만드는 코드를 여기에 복사하지 않는다. `bin/axmap.mjs` 의 `ensureBus` 하나뿐이고
+ *    이 함수는 그것을 `bus-repair` 로 부른다. 사본을 두면 두 벌이 되고, 두 벌은
+ *    반드시 어긋난다 — 이 저장소가 팀 사본을 걷어낸 것과 같은 이유다.
+ *
+ * 🔴 만들고 나서 **조용히 넘어가지 않는다.** 이 버그의 본질이 "말없이 넘어간 것"
+ *    이라, 자동으로 만들어 놓고 또 말없이 넘어가면 증상만 다른 같은 병이 된다.
+ *    stdout 이 아니라 stderr 로 낸다 — 목록을 파이프로 넘겨도 사람 눈에는 남는다.
+ */
+function openBus() {
+  if (process.env.AXMAP_BUS_DIR) return true // 대상이 명시됐으면 물을 것이 없다
+  if (busReady()) return true
+  if (BUS_WT === null) {
+    busProblem = '이 저장소를 찾지 못했습니다.'
+    return false
+  }
+
+  const r = spawnSync(process.execPath, [path.join(ROOT, 'bin', 'axmap.mjs'), 'bus-repair'], {
+    cwd: REPO, encoding: 'utf8', windowsHide: true,
+  })
+  if (busReady()) {
+    console.error(`쪽지함이 없어서 만들었습니다: ${path.join('.axmap', 'bus')}  (${BUS_BRANCH})`)
+    return true
+  }
+  busProblem = (r.stderr ?? '').trim() || (r.stdout ?? '').trim() || '알 수 없는 이유로 실패했습니다.'
+  return false
+}
+
+/**
+ * 쪽지함을 못 열었다는 것을 사람이 볼 수 있게 낸다.
+ *
+ * 🔴 **"없음" 이라고 말하지 않는다.** 받은 쪽지가 없는 것이 아니라 확인을 못 한
+ *    것이고, 둘은 사람이 해야 할 일이 정반대다.
+ */
+function reportBusProblem() {
+  // 🔴 순서가 뜻이다. **무슨 일인지 먼저, 이유는 그다음.** 이유부터 내면 그것이
+  //    여러 줄일 때 안내가 아래로 밀려서, 급한 사람이 첫 줄만 보고 넘어간다.
+  const why = busProblem
+    .replace(/^경고: /, '')
+    .split('\n')
+    .map((s, i) => (i === 0 ? s : `        ${s.trim()}`))
+    .join('\n')
+  console.error(
+    '쪽지함을 못 열었습니다 — 받은 쪽지가 없는 것이 아니라 확인을 못 한 것입니다.\n' +
+      `\n  이유: ${why}\n` +
+      '\n  고치기:  axmap bus-repair      (MCP 에서는 ax_init)',
+  )
+}
+
 /**
  * 원격의 쪽지를 받아온다. **실패해도 죽지 않는다** — 못 받은 것은 위험이 아니라
  * 지연이다. 장부(`syncLedger`)가 같은 자리에서 죽는 것과 정반대이고, 그 차이의
@@ -129,7 +202,10 @@ const busReady = () => BUS_WT !== null && fs.existsSync(path.join(BUS_WT, '.git'
  *    쪽지 worktree(`.axmap/bus`) **바깥**이라 고아 브랜치에 섞이지 않는다.
  */
 function pull() {
-  if (!busReady()) return
+  // 🔴 예전에는 여기가 `if (!busReady()) return` 이었다. 쪽지함이 없으면 **fetch 를
+  //    한 번도 안 하고 조용히 반환**했고, 그것이 "쪽지 없음" 으로 보였다.
+  //    이제는 열어 보고, 못 열면 그 사실을 `busProblem` 에 남긴다.
+  if (!openBus()) return
   // 🔴 주기는 **설정에서 온다.** `--throttle` 이 1순위(부르는 쪽이 그 자리에서
   //    정한다), 없으면 `AXMAP_BUS_POLL`(초), 그것도 없으면 0 = 매번 받아온다.
   //
@@ -230,11 +306,17 @@ const slug = (s) => s.toLowerCase().replace(/[^\w가-힣]+/g, '-').replace(/^-|-
 
 function readAll() {
   const found = []
+  let newBoxOpened = false
   for (const box of READ_BOXES) {
     let ns = []
     try { ns = fs.readdirSync(box).filter((f) => f.endsWith('.md')) } catch { continue }
+    if (box === BOX) newBoxOpened = true
     for (const f of ns) found.push({ box, f })
   }
+  // 🔴 옛 함(`docs/bus`)은 **읽기 전용 유산**이다. 새 함을 못 열었는데 옛 함이
+  //    읽히면 지금까지는 그것이 **성공한 것처럼** 보였다 — 8월 20일자 8건이
+  //    나오고 오늘 온 쪽지는 없는 것이 된다. 어느 함에서 읽었는지를 남긴다.
+  readFromLegacyOnly = !newBoxOpened && found.length > 0
   return found.map(({ box, f }) => {
     const text = fs.readFileSync(path.join(box, f), 'utf8')
     const head = {}
@@ -419,7 +501,25 @@ function list() {
     rows = rows.filter((m) => m.id > seen && m.from !== who)
   }
 
-  if (!rows.length) return has('--quiet-if-empty') ? undefined : console.log('쪽지 없음.')
+  // 🔴 **못 읽었으면 "없음" 이라고 답하지 않는다.** 이 세 줄이 이 파일에서 제일
+  //    중요하다. 나머지는 편의고 이것만이 사고를 막는다.
+  //
+  //    종료 코드를 0 이 아닌 것으로 낸다 — MCP 서버(`mcp/server.mjs`)는 이미
+  //    `ok: r.code === 0` 으로 갈라 "쪽지함을 읽지 못했습니다" 를 따로 내도록
+  //    되어 있었다. 읽기가 그 신호를 **한 번도 낸 적이 없었을** 뿐이다.
+  //
+  //    `--quiet-if-empty`(훅·배너)일 때만 0 으로 끝낸다. 훅에서 0 이 아니면
+  //    커밋이 막히는데, 쪽지를 못 읽은 것으로 커밋을 막는 것은 과하다.
+  //    **다만 말은 한다** — stderr 는 그 경우에도 그대로 나간다.
+  if (busProblem) {
+    reportBusProblem()
+    if (!has('--quiet-if-empty')) process.exit(1)
+    return
+  }
+  if (!rows.length) {
+    if (readFromLegacyOnly) console.error('※ 옛 쪽지함(docs/bus)만 읽었습니다 — 새 쪽지함은 비어 있습니다.')
+    return has('--quiet-if-empty') ? undefined : console.log('쪽지 없음.')
+  }
   for (const m of rows) {
     console.log(`${m.at?.slice(0, 16).replace('T', ' ')}  ${(m.from ?? '?').padEnd(18)} → ${(m.to ?? 'all').padEnd(18)} ${m.subject ?? ''}`)
     console.log(`    ${m.id}`)
@@ -444,6 +544,9 @@ function list() {
 function read(id) {
   pull()
   const m = readAll().find((x) => x.id === id || x.id.includes(id))
+  // 🔴 못 열었으면 "없는 쪽지" 라고 말하지 않는다. 목록과 같은 이유다 — 사람은
+  //    아이디를 잘못 적었다고 믿고 다시 치게 되는데, 몇 번을 쳐도 같은 답이 온다.
+  if (!m && busProblem) { reportBusProblem(); process.exit(1) }
   if (!m) { console.error(`없는 쪽지: ${id}`); process.exit(1) }
   console.log(`── ${m.subject}\n   ${m.from} → ${m.to}   ${m.at}\n`)
   console.log(m.body)
@@ -491,7 +594,11 @@ switch (cmd) {
   case 'post': post({ to: flag('--to'), subject: flag('--subject'), body: stdin() }); break
   case 'reply': {
     const target = args[1]
+    // 🔴 답장도 먼저 받아온다. 예전에는 받아오지 않고 찾아서, 원격에만 있는 쪽지에
+    //    답장하면 **"없는 쪽지"** 가 나왔다. 아이디를 잘못 적은 것과 구별이 안 된다.
+    pull()
     const src = readAll().find((x) => x.id === target || x.id.includes(target))
+    if (!src && busProblem) { reportBusProblem(); process.exit(1) }
     if (!src) { console.error(`없는 쪽지: ${target}`); process.exit(1) }
     post({ to: src.from, subject: flag('--subject') ?? `Re: ${src.subject}`, body: stdin(), replyTo: src.id })
     break

package/.claude/settings.local.json

@@ -1,32 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(sed -i 's|/\\\\*\\\\* 궤도 모드에서 허용하는 yaw 한계 \\(약 35°\\). cos 이 0.82 아래로 내려가지 않는다. \\\\*/\\\\nconst YAW_LIMIT = 0.62|X|' app/web/graph.js)",
-      "Bash(sed -i 's|const YAW_LIMIT = 0.62|const TILT_LIMIT = 0.62|; s|허용하는 yaw 한계|허용하는 기울기 한계 \\(yaw · pitch 공통\\)|' app/web/graph.js)",
-      "Bash(sed -i 's|인코딩은 인코딩이 아니다. cos\\(TILT_LIMIT\\)=0.82 이면 고리의 화면 반지름이\\\\n   \\\\* \\\\[0.82R, R\\\\] 안에 머물러 이웃 단계와 절대 겹치지 않는다.|X|' app/web/graph.js)",
-      "Bash(sed -n '/인코딩은 인코딩이 아니다/,+2p' app/web/graph.js)",
-      "Bash(sed -i 's|import { applyEdits, draft, editRecord } from|import { applyEdits, draft } from|' app/server.mjs)",
-      "Bash(sed -i 's|\"test\": \"node --test test/protocol.test.mjs test/model.test.mjs test/analyze.test.mjs\"|\"test\": \"node --test test/protocol.test.mjs test/model.test.mjs test/analyze.test.mjs test/features.test.mjs\"|' package.json)",
-      "Bash(npm test *)",
-      "Bash(sed -i 's|        .filter\\(\\(\\\\[t\\\\]\\) => t !== name \\\\&\\\\& !taken.has\\(t\\)\\)|        .filter\\(\\([t]\\) => t !== name \\\\&\\\\& !taken.has\\(t\\) \\\\&\\\\& !tooCommon\\(t\\)\\)|' app/lib/features.mjs)",
-      "Bash(node -e ' *)",
-      "Bash(npm run *)",
-      "Bash(export AXMAP_AGENT=claude-fix GIT_AUTHOR_NAME=claude-fix GIT_AUTHOR_EMAIL=claude-fix@local GIT_COMMITTER_NAME=claude-fix GIT_COMMITTER_EMAIL=claude-fix@local)",
-      "Bash(node bin/axmap.mjs claim app/web/app.js app/web/graph.js app/web/style.css --task fix-click-color --intent \"이름 클릭=강조/더블클릭=이름변경, 단계 없을 때 색 회귀 수정\" --actor agent)",
-      "Bash(sed 's/\\\\$$//')",
-      "Bash(python -)",
-      "Bash(sed -n '/import 를 뽑을 수 있는 언어 이름/,/^\\\\]\\)/p' app/lib/analyze.mjs)",
-      "Bash(export AXMAP_AGENT=janghyojoon)",
-      "Bash(node bin/axmap.mjs release)",
-      "Bash(echo \"// 테스트\")",
-      "Bash(git add *)",
-      "Bash(git commit *)",
-      "Bash(git reset *)",
-      "Bash(git checkout *)"
-    ]
-  },
-  "enabledMcpjsonServers": [
-    "axmap"
-  ],
-  "enableAllProjectMcpServers": true
-}