@kienntpixon/dieu-phoi 0.5.3 → 0.6.1

package/lib/args.cjs

@@ -1,9 +1,10 @@
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
 const core = require('../hook.cjs');
 
-const BOOLEAN_FLAGS = new Set(['json', 'help', 'h', 'purge', 'version', 'v', 'dry-run', 'no-sync', 'approve', 'yes']);
+const BOOLEAN_FLAGS = new Set(['json', 'help', 'h', 'purge', 'version', 'v', 'dry-run', 'no-sync', 'approve', 'yes', 'force', 'follow', 'remove', 'dirty', 'no-cache', 'untagged', 'no-knowledge', 'net', 'with-codebase-memory', 'cbm', 'allow-custom-source']);
 
 /** Minimal argv parser: positionals, --k v, --k=v, boolean flags. */
 function parseArgs(argv) {
@@ -52,4 +53,20 @@ function yesNo(v, dflt) {
   throw new Error(`Giá trị y/n không hợp lệ: ${v}`);
 }
 
-module.exports = { parseArgs, claudeDirOf, ctxOf, yesNo };
+/**
+ * Repo a command works on: `--repo <path>` (any path inside the repo or one of its worktrees), else the cwd.
+ * Throws a readable error when --repo is not an existing directory. Does not require the path to be a git repo.
+ */
+function repoOf(opts) {
+  if (opts && opts.repo !== undefined) {
+    if (typeof opts.repo !== 'string' || !opts.repo) throw new Error('--repo cần một đường dẫn');
+    const p = path.resolve(core.nativePath(opts.repo));
+    let ok = false;
+    try { ok = fs.statSync(p).isDirectory(); } catch (_) { /* missing */ }
+    if (!ok) throw new Error(`--repo: không phải thư mục: ${p}`);
+    return p;
+  }
+  return process.cwd();
+}
+
+module.exports = { parseArgs, claudeDirOf, ctxOf, yesNo, repoOf };

package/lib/cbm.cjs

@@ -0,0 +1,490 @@
+'use strict';
+
+// codebase-memory-mcp (https://github.com/DeusData/codebase-memory-mcp): a recommended, optional MCP server that
+// gives agents a code graph. `doctor` reports on it (installed? registered? version? a daemon of another version?
+// repo indexed?) and `setup --with-codebase-memory` installs the official release binary + registers it in Claude
+// Code at user scope. Nothing here is required for dieu-phoi to work: every problem is a warning, never an error.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const cp = require('child_process');
+const crypto = require('crypto');
+
+const REPO = 'DeusData/codebase-memory-mcp';
+const SERVER_NAME = 'codebase-memory-mcp';
+const RELEASE_BASE = `https://github.com/${REPO}/releases/latest/download`;
+const LATEST_API = `https://api.github.com/repos/${REPO}/releases/latest`;
+const INSTALL_HINT = 'dieu-phoi setup --with-codebase-memory';
+const CHECKSUMS_MAX = 1024 * 1024;
+const DAEMON_CACHE_MS = 10 * 60 * 1000;
+
+const binName = (platform) => ((platform || process.platform) === 'win32' ? `${SERVER_NAME}.exe` : SERVER_NAME);
+const toSlash = (p) => String(p).replace(/\\/g, '/');
+
+/** Claude Code's own config file: `$CLAUDE_CONFIG_DIR/.claude.json`, or `~/.claude.json` for the default ~/.claude. */
+function claudeJsonPath(claudeDir) {
+  const def = path.join(os.homedir(), '.claude');
+  if (path.resolve(claudeDir) === path.resolve(def)) return path.join(os.homedir(), '.claude.json');
+  return path.join(claudeDir, '.claude.json');
+}
+
+function isCbmEntry(name, cfg) {
+  if (/codebase-memory/i.test(name)) return true;
+  return !!(cfg && typeof cfg.command === 'string' && /codebase-memory-mcp(\.exe)?$/i.test(cfg.command.trim()));
+}
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { return null; }
+}
+
+function samePath(a, b) {
+  const n = (p) => toSlash(path.resolve(p)).replace(/\/+$/, '');
+  return process.platform === 'win32' ? n(a).toLowerCase() === n(b).toLowerCase() : n(a) === n(b);
+}
+
+/** MCP registrations of codebase-memory-mcp visible to Claude Code for `repo`: user, local (per project) and project (.mcp.json). */
+function registrations(claudeDir, repo) {
+  const out = [];
+  const file = claudeJsonPath(claudeDir);
+  const j = readJson(file);
+  const push = (scope, servers, src) => {
+    if (!servers || typeof servers !== 'object') return;
+    for (const [name, cfg] of Object.entries(servers)) {
+      if (!isCbmEntry(name, cfg)) continue;
+      const c = cfg && typeof cfg === 'object' ? cfg : {};
+      // args/env are kept (never printed) so `install --force` can restore the entry if re-registering fails
+      out.push({
+        scope, name, command: typeof c.command === 'string' ? c.command : null, file: src,
+        args: Array.isArray(c.args) ? c.args.map(String) : [],
+        env: c.env && typeof c.env === 'object' && !Array.isArray(c.env) ? c.env : {},
+      });
+    }
+  };
+  if (j) {
+    push('user', j.mcpServers, file);
+    if (repo && j.projects && typeof j.projects === 'object') {
+      for (const [p, pc] of Object.entries(j.projects)) {
+        if (pc && samePath(p, repo)) push('local', pc.mcpServers, file);
+      }
+    }
+  }
+  if (repo) {
+    const root = repoRoot(repo) || repo;
+    const mj = readJson(path.join(root, '.mcp.json'));
+    if (mj) push('project', mj.mcpServers, path.join(root, '.mcp.json'));
+  }
+  return out;
+}
+
+function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch (_) { return false; }
+}
+
+function defaultInstallDir(platform, env) {
+  const e = env || process.env;
+  if ((platform || process.platform) === 'win32') {
+    const base = e.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(base, 'Programs', SERVER_NAME); // where the project's own install.ps1 puts it
+  }
+  return path.join(os.homedir(), '.local', 'bin');
+}
+
+/**
+ * Locate the binary: DIEU_PHOI_CBM_BIN (a path; `none` turns off PATH/default-dir search, for tests), the command of a
+ * Claude Code registration, PATH, then the default install dirs (~/.local/bin, %LOCALAPPDATA%/Programs/...).
+ */
+function findBinary(regs, env) {
+  const e = env || process.env;
+  const forced = e.DIEU_PHOI_CBM_BIN;
+  if (forced && forced !== 'none') return isFile(forced) ? { path: forced, source: 'DIEU_PHOI_CBM_BIN' } : null;
+  for (const r of regs || []) {
+    if (r.command && isFile(r.command)) return { path: r.command, source: `MCP ${r.scope}` };
+  }
+  if (forced === 'none') return null;
+  const name = binName();
+  for (const dir of String(e.PATH || e.Path || '').split(path.delimiter)) {
+    if (dir && isFile(path.join(dir, name))) return { path: path.join(dir, name), source: 'PATH' };
+  }
+  for (const dir of [path.join(os.homedir(), '.local', 'bin'), defaultInstallDir(process.platform, e)]) {
+    if (isFile(path.join(dir, name))) return { path: path.join(dir, name), source: 'thư mục mặc định' };
+  }
+  return null;
+}
+
+/** argv for running `bin` (a .js/.cjs path runs under this node — lets tests use a fake binary on every OS). */
+function binArgv(bin, args) {
+  return /\.c?js$/i.test(bin) ? [process.execPath, [bin, ...args]] : [bin, args];
+}
+
+function probeVersion(bin, timeoutMs) {
+  const [cmd, args] = binArgv(bin, ['--version']);
+  const r = cp.spawnSync(cmd, args, { encoding: 'utf8', timeout: timeoutMs || 3000, windowsHide: true });
+  if (r.error || r.status !== 0) return null;
+  const m = /(\d+\.\d+\.\d+)/.exec(`${r.stdout || ''}`);
+  return m ? m[1] : null;
+}
+
+/** `codebase-memory-mcp daemon status` → { state: active|none|unresponsive|unknown, version, pid, clients }. */
+function parseDaemonStatus(text) {
+  const t = String(text || '');
+  const res = { state: 'unknown', version: null, pid: null, clients: [] };
+  if (/daemon:\s*active/i.test(t)) res.state = 'active';
+  else if (/not responding/i.test(t)) res.state = 'unresponsive';
+  else if (/not running|no daemon|inactive|stopped/i.test(t)) res.state = 'none';
+  const b = /build:\s*v?(\d+\.\d+\.\d+)/i.exec(t) || /active version\s*v?(\d+\.\d+\.\d+)/i.exec(t);
+  if (b) res.version = b[1];
+  const p = /^\s*pid:\s*(\d+)/im.exec(t) || /held by pid\s*(\d+)/i.exec(t);
+  if (p) res.pid = Number(p[1]);
+  const re = /^\s*-\s*pid\s+(\d+)/gim;
+  let m;
+  while ((m = re.exec(t))) res.clients.push(Number(m[1]));
+  return res;
+}
+
+/** Async so doctor can start it first and overlap it with its other (blocking) checks. */
+function daemonStatus(bin, timeoutMs) {
+  return new Promise((resolve) => {
+    const [cmd, args] = binArgv(bin, ['daemon', 'status']);
+    cp.execFile(cmd, args, { encoding: 'utf8', timeout: timeoutMs || 5000, windowsHide: true }, (err, stdout, stderr) => {
+      if (err && err.killed) return resolve({ state: 'timeout', version: null, pid: null, clients: [] });
+      resolve(parseDaemonStatus(`${stdout || ''}\n${stderr || ''}`));
+    });
+  });
+}
+
+function cacheDir(env) {
+  const e = env || process.env;
+  return e.CBM_CACHE_DIR ? path.resolve(e.CBM_CACHE_DIR) : path.join(os.homedir(), '.cache', SERVER_NAME);
+}
+
+/** Top of the git work tree containing `dir` (a .git dir or file), or null. */
+function repoRoot(dir) {
+  let d = path.resolve(dir);
+  for (;;) {
+    if (fs.existsSync(path.join(d, '.git'))) return d;
+    const up = path.dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+/** For a linked worktree (`.git` is a file), the main checkout's root; else null. */
+function mainCheckoutOf(root) {
+  try {
+    const g = path.join(root, '.git');
+    if (!fs.statSync(g).isFile()) return null;
+    const m = /gitdir:\s*(.+)/.exec(fs.readFileSync(g, 'utf8'));
+    if (!m) return null;
+    const gitdir = path.resolve(root, m[1].trim());
+    let common = gitdir;
+    try { common = path.resolve(gitdir, fs.readFileSync(path.join(gitdir, 'commondir'), 'utf8').trim()); } catch (_) { /* none */ }
+    return path.basename(common) === '.git' ? path.dirname(common) : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+const canon = (s) => toSlash(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+
+/**
+ * Is `repo` indexed? codebase-memory-mcp keeps one `<project>.db` per repo in its cache dir, the project name being the
+ * path with separators as `-` (D:/Projects/x → D-Projects-x). Compared loosely (case, punctuation). Best effort: no
+ * process is spawned (a `cli list_projects` takes ~13 s and fails while a daemon of another version runs).
+ */
+function indexStatus(repo, env) {
+  const root = repoRoot(repo);
+  if (!root) return { root: null, indexed: false, skipped: 'ngoài git' };
+  let names = [];
+  const dir = cacheDir(env);
+  try { names = fs.readdirSync(dir).filter((n) => /\.db$/.test(n) && !n.startsWith('_')).map((n) => n.slice(0, -3)); } catch (_) { /* none */ }
+  const want = (p) => names.find((n) => canon(n) === canon(p));
+  const hit = want(root);
+  if (hit) return { root, indexed: true, project: hit, dir };
+  const main = mainCheckoutOf(root);
+  const mainHit = main ? want(main) : null;
+  return { root, indexed: false, main, main_project: mainHit || null, dir };
+}
+
+function cmpVersion(a, b) {
+  const pa = String(a).replace(/^v/, '').split('.').map(Number);
+  const pb = String(b).replace(/^v/, '').split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+async function latestVersion(env, timeoutMs) {
+  const url = (env || process.env).DIEU_PHOI_CBM_LATEST_URL || LATEST_API;
+  const res = await fetch(url, { headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'dieu-phoi' }, signal: AbortSignal.timeout(timeoutMs || 6000) });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const j = await res.json();
+  const m = /(\d+\.\d+\.\d+)/.exec(String(j && j.tag_name || ''));
+  if (!m) throw new Error('không đọc được tag_name');
+  return m[1];
+}
+
+function indexCommand(bin, root) {
+  return `${bin ? `"${toSlash(bin)}"` : SERVER_NAME} cli index_repository '{"repo_path":"${toSlash(root)}"}'`;
+}
+
+function registerCommand(bin) {
+  return `claude mcp add --scope user ${SERVER_NAME} -- "${toSlash(bin)}"`;
+}
+
+function readDaemonCache(file, bin, version, nowMs) {
+  if (!file) return null;
+  const c = readJson(file);
+  if (!c || !c.daemon || c.bin !== toSlash(bin) || c.version !== (version || null)) return null;
+  const t = Date.parse(c.ts);
+  if (!t || nowMs - t > DAEMON_CACHE_MS || t > nowMs + 60000) return null;
+  if (!c.daemon.state || c.daemon.state === 'timeout') return null;
+  return { ts: c.ts, daemon: c.daemon };
+}
+
+function writeDaemonCache(file, bin, version, daemon, nowMs) {
+  if (!file || !daemon || daemon.state === 'timeout') return;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify({ ts: new Date(nowMs).toISOString(), bin: toSlash(bin), version: version || null, daemon })}\n`);
+  } catch (_) { /* cache is best effort */ }
+}
+
+/**
+ * Doctor checks (all warnings at worst). Spawns at most `--version` (~40 ms) and, only with `deep` (doctor `--net` /
+ * `--cbm`), `daemon status` (~2.7 s, async, so it overlaps the other checks); otherwise the daemon line comes from a
+ * 10-minute cache (`cacheFile`) or says it was not checked. `net` adds one GitHub API call (6 s timeout).
+ * Returns a Promise of the checks: call it early, await it at the end.
+ */
+function doctorChecks({ claudeDir, repo, net, deep, cacheFile, env, now }) {
+  const e = env || process.env;
+  const nowMs = typeof now === 'number' ? now : Date.now();
+  const checks = [];
+  const add = (ok, name, detail) => checks.push({ ok, level: ok ? 'OK' : 'CẢNH BÁO', name, detail });
+  const regs = registrations(claudeDir, repo);
+  const found = findBinary(regs, e);
+  const regTxt = regs.length ? regs.map((r) => `${r.scope}:${r.name}`).join(', ') : null;
+  if (!found) {
+    add(false, 'codebase-memory', regs.length
+      ? `MCP đã đăng ký (${regTxt}) nhưng không thấy binary ${regs.map((r) => r.command).filter(Boolean).join(', ') || ''} — cài lại: \`${INSTALL_HINT} --force\``
+      : `chưa cài (khuyến nghị, không bắt buộc: agent dùng Grep/Glob khi thiếu) — cài: \`${INSTALL_HINT}\``);
+    return Promise.resolve(checks);
+  }
+  const version = probeVersion(found.path);
+  const wantDaemon = !!(deep || net);
+  const cached = wantDaemon ? null : readDaemonCache(cacheFile, found.path, version, nowMs);
+  const daemonP = wantDaemon ? daemonStatus(found.path, 5000) : Promise.resolve(null);
+  const latestP = net ? latestVersion(e).then((v) => ({ v }), (err) => ({ err: err.message })) : Promise.resolve(null);
+  return (async () => {
+    add(!!version && regs.length > 0, 'codebase-memory', `${version ? `v${version}` : 'không chạy được `--version`'} tại ${toSlash(found.path)} (${found.source})${regs.length
+      ? `; MCP: ${regTxt}` : ` — chưa đăng ký MCP trong Claude Code: \`${registerCommand(found.path)}\``}`);
+    const latest = await latestP;
+    if (latest && version) {
+      if (latest.err) add(true, 'cbm-version', `không kiểm được bản mới nhất (${latest.err})`);
+      else if (cmpVersion(version, latest.v) < 0) add(false, 'cbm-version', `v${version} cũ hơn bản mới nhất v${latest.v} — nâng cấp: \`${INSTALL_HINT} --force\` (đóng các phiên đang dùng MCP trước)`);
+      else add(true, 'cbm-version', `v${version} là bản mới nhất`);
+    }
+    let d = await daemonP;
+    let suffix = '';
+    if (d) writeDaemonCache(cacheFile, found.path, version, d, nowMs);
+    else if (cached) { d = cached.daemon; suffix = ` (bộ nhớ đệm lúc ${cached.ts}; \`dieu-phoi doctor --cbm\` để kiểm lại)`; }
+    if (!d) {
+      add(true, 'cbm-daemon', 'chưa kiểm (`daemon status` mất ~3 s) — chạy `dieu-phoi doctor --cbm` khi MCP báo lỗi hoặc nghi daemon khác version');
+    } else if (d.state === 'active' && d.version && version && d.version !== version) {
+      add(false, 'cbm-daemon', `daemon v${d.version} (pid ${d.pid || '?'}) đang chạy khác bản cài v${version} — bản cài sẽ bị từ chối (agent rơi về Grep/Glob) tới khi daemon cũ thoát. Daemon tự thoát khi phiên cuối đóng: đóng/khởi động lại các phiên Claude Code đang dùng MCP${d.clients.length ? ` (pid ${d.clients.join(', ')})` : ''}, hoặc \`codebase-memory-mcp daemon stop\` khi không còn phiên.${suffix}`);
+    } else if (d.state === 'unresponsive') {
+      add(false, 'cbm-daemon', `daemon không phản hồi${d.pid ? ` (endpoint do pid ${d.pid} giữ)` : ''} — có thể là bản khác; khởi động lại các phiên Claude Code đang dùng MCP${suffix}`);
+    } else if (d.state === 'active') {
+      add(true, 'cbm-daemon', `daemon v${d.version || '?'} đang chạy${d.clients.length ? `, ${d.clients.length} phiên` : ''}${suffix}`);
+    } else if (d.state === 'timeout') {
+      add(true, 'cbm-daemon', 'không đọc được `daemon status` trong 5 s (bỏ qua)');
+    } else {
+      add(true, 'cbm-daemon', `không có daemon đang chạy${suffix}`);
+    }
+    const ix = indexStatus(repo, e);
+    if (ix.root) {
+      if (ix.indexed) add(true, 'cbm-index', `${toSlash(ix.root)} đã index (project ${ix.project})`);
+      else {
+        add(false, 'cbm-index', `${toSlash(ix.root)} chưa index${ix.main_project ? ` (repo chính ${toSlash(ix.main)} đã có: ${ix.main_project})` : ''} — agent dùng Grep/Glob; index: \`${indexCommand(found.path, ix.root)}\``);
+      }
+    }
+    return checks;
+  })();
+}
+
+// ------------------------------------------------------------------ install
+
+/** Official release asset for this OS/arch (names as published in checksums.txt). */
+function assetFor(platform, arch) {
+  const a = arch === 'arm64' ? 'arm64' : (arch === 'x64' ? 'amd64' : null);
+  if (!a) return null;
+  if (platform === 'win32') return `${SERVER_NAME}-windows-${a}.zip`;
+  if (platform === 'darwin') return `${SERVER_NAME}-darwin-${a}.tar.gz`;
+  if (platform === 'linux') return `${SERVER_NAME}-linux-${a}-portable.tar.gz`; // portable = no glibc version dependency
+  return null;
+}
+
+function sha256File(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function digestFor(checksums, asset) {
+  for (const line of String(checksums).split(/\r?\n/)) {
+    const m = /^([0-9a-fA-F]{64})\s+\*?(\S+)\s*$/.exec(line.trim());
+    if (m && m[2] === asset) return m[1].toLowerCase();
+  }
+  return null;
+}
+
+const defaultDeps = {
+  async fetchText(url) {
+    const res = await fetch(url, { redirect: 'follow', headers: { 'User-Agent': 'dieu-phoi' }, signal: AbortSignal.timeout(30000) });
+    if (!res.ok) throw new Error(`${url} → HTTP ${res.status}`);
+    const len = Number(res.headers.get('content-length') || 0);
+    if (len > CHECKSUMS_MAX) throw new Error('checksums.txt vượt 1 MiB');
+    const t = await res.text();
+    if (t.length > CHECKSUMS_MAX) throw new Error('checksums.txt vượt 1 MiB');
+    return t;
+  },
+  async download(url, dest) {
+    const res = await fetch(url, { redirect: 'follow', headers: { 'User-Agent': 'dieu-phoi' }, signal: AbortSignal.timeout(600000) });
+    if (!res.ok) throw new Error(`${url} → HTTP ${res.status}`);
+    fs.writeFileSync(dest, Buffer.from(await res.arrayBuffer()));
+  },
+  extract(archive, destDir) {
+    // Windows' own bsdtar reads .zip; a git-bash GNU tar earlier on PATH would not.
+    const tar = process.platform === 'win32' ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe') : 'tar';
+    const r = cp.spawnSync(tar, ['-xf', archive, '-C', destDir], { encoding: 'utf8', timeout: 300000, windowsHide: true });
+    if (r.error || r.status !== 0) throw new Error(`giải nén lỗi: ${r.error ? r.error.message : (r.stderr || '').trim().slice(0, 200)}`);
+  },
+  probeVersion,
+  runClaude(args, env) {
+    const win = process.platform === 'win32';
+    const q = (a) => (win && /[\s"&|<>^]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a);
+    const r = cp.spawnSync(win ? ['claude', ...args.map(q)].join(' ') : 'claude', win ? [] : args, {
+      shell: win, encoding: 'utf8', timeout: 60000, windowsHide: true, env,
+    });
+    return { status: r.error ? null : r.status, out: `${r.stdout || ''}${r.stderr || ''}`.trim(), error: r.error ? r.error.message : null };
+  },
+};
+
+function tsStamp(d) {
+  return (d || new Date()).toISOString().replace(/[-:]/g, '').replace(/\..*/, '').replace('T', '-');
+}
+
+/**
+ * `setup --with-codebase-memory`: install the official release binary (checksum-verified) and register it in Claude Code
+ * at user scope. An existing binary / registration is kept unless `force`; a replaced binary is renamed to
+ * `<bin>.bak-dieu-phoi-<ts>` first (rename works on Windows even while the old exe runs). `deps` is injectable for tests.
+ */
+async function install(opts, deps) {
+  const d = Object.assign({}, defaultDeps, deps || {});
+  const env = opts.env || process.env;
+  const platform = opts.platform || process.platform;
+  const arch = opts.arch || process.arch;
+  const claudeDir = opts.claudeDir;
+  const force = !!opts.force;
+  const res = { ok: true, binary: null, version: null, action: null, backup: null, mcp: null, notes: [] };
+  const regs = registrations(claudeDir, null).filter((r) => r.scope === 'user');
+  const existing = findBinary(regs, env);
+
+  let target;
+  if (existing && !force) {
+    res.binary = existing.path;
+    res.version = d.probeVersion(existing.path);
+    res.action = 'kept';
+    target = existing.path;
+  } else {
+    const asset = assetFor(platform, arch);
+    if (!asset) throw new Error(`không có bản phát hành cho ${platform}/${arch} — xem https://github.com/${REPO}/releases`);
+    const base = (env.DIEU_PHOI_CBM_BASE_URL || RELEASE_BASE).replace(/\/+$/, '');
+    if (base !== RELEASE_BASE) {
+      const warn = `DIEU_PHOI_CBM_BASE_URL đang đặt nguồn tải KHÁC bản phát hành chính thức (${base} thay vì ${RELEASE_BASE}); checksums.txt lấy cùng nguồn đó nên sha256 không còn bảo đảm đây là bản chính thức`;
+      if (!opts.allowCustomSource) throw new Error(`${warn}. Không tải gì. Nếu đúng ý (mirror nội bộ, thử nghiệm): thêm --allow-custom-source; không thì bỏ biến này.`);
+      res.notes.push(`CẢNH BÁO: ${warn} (đã xác nhận bằng --allow-custom-source)`);
+    }
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dieu-phoi-cbm-'));
+    try {
+      const sums = await d.fetchText(`${base}/checksums.txt`);
+      const want = digestFor(sums, asset);
+      if (!want) throw new Error(`checksums.txt không có ${asset}`);
+      const archive = path.join(tmp, asset);
+      await d.download(`${base}/${asset}`, archive);
+      const got = sha256File(archive);
+      if (got !== want) throw new Error(`sha256 không khớp cho ${asset}: tải về ${got}, checksums.txt ${want} — không cài`);
+      const out = path.join(tmp, 'x');
+      fs.mkdirSync(out);
+      d.extract(archive, out);
+      const name = binName(platform);
+      const fresh = path.join(out, name);
+      const st = fs.existsSync(fresh) ? fs.lstatSync(fresh) : null;
+      if (!st || !st.isFile()) throw new Error(`không thấy ${name} (tệp thường) trong ${asset}`);
+      const v = d.probeVersion(fresh);
+      if (!v) throw new Error(`binary vừa tải không chạy được \`--version\` — không cài`);
+      const dir = typeof opts.dir === 'string' ? path.resolve(opts.dir) : (existing ? path.dirname(existing.path) : defaultInstallDir(platform, env));
+      target = path.join(dir, name);
+      fs.mkdirSync(dir, { recursive: true });
+      if (fs.existsSync(target)) {
+        res.backup = `${target}.bak-dieu-phoi-${tsStamp(d.now ? d.now() : new Date())}`;
+        fs.renameSync(target, res.backup);
+      }
+      try {
+        fs.copyFileSync(fresh, target);
+        if (platform !== 'win32') fs.chmodSync(target, 0o755);
+      } catch (e) {
+        if (res.backup) { try { fs.renameSync(res.backup, target); res.backup = null; } catch (_) { /* keep backup */ } }
+        throw e;
+      }
+      res.binary = target;
+      res.version = v;
+      res.action = existing ? 'replaced' : 'installed';
+      if (existing && !samePath(existing.path, target)) res.notes.push(`bản cũ vẫn ở ${toSlash(existing.path)} (không đụng)`);
+    } finally {
+      try { fs.rmSync(tmp, { recursive: true, force: true }); } catch (_) { /* best effort */ }
+    }
+  }
+
+  // registration (user scope, the standard `claude mcp add`)
+  const cmdPath = toSlash(target);
+  const same = regs.find((r) => r.command && samePath(r.command, target));
+  if (regs.length && !force) {
+    res.mcp = same ? 'kept' : 'kept-other';
+    if (!same) res.notes.push(`MCP user đã đăng ký trỏ tới ${regs.map((r) => r.command).join(', ')} — giữ nguyên (dùng --force để trỏ về ${cmdPath})`);
+  } else {
+    const cenv = Object.assign({}, env);
+    if (path.resolve(claudeDir) !== path.resolve(path.join(os.homedir(), '.claude'))) cenv.CLAUDE_CONFIG_DIR = claudeDir;
+    // old entries are remembered (command/args/env) before `remove`, so a failed `add` can put them back
+    const removed = [];
+    for (const r of regs) {
+      const rm = d.runClaude(['mcp', 'remove', '--scope', 'user', r.name], cenv);
+      if (rm.status === 0) removed.push(r);
+    }
+    const r = d.runClaude(['mcp', 'add', '--scope', 'user', SERVER_NAME, '--', cmdPath], cenv);
+    if (r.status === 0) res.mcp = regs.length ? 'replaced' : 'added';
+    else {
+      res.mcp = 'manual';
+      res.notes.push(`không chạy được \`claude mcp add\` (${r.error || r.out || `exit ${r.status}`}) — tự chạy: ${registerCommand(cmdPath)}`);
+      const lost = [];
+      for (const o of removed) {
+        const argv = ['mcp', 'add'];
+        for (const [k, v] of Object.entries(o.env || {})) argv.push('--env', `${k}=${v}`);
+        argv.push('--scope', 'user', o.name, '--', o.command || '', ...(o.args || []));
+        if (o.command && d.runClaude(argv, cenv).status === 0) res.mcp = 'restored';
+        else lost.push(o);
+      }
+      if (removed.length && !lost.length) res.notes.push(`đã khôi phục đăng ký cũ (${removed.map((o) => o.name).join(', ')}), không mất gì`);
+      for (const o of lost) {
+        res.notes.push(`KHÔNG khôi phục được đăng ký cũ "${o.name}" (command: ${o.command ? toSlash(o.command) : '?'}${o.args && o.args.length ? `, ${o.args.length} args` : ''}${Object.keys(o.env || {}).length ? `, env: ${Object.keys(o.env).join(', ')}` : ''}); thêm lại bằng \`claude mcp add --scope user ${o.name} -- <command> <args>\` (giá trị env lấy từ bản sao .claude.json của bạn)`);
+      }
+    }
+  }
+  return res;
+}
+
+module.exports = {
+  REPO, SERVER_NAME, INSTALL_HINT, claudeJsonPath, registrations, findBinary, probeVersion, parseDaemonStatus, daemonStatus,
+  cacheDir, repoRoot, indexStatus, cmpVersion, latestVersion, doctorChecks, assetFor, digestFor, install, defaultInstallDir,
+  registerCommand, indexCommand,
+};