axmap-cli 0.0.1

package/package.json

@@ -0,0 +1,48 @@
+{
+  "//name": "🔴 npm 의 'axmap' 은 2022년부터 남이 쓰고 있는 다른 꾸러미다(leozin_ 의 Map 라이브러리, 1.1.2). 그래서 `npx axmap` 은 우리 것이 아니고, 누구에게도 그렇게 안내하면 안 된다. 2026-08-28 에 axmap-cli 로 정했다 — 스코프(@사용자/이름)를 쓰지 않는 이유는 스코프가 npm 계정 이름에 묶여서 나중에 팀이나 조직으로 옮길 때 이름이 통째로 바뀌기 때문이다. 사람이 치는 **명령** 이름은 그대로 axmap 이다 (아래 bin) — 꾸러미 이름과 명령 이름은 달라도 된다.",
+  "name": "axmap-cli",
+  "version": "0.0.1",
+  "//private": "🔴 여기 있던 \"private\": true 를 2026-08-28 에 지웠다. 그 줄이 있는 동안 npm publish 는 거부됐다. 되돌리려면 다시 넣으면 되지만, 이미 올라간 버전은 그래도 안 사라진다 — npm 은 같은 번호를 덮어쓰지 못하고 삭제도 72시간 안에만 된다. 즉 이 줄을 되살리는 것은 '앞으로 안 올린다' 는 뜻이지 '올린 것을 없앤다' 는 뜻이 아니다.",
+  "//publishConfig": "axmap-cli 는 스코프가 없어서 기본이 이미 공개다. 즉 지금은 없어도 된다. 그래도 남겨 두는 이유: 나중에 @조직/axmap 처럼 스코프를 붙이는 날 이 줄이 없으면 publish 가 '유료 플랜이 필요하다'는 엉뚱한 말로 실패한다.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "axMap — AI Experience 의 지도이자 개발 환경의 AI Transformation. AI 에이전트들이 서로의 작업 영역을 침범하지 않도록, 코드 충돌 대신 의도 충돌을 먼저 터뜨리는 git 위의 선점 프로토콜",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://lab.ssafy.com/rleaderjoon/axmap.git"
+  },
+  "keywords": ["ai-agent", "claim", "lock", "git", "mcp", "collaboration", "preemption"],
+  "bin": {
+    "axmap": "bin/axmap.mjs"
+  },
+  "//files": "npm 꾸러미에 들어갈 것. 이 목록이 없으면 벤치 산출물·데모·테스트까지 실려 꾸러미가 수십 MB 가 된다. 여기서 빼는 것들(test·demo·corpus·desktop·docs)은 설치한 사람에게 필요 없다 — 그건 이 저장소를 clone 한 사람의 것이다.",
+  "files": [
+    "bin/",
+    "src/",
+    "mcp/",
+    "tools/",
+    "app/",
+    "governance/",
+    ".claude/",
+    "CLAUDE.md"
+  ],
+  "scripts": {
+    "test": "node tools/run-tests.mjs",
+    "setup": "node tools/setup.mjs",
+    "demo": "bash demo/run-demo.sh",
+    "demo:compare": "bash demo/conflict-vs-parser.sh",
+    "demo:chaos": "bash demo/chaos.sh",
+    "app": "node app/server.mjs",
+    "smoke": "node tools/smoke.mjs",
+    "desktop": "npm --prefix desktop start",
+    "desktop:smoke": "npm --prefix desktop run selftest",
+    "dist": "npm --prefix desktop run dist",
+    "shortcut": "node tools/shortcut.mjs --dev"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/closure.mjs

@@ -0,0 +1,343 @@
+/**
+ * **import 폐포**(closure — 진입점에서 import 를 따라 끝까지 갔을 때 닿는 파일 전부)를
+ * 구하는 순수 계산.
+ *
+ * 하나라도 빠지면 실행이 안 되고, 하나라도 남으면 안 쓰는 파일을 남의 저장소에
+ * 복사하게 된다. 그래서 **목록을 손으로 적지 않고 코드에서 구한다.**
+ *
+ * ── 왜 이 파일이 따로 있는가 ────────────────────────────────────────────────
+ *
+ * 이 목록을 쓰는 곳이 둘이다.
+ *
+ *   `tools/vendor.mjs`        벤더링(vendoring — 남의 코드를 내 저장소 안에 복사해
+ *                             두고 그 사본으로 돌리는 것) 할 파일을 고른다
+ *   `test/closure.test.mjs`   그 목록이 늘거나 줄지 않았는지 본다
+ *
+ * 🔴 두 벌로 적으면 **어긋난 순간 테스트가 통과하면서 사본이 깨진다.** 테스트가
+ *    자기 목록을 보고 초록을 내는데 벤더러는 다른 목록을 복사하기 때문이다.
+ *    한 함수를 둘이 가져다 쓴다. `src/version.mjs` 를 `tools/version.mjs` 와
+ *    `src/mrtarget.mjs` 가 함께 쓰는 것과 같은 이유다.
+ *
+ * 🔴 여기에는 파일시스템이 없다. 읽기는 `readFile` 인자로 받는다.
+ *    `src/governance.mjs` 가 git 을 인자로 받지 않는 것과 같은 이유 —
+ *    판정을 검증하려고 진짜 저장소를 만들 필요가 없어야 한다.
+ */
+
+/**
+ * CI 가 직접 부르는 파일들. `.gitlab-ci.yml` 의 `script:` 에 적힌 것과 승격 봇이
+ * 자식 프로세스로 띄우는 것을 합친 자리다.
+ *
+ * 🔴 **이 목록만 손으로 적는다.** 나머지는 여기서 import 를 따라가 구한다.
+ *    진입점은 코드가 알 수 없다 — 무엇을 CI 가 부르기로 했는지는 사람의 결정이다.
+ *
+ * `governance/vote.mjs` 는 지금 `.gitlab-ci.yml` 에 없지만 넣는다. 사람이 표를
+ * 줄 때 부르는 자리이고, 사본에 없으면 팀 저장소를 clone 한 사람은 투표를 할 수
+ * 없다 — 표를 저장소 안에 둔 이유가 통째로 사라진다.
+ *
+ * ── 🔴 `bin/axmap.mjs` 와 `mcp/server.mjs` 가 여기 있는 이유 ─────────────────
+ *
+ * 이 둘은 CI 가 아니라 **사람과 에이전트가** 부른다. 그런데도 넣는 이유는 하나다:
+ *
+ *   **팀 저장소만 clone 한 사람에게도 선점(claim)이 있어야 한다.**
+ *
+ * 없으면 충돌 방지가 "각자 axMap 을 따로 설치했는가" 에 달리게 된다. 안 한 사람
+ * 하나가 그날의 모든 보호를 무효로 만들고, 팀 규칙이 팀 저장소 밖의 무언가에
+ * 인질로 잡힌다. 장부(`axmap/claims`)는 팀 저장소에 있는데 그것을 읽고 쓸 도구가
+ * 없는 상태가 제일 이상하다 — 데이터는 있고 열쇠가 없는 것이다.
+ *
+ *   bin/axmap.mjs    claim · release · status · verify(훅) · audit
+ *   mcp/server.mjs   AI 도구가 붙는 창구. clone 만으로 `ax_claim` 이 뜬다
+ *   tools/bus.mjs    에이전트끼리 쪽지 (`ax_inbox` · `ax_send`)
+ *
+ * 🔴 `tools/bus.mjs` 를 놓쳤다가 실제로 깨뜨렸다. 이 폐포는 **`import` 만 따라간다.**
+ *    그런데 `mcp/server.mjs` 는 bus 를 import 하지 않고 **자식 프로세스로 띄운다**
+ *    (`path.join(SELF, 'tools', 'bus.mjs')`). 그래서 사본에 안 들어갔고,
+ *    `ax_inbox` 를 부르면 "Cannot find module" 로 죽었다.
+ *
+ *    교훈: **spawn 되는 파일은 import 그래프에 안 잡힌다.** 진입점 목록을 손으로
+ *    적는 이유가 정확히 이것이다 — 무엇이 실행되는지는 코드가 알 수 없다.
+ *    새 파일을 spawn 하게 되면 여기에도 더해야 한다.
+ *
+ * 전역 설치(`~/.axmap/app`)를 대신하는 것이 아니다. 둘은 같이 산다 — 팀 저장소
+ * 안에서는 `.mcp.json` 이 이 사본을 가리키고, 다른 저장소에서는 전역이 받는다.
+ *
+ * 대가는 정직하게 적어 둔다: **`bin/axmap.mjs` 는 이 저장소에서 제일 자주 바뀌는
+ * 파일이라, 사본을 다시 만들 일이 그만큼 자주 생긴다.** 그 비용을 내고 사는 것이
+ * "설치 안 한 사람 때문에 보호가 사라지는 것" 보다 낫다고 판단했다.
+ */
+export const CI_ENTRYPOINTS = Object.freeze([
+  'governance/gate.mjs',
+  'governance/vote.mjs',
+  'tools/mr-target.mjs',
+  'tools/promote.mjs',
+  'tools/version.mjs',
+  'bin/axmap.mjs',
+  'mcp/server.mjs',
+  'tools/bus.mjs',
+])
+
+/** 슬래시 하나가 `/` 로 시작하면 나눗셈이 아니라 정규식이 올 수 있는 자리다. */
+const REGEX_MAY_FOLLOW = new Set(
+  ['', '(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '+', '-', '*', '%', '<', '>', '~', '^', '\n'],
+)
+
+/** 같은 판단을 낱글자가 아니라 낱말로 해야 하는 경우 (`return /re/` 처럼). */
+const REGEX_MAY_FOLLOW_WORD = new Set(
+  ['return', 'typeof', 'case', 'in', 'of', 'delete', 'void', 'instanceof', 'new', 'do', 'else', 'yield', 'await'],
+)
+
+const isWordChar = (c) => /[A-Za-z0-9_$]/.test(c)
+
+/**
+ * 주석을 지운다. 문자열·템플릿·정규식 리터럴 **안**은 건드리지 않는다.
+ *
+ * ── 왜 지우고 시작하는가 ────────────────────────────────────────────────────
+ *
+ * 이 저장소의 파일들은 머리말 주석에 사용법을 적어 둔다. 거기에
+ * `node axmap/governance/gate.mjs` 같은 줄이 그대로 있고, `import` 라는 낱말도
+ * 설명문에 나온다. 주석을 남겨 두고 정규식을 돌리면 **주석에 적힌 예시를 진짜
+ * import 로 세어** 있지도 않은 파일을 복사 목록에 넣게 된다.
+ *
+ * 🔴 반대로 문자열은 지우면 안 된다. 우리가 찾는 것이 바로 문자열이다.
+ *    그래서 "주석만" 지운다. 정규식 리터럴을 따로 알아보는 이유도 하나뿐이다 —
+ *    `/[a-z]\/\//` 같은 것을 주석 시작으로 잘못 읽으면 그 뒤가 통째로 사라진다.
+ */
+export function stripComments(source) {
+  const src = String(source ?? '')
+  let out = ''
+  let i = 0
+  let prev = '' // 직전의 공백 아닌 코드 글자
+  let word = '' // 그 글자로 끝나는 낱말 (없으면 빈 문자열)
+
+  const regexMayFollow = () => REGEX_MAY_FOLLOW.has(prev) || REGEX_MAY_FOLLOW_WORD.has(word)
+  const advance = (c) => {
+    if (/\s/.test(c)) return // 공백은 낱말을 끊지 않는다. `return /re/` 을 알아보려면 필요하다
+    if (isWordChar(c)) word += c
+    else word = ''
+    prev = c
+  }
+
+  while (i < src.length) {
+    const c = src[i]
+    const d = src[i + 1]
+
+    if (c === '/' && d === '/') {
+      while (i < src.length && src[i] !== '\n') i++
+      continue
+    }
+
+    if (c === '/' && d === '*') {
+      i += 2
+      while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) i++
+      i += 2
+      out += ' ' // 주석이 붙어 있던 두 토큰이 한 낱말로 붙지 않게 자리를 남긴다
+      prev = ''
+      word = ''
+      continue
+    }
+
+    if (c === '"' || c === "'" || c === '`') {
+      out += c
+      i++
+      while (i < src.length) {
+        if (src[i] === '\\') {
+          out += src[i] + (src[i + 1] ?? '')
+          i += 2
+          continue
+        }
+        const ch = src[i]
+        out += ch
+        i++
+        if (ch === c) break
+      }
+      prev = c
+      word = ''
+      continue
+    }
+
+    if (c === '/' && regexMayFollow()) {
+      out += c
+      i++
+      let inClass = false
+      while (i < src.length) {
+        const ch = src[i]
+        if (ch === '\\') {
+          out += ch + (src[i + 1] ?? '')
+          i += 2
+          continue
+        }
+        if (ch === '\n') break // 줄을 넘는 정규식 리터럴은 없다. 잘못 짚었다는 뜻이니 멈춘다
+        out += ch
+        i++
+        if (ch === '[') inClass = true
+        else if (ch === ']') inClass = false
+        else if (ch === '/' && !inClass) break
+      }
+      prev = '/'
+      word = ''
+      continue
+    }
+
+    out += c
+    advance(c)
+    i++
+  }
+
+  return out
+}
+
+/*
+ * import 를 알아보는 세 가지 모양.
+ *
+ * `[^'";()]*?` 로 가운데를 막아 둔 것은 한 문장을 넘어가지 못하게 하기 위해서다.
+ * 이걸 `[\s\S]*?` 로 두면 앞 줄의 `import` 와 한참 뒤의 `from` 이 짝지어져 엉뚱한
+ * 문자열을 경로로 읽는다.
+ *
+ * 알려진 한계: `export const from = './x.mjs'` 처럼 `from` 을 변수 이름으로 쓰면
+ * 거짓 양성이 난다. 그때는 그 경로가 bare 나 없는 파일로 잡혀 테스트가 빨개진다 —
+ * 조용히 지나가지는 않는다.
+ */
+const RE_FROM = /(?:^|[\s;})])(?:import|export)\s[^'";()]*?\bfrom\s*(['"])([^'"]+)\1/gm
+const RE_SIDE_EFFECT = /(?:^|[\s;})])import\s*(['"])([^'"]+)\1/gm
+const RE_DYNAMIC = /\bimport\s*\(\s*(['"])([^'"]+)\1\s*\)/gm
+
+/**
+ * 소스 한 벌에서 import 대상 문자열을 전부 뽑는다. 주석은 먼저 지운다.
+ *
+ * `import.meta.url` 은 걸리지 않는다 — 세 정규식 모두 `import` 뒤에 공백이나
+ * 여는 괄호를 요구하고, `.` 은 어느 쪽도 아니다.
+ */
+export function importSpecifiers(source) {
+  const code = stripComments(source)
+  const found = []
+  for (const re of [RE_FROM, RE_SIDE_EFFECT, RE_DYNAMIC]) {
+    re.lastIndex = 0
+    let m
+    while ((m = re.exec(code)) !== null) found.push(m[2])
+  }
+  return found
+}
+
+/**
+ * import 대상을 셋으로 가른다.
+ *
+ *   `builtin`   `node:fs` 처럼 Node 가 들고 있는 것. 복사할 것이 없다
+ *   `relative`  `./x.mjs` · `../src/y.mjs`. 따라가서 같이 복사해야 한다
+ *   `bare`      그 밖 전부. npm 패키지이거나 `fs` 처럼 `node:` 를 빠뜨린 것
+ *
+ * 🔴 `fs` 를 `bare` 로 세는 것은 실수가 아니다. 접두사 없는 내장 이름은 같은
+ *    이름의 npm 패키지에 가려질 수 있고, 그러면 어느 쪽이 로드됐는지 코드만
+ *    보고는 알 수 없다. 이 저장소는 `node:` 를 붙이기로 했으므로 안 붙은 것은
+ *    구분 없이 빨갛게 만든다.
+ */
+export function classifySpecifier(spec) {
+  const s = String(spec ?? '')
+  if (s.startsWith('node:')) return 'builtin'
+  if (s === '.' || s === '..' || s.startsWith('./') || s.startsWith('../')) return 'relative'
+  return 'bare'
+}
+
+/** posix 경로 계산. `path` 모듈을 안 쓰는 이유는 Windows 에서 `\` 가 섞이면 안 되어서다. */
+function posixDirname(rel) {
+  const i = rel.lastIndexOf('/')
+  return i < 0 ? '' : rel.slice(0, i)
+}
+
+/**
+ * `fromRel` 안의 `spec` 이 가리키는 파일을 루트 기준 상대 경로로 돌려준다.
+ * 루트 밖으로 나가면 `null` — 복사할 수 없는 것이므로 부르는 쪽이 알아야 한다.
+ */
+export function resolveImport(fromRel, spec) {
+  const parts = `${posixDirname(String(fromRel))}/${String(spec)}`.split('/')
+  const stack = []
+  for (const p of parts) {
+    if (p === '' || p === '.') continue
+    if (p === '..') {
+      if (stack.length === 0) return null // 루트를 뚫고 올라갔다
+      stack.pop()
+      continue
+    }
+    stack.push(p)
+  }
+  return stack.length === 0 ? null : stack.join('/')
+}
+
+/**
+ * 진입점에서 출발해 닿는 파일 전부를 모은다.
+ *
+ * @param {object} opts
+ * @param {string[]} [opts.entries]  루트 기준 상대 경로. 기본은 `CI_ENTRYPOINTS`
+ * @param {(rel: string) => (string|null)} opts.readFile
+ *        파일 내용. 없으면 `null` 을 준다 (던지지 않는다 — 없는 파일도 결과의 일부다)
+ * @returns {{files: string[], bare: {file: string, spec: string}[],
+ *            missing: string[], outside: {file: string, spec: string}[], entries: string[]}}
+ *
+ * 🔴 못 읽은 파일을 예외로 터뜨리지 않고 `missing` 에 담는 이유: 부르는 쪽이
+ *    "무엇이 왜 안 됐는지" 를 한 번에 보고해야 하기 때문이다. 첫 번째에서 죽으면
+ *    두 번째 문제는 다음 실행에서야 보인다.
+ */
+export function importClosure({ entries = CI_ENTRYPOINTS, readFile } = {}) {
+  if (typeof readFile !== 'function') throw new TypeError('importClosure: readFile 함수가 필요합니다')
+
+  const entryList = [...entries]
+  const files = new Set()
+  const bare = []
+  const missing = []
+  const outside = []
+  const seen = new Set()
+  const queue = [...entryList]
+
+  while (queue.length > 0) {
+    const rel = queue.shift()
+    if (seen.has(rel)) continue
+    seen.add(rel)
+
+    const source = readFile(rel)
+    if (source == null) {
+      missing.push(rel)
+      continue
+    }
+    files.add(rel)
+
+    for (const spec of importSpecifiers(source)) {
+      const kind = classifySpecifier(spec)
+      if (kind === 'builtin') continue
+      if (kind === 'bare') {
+        bare.push({ file: rel, spec })
+        continue
+      }
+      const next = resolveImport(rel, spec)
+      if (next === null) {
+        outside.push({ file: rel, spec })
+        continue
+      }
+      queue.push(next)
+    }
+  }
+
+  return { files: [...files].sort(), bare, missing, outside, entries: entryList }
+}
+
+/**
+ * 폐포를 구하다 만난 문제를 사람이 읽는 줄로 바꾼다. 문제가 없으면 빈 배열.
+ *
+ * 벤더러와 테스트가 같은 문장을 내야 한다 — 한쪽에서 본 메시지를 다른 쪽에서
+ * 검색했을 때 안 나오면 같은 문제인지 알 수 없다.
+ */
+export function formatClosureProblems(closure) {
+  const lines = []
+  for (const rel of closure.missing) {
+    lines.push(`없는 파일을 import 합니다: ${rel}`)
+  }
+  for (const { file, spec } of closure.outside) {
+    lines.push(`루트 밖을 import 합니다: ${file} → ${spec} (복사할 수 없습니다)`)
+  }
+  for (const { file, spec } of closure.bare) {
+    lines.push(
+      `Node 내장이 아닌 것을 import 합니다: ${file} → '${spec}'\n` +
+        `    내장이라면 'node:${spec}' 처럼 접두사를 붙이세요.\n` +
+        `    패키지라면 CI 진입점에서 닿는 자리에 둘 수 없습니다 — 사본에는 node_modules 가 없습니다.`,
+    )
+  }
+  return lines
+}