agent-syncer 0.1.1 → 0.1.2

package/lib/commands/sync.js

@@ -5,6 +5,7 @@ import { CONFIG_FILENAME, loadConfig } from '../config.js';
 import { applyInstall, findOrphans, planInstall } from '../install.js';
 import {
   RECORD_REL,
+  backupUnreadableRecord,
   carryOver,
   isTracked,
   planRemovals,
@@ -20,9 +21,9 @@ import {
   loadRepo,
   resolveSelection,
 } from '../manifest.js';
-import { dim, fail, info, ok, plain, title, warn } from '../log.js';
+import { dim, fail, info, ok, plain, rel, title, warn } from '../log.js';
 import { isInteractive } from '../prompt.js';
-import { applyMergeAll } from '../merge.js';
+import { applyMergeAll, keepByProtect } from '../merge.js';
 import { rmdirIfEmpty, rmdirTreeIfEmpty } from '../prune.js';
 import { fetchRepo, isGitUrl, localRefWarning } from '../source.js';
 import { CONTENT_ROOT, MERGE_KINDS, TOOLS } from '../target.js';
@@ -46,8 +47,27 @@ function printBundles(repoRoot) {
   plain(dim('  只想微调？"include" / "exclude" 可以叠在模板之上，exclude 最后生效。'));
 }
 
-/** 统一的相对路径显示（正斜杠，跨平台一致） */
-const rel = (from, to) => path.relative(from, to).split(path.sep).join('/');
+/**
+ * 要透传给 `link` 的选项。**白名单，不是把整个 flags 递过去。**
+ *
+ * 整个递过去踩过一次（实测）：命令层的 flags 没有命名空间，而 `--src`/`--dst`
+ * 会把 link 拨到「直连模式」那条路上——于是 sync 装完了内容、写完了记录，却
+ * **一条托管链接都没建、.gitignore 也没写**，退出码还是 0。正好是这个工具最
+ * 不该出现的状态：链接不在忽略段里，git 会顺着它们把 `.agents/` 的内容再提交
+ * 一份，而全程没有一句提示。
+ *
+ * 这里只留 link 自己认识的开关。将来 link 加了新选项就**显式加进来**——
+ * 那点摩擦正是白名单该有的。
+ *
+ * @param {Record<string, any>} flags
+ */
+function linkFlags(flags) {
+  const PASS = ['dry-run', 'force', 'prune', 'yes', 'no-save'];
+  /** @type {Record<string, any>} */
+  const out = {};
+  for (const k of PASS) if (flags[k] !== undefined) out[k] = flags[k];
+  return out;
+}
 
 /**
  * 把 hooks / mcp 合并进各工具自己的配置文件。
@@ -66,17 +86,11 @@ const rel = (from, to) => path.relative(from, to).split(path.sep).join('/');
 function runMerge({ cwd, plan, config, record, dryRun, prune }) {
   /** @type {Record<string, Record<string, string>>} */
   const sourcesByKind = {};
-  /** @type {Record<string, string[]>} */
-  const keepByKind = {};
-
-  /** @param {string} dir @param {string} id */
-  const addKeep = (dir, id) => {
-    const list = (keepByKind[dir] ??= []);
-    if (!list.includes(id)) list.push(id);
-  };
 
   // 注意 `plan` 里**不会有被 protect 锁住的条目**（sync 早就把它们滤掉了），
-  // 所以这里不必再判一次 protect——锁住的那些由下面那个循环单独收。
+  // 所以这里不必再判一次 protect。锁住的那些由 `keepByProtect` 单独收：它们不在
+  // plan 里，却很可能已经合并进过工具配置——不显式算进来的话，「锁住它」到了
+  // --prune 就失效，而用户写 protect 的正是「别动这个」。
   for (const e of plan) {
     const dir = ITEM_KINDS[e.kind]?.dir;
     // scripts 没有条目类型，也不合并——它整目录同步，由 hook 按路径引用
@@ -84,23 +98,12 @@ function runMerge({ cwd, plan, config, record, dryRun, prune }) {
     (sourcesByKind[dir] ??= {})[e.id] = e.from;
   }
 
-  // protect 里锁住、但**本次没选中**的条目也要算数。它们不在 plan 里，却很可能
-  // 已经合并进过工具配置——不显式加进来的话，「锁住它」到了 --prune 就失效，
-  // 而用户写 protect 的正是「别动这个」。
-  for (const key of config.protect) {
-    const colon = key.indexOf(':');
-    if (colon === -1) continue;
-    const dir = ITEM_KINDS[key.slice(0, colon)]?.dir;
-    if (!dir || !MERGE_KINDS.includes(dir)) continue;
-    addKeep(dir, key.slice(colon + 1));
-  }
-
   return {
     ...applyMergeAll({
       projectRoot: cwd,
       tools: config.tools,
       sourcesByKind,
-      keepByKind,
+      keepByKind: keepByProtect(config.protect),
       prevMerged: record.merged ?? {},
       dryRun,
       prune,
@@ -329,15 +332,22 @@ export async function run({ cwd, flags, input, output }) {
     for (const e of plan) (by[e.status] ??= []).push(e);
 
     // ---- 5. 报告 ----
-    for (const e of by.blocked) fail(`${e.spec}  目标是链接，拒绝覆盖`);
+    for (const e of by.blocked) {
+      fail(`${e.spec}  路径上有链接，拒绝覆盖：${path.relative(cwd, e.linkAt ?? e.to)}`);
+    }
     for (const e of by.new) ok(`${e.spec}  ${dim('新增')}`);
     for (const e of by.update) info(`${e.spec}  ${dim('更新（本地同名内容会被覆盖）')}`);
 
     if (by.blocked.length > 0) {
       title('需要你处理');
-      plain('  下面这些路径是链接，sync 不会写进链接指向的地方：');
-      for (const e of by.blocked) plain(`  · ${path.relative(cwd, e.to)}`);
-      plain('  先删掉它们或改用 link 管理，再重跑。');
+      plain('  下面这些路径（它自己或它的上层目录）是链接，sync 不会写进链接指向的地方：');
+      for (const e of by.blocked) {
+        const at = e.linkAt ?? e.to;
+        plain(`  · ${path.relative(cwd, at)}${at === e.to ? '' : dim('（是上层目录）')}`);
+      }
+      // 链接指向的地方很可能还有别的项目在管同一批内容（每个项目的记录各管各的），
+      // 这边写进去、那边 --prune 删掉，会互相踩
+      plain('  那儿可能还有别的项目在管同一批内容。先删掉链接或改用 link 管理，再重跑。');
       return 1;
     }
 
@@ -484,6 +494,13 @@ export async function run({ cwd, flags, input, output }) {
     // 注意**不能放进上面的 `if (record.usable)`**——首次运行时记录还不存在，
     // 那正是它最需要被写下来的时刻。
     if (!dryRun) {
+      // 读不出来的那份（坏 JSON / BOM / 别的版本写的）先留个档再重建：
+      // `writeRecord` 是整份重写，不备份的话盘上那份就永久没了，而它记的归属
+      // 没有第二处能推导出来。
+      if (!record.usable && record.reason) {
+        const bak = backupUnreadableRecord(cwd);
+        if (bak) warn(`原来那份记录读不了，已备份成 ${bak}，本次重建一份新的`);
+      }
       writeRecord(cwd, carryOver(snapshotRecord(cwd, items, scripts, merge.merged), carry));
     }
 
@@ -518,11 +535,16 @@ export async function run({ cwd, flags, input, output }) {
     // ---- 10. 建链接 ----
     if (dryRun) {
       plain(dim('\n这是预演，未写盘。去掉 --dry-run 即可实际执行。'));
-      return 0;
+      // 预演也要如实反映故障：同一份现场，`sync` 退 1 而 `sync --dry-run` 退 0，
+      // 就是「预演是绿的、真跑是红的」——CI 里只看退出码的人会被骗一道。
+      // 「同一现场同一结论」是 merge.js 里 checkMergeAll 那段定下的口径。
+      return merge.problems.length > 0 ? 1 : 0;
     }
 
     plain('');
-    const linkCode = await runLink({ cwd, flags, input, output });
+    // **只透传 link 认识的选项**，不能整个 flags 递过去——`--src`/`--dst` 会把
+    // 它拨到直连模式，托管链接就一条都不建了（见 linkFlags 那段）
+    const linkCode = await runLink({ cwd, flags: linkFlags(flags), input, output });
     // 合并出了硬问题（内容文件坏了、目标写不进去）也要反映在退出码上，
     // 否则 CI 里只看退出码的人会以为一切都好
     return linkCode !== 0 ? linkCode : merge.problems.length > 0 ? 1 : 0;

package/lib/config.js

@@ -2,23 +2,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ITEM_KINDS, ITEM_KIND_NAMES, SUPPORT_DIR } from './manifest.js';
-// 借 merge.js 的原子写。这个文件的依赖方向确实有点逆（config 比 merge 底层），
-// 但「tmp + rename」是个**安全原语**，再抄一份出来比这个方向更糟——
-// link.js 里还有一份内联的，已经够多了。
-import { writeJsonFile } from './merge.js';
+// 借 merge.js 的两样东西：原子写和剥 BOM。
+//
+// 这个文件的依赖方向确实有点逆（config 比 merge 底层），但两个都是**安全原语**
+// ——「tmp + rename」和「JSON 文本怎么读」，再抄一份出来比这个方向更糟：
+// link.js 里还有一份内联的原子写，而 BOM 这件事原先在三处各有一个说法，
+// record.js 那份干脆没有，于是记事本改一下记录就让归属全丢。
+import { isMissingPath, stripBom, writeJsonFile } from './merge.js';
 import { TOOL_NAMES, isTool, sortTools, specsOfTools } from './target.js';
 
 export const CONFIG_FILENAME = 'agents.json';
 
-/**
- * 有 BOM 就剥掉。
- *
- * Windows 上记事本、PowerShell 的 `>` 重定向默认都写带 BOM 的 UTF-8，而
- * `JSON.parse` 见 BOM 直接抛——用户会看到「不是合法的 JSON」，然后去改一个
- * 其实完全正常的文件。`merge.js` 的 `readJsonFile` 早就这么处理了，这里跟上。
- */
-const stripBom = (text) => (text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
-
 /**
  * 读 `agents.json` 的原文。三种结果分得很开，**混起来就是上次那个 blocker**：
  *
@@ -39,7 +33,7 @@ function readConfigText(projectRoot) {
     return fs.readFileSync(p, 'utf8');
   } catch (e) {
     const err = /** @type {any} */ (e);
-    if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return null;
+    if (isMissingPath(err)) return null;
     throw new Error(`${CONFIG_FILENAME} 读不了（${err.code ?? err.message}）：${p}`);
   }
 }

package/lib/gitignore.js

@@ -88,13 +88,24 @@ export function checkBlock(projectRoot, tools) {
     return { present: false, missing: [], extra: [] };
   }
 
-  const block = content.slice(start, end);
-  const expected = buildBlock(projectRoot, tools)
-    .split('\n')
-    .filter((l) => l && !l.startsWith('#'));
-  const missing = expected.filter((l) => !block.includes(l));
+  /** 逐行拆出来：注释和空行不算，两边都用这把尺子 */
+  const linesIn = (/** @type {string} */ text) =>
+    text
+      .split('\n')
+      .map((l) => l.trim())
+      .filter((l) => l !== '' && !l.startsWith('#'));
 
-  return { present: true, missing, extra: [] };
+  const expected = linesIn(buildBlock(projectRoot, tools));
+  const found = linesIn(content.slice(start + BEGIN_MARK.length, end));
+
+  // 按行比，不用 `block.includes(l)` 那种子串判断：期望项 `.claude/rules` 会被
+  // 段里的一行 `.claude/rules-old` 命中，于是「缺了这条」永远报不出来。
+  const missing = expected.filter((l) => !found.includes(l));
+  // 段里多出来的行。`writeBlock` 是**整段重建**的，这几行会在下一次 link 时
+  // 无声消失——报出来，别让「写在托管段里也能生效」变成一个事后才发现不成立的假设。
+  const extra = found.filter((l) => !expected.includes(l));
+
+  return { present: true, missing, extra };
 }
 
 /**

package/lib/install.js

@@ -2,20 +2,10 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { ITEM_KINDS, SUPPORT_DIR, itemPath, parseItem } from './manifest.js';
+import { isSymlink } from './link.js';
+import { ITEM_KINDS, SUPPORT_DIR, itemPath, parseItem, projectItemPath } from './manifest.js';
 import { CONTENT_ROOT } from './target.js';
 
-/** 条目在项目里的落点：.agents/<仓库目录名>/<id>[ext] */
-export function projectItemPath(projectRoot, kind, id) {
-  const cfg = ITEM_KINDS[kind];
-  return path.resolve(
-    projectRoot,
-    CONTENT_ROOT,
-    cfg.dir,
-    cfg.ext === null ? id : `${id}${cfg.ext}`,
-  );
-}
-
 /**
  * 目录树的稳定指纹：所有文件的「相对路径 + 内容哈希」，按路径排序。
  * 单文件则直接返回内容哈希。
@@ -70,13 +60,35 @@ function statusOf(from, to) {
   }
 }
 
-/** 判断路径是不是链接——是的话绝不能覆盖 */
-function isLink(p) {
-  try {
-    return fs.lstatSync(p).isSymbolicLink();
-  } catch {
-    return false;
+/**
+ * 落点路径上、**项目范围内**有没有链接——不含最后一段（那一段由调用方判，
+ * 消息不一样）。
+ *
+ * 为什么必须往上找：守卫原先只看叶子，于是 `.agents/skills` 自己是链接时，
+ * `.agents/skills/alpha` 不是链接，守卫整条放过——sync 就**写穿到链接指向的
+ * 地方**去了（实测过：内容落进了外部目录，退出码还是 0），而本工具对用户的
+ * 承诺是「不写进链接指向的地方」。
+ *
+ * 链接指向别处意味着那份内容可能**还有别的项目在管**（每个项目的记录是各管各的），
+ * 这边 `--prune` 一删，那边就凭空少东西。所以和叶子一样：拒绝，并说清怎么走。
+ *
+ * 上溯**从项目根开始**，不爬到文件系统根：项目根自己的祖先是不是链接
+ * （macOS 上 `/tmp` 就是）不归本工具管，管了只会全是误报。
+ *
+ * @param {string} projectRoot @param {string} abs
+ * @returns {string|null} 是链接的那一段的绝对路径
+ */
+function linkInPath(projectRoot, abs) {
+  const rel = path.relative(projectRoot, abs);
+  if (rel === '' || path.isAbsolute(rel) || rel.startsWith('..')) return null; // 落点不在项目内
+
+  let cur = projectRoot;
+  // 去掉最后一段（叶子），只看中间目录
+  for (const part of rel.split(path.sep).slice(0, -1)) {
+    cur = path.join(cur, part);
+    if (isSymlink(cur)) return cur;
   }
+  return null;
 }
 
 /**
@@ -138,7 +150,7 @@ function collectSupport(repoRoot, projectRoot) {
  * @param {string} repoRoot @param {string} projectRoot @param {string[]} items
  */
 export function planInstall(repoRoot, projectRoot, items) {
-  /** @type {{spec: string, kind: string, id: string, from: string, to: string, status: string}[]} */
+  /** @type {{spec: string, kind: string, id: string, from: string, to: string, status: string, linkAt?: string}[]} */
   const entries = [];
 
   for (const spec of items) {
@@ -159,10 +171,19 @@ export function planInstall(repoRoot, projectRoot, items) {
   // 仍然躺在 `.agents/hooks/` 里，它引用的脚本还得留着。
   if (wantsSupport(items)) entries.push(...collectSupport(repoRoot, projectRoot));
 
-  // 目标是链接的一律拦下——那多半是 link 命令建的反向链接，
-  // 覆盖它等于把内容仓库的东西写进一个链接指向的地方
+  // 路径上有链接的一律拦下——那多半是 link 命令建的反向链接，
+  // 写进去等于把内容仓库的东西写进一个链接指向的地方。叶子和中间目录都查。
   for (const e of entries) {
-    if (isLink(e.to)) e.status = 'blocked';
+    if (isSymlink(e.to)) {
+      e.status = 'blocked';
+      e.linkAt = e.to;
+      continue;
+    }
+    const up = linkInPath(projectRoot, e.to);
+    if (up) {
+      e.status = 'blocked';
+      e.linkAt = up;
+    }
   }
 
   return entries;

package/lib/log.js

@@ -1,4 +1,5 @@
 // @ts-check
+import path from 'node:path';
 import process from 'node:process';
 
 // 颜色仅在 TTY 下启用，遵循 NO_COLOR 约定
@@ -56,3 +57,13 @@ export const title = (msg) => {
 export const plain = (msg = '') => {
   if (!silent()) console.log(msg);
 };
+
+/**
+ * 给人看的相对路径：一律正斜杠，跨平台长得一样。
+ *
+ * 这是**显示**规则，不是路径处理——真正拼路径的地方一律 `path.join`/`path.resolve`。
+ * 放在这里是因为它服务于输出：`status` / `sync` 原先各写了一份一模一样的实现。
+ *
+ * @param {string} from @param {string} to
+ */
+export const rel = (from, to) => path.relative(from, to).split(path.sep).join('/');

package/lib/manifest.js

@@ -1,6 +1,7 @@
 // @ts-check
 import fs from 'node:fs';
 import path from 'node:path';
+import { CONTENT_ROOT } from './target.js';
 
 /** 当前支持的内容仓库 schema 版本 */
 export const SCHEMA_VERSION = 1;
@@ -38,6 +39,27 @@ export function itemPath(repoRoot, kind, id) {
   return path.resolve(repoRoot, cfg.dir, cfg.ext === null ? id : `${id}${cfg.ext}`);
 }
 
+/**
+ * 条目在项目里的落点：`<项目根>/.agents/<仓库目录名>/<id>[ext]`。
+ *
+ * 和上面 `itemPath` 是镜像——一个问「内容仓库里在哪」，一个问「项目里在哪」。
+ * **放在一起是因为它们总是一起变**：加一类条目、改一次扩展名，两个函数必须同时
+ * 改对。（它原先住在 `install.js`，于是 `record.js` 为了拿它得反向依赖安装层——
+ * 一个「条目在哪」的问题，不该由「怎么把文件拷过去」那个模块来回答。）
+ *
+ * @param {string} projectRoot @param {string} kind @param {string} id
+ */
+export function projectItemPath(projectRoot, kind, id) {
+  const cfg = ITEM_KINDS[kind];
+  if (!cfg) throw new Error(`未知条目类型 "${kind}"（可用：${ITEM_KIND_NAMES.join('、')}）`);
+  return path.resolve(
+    projectRoot,
+    CONTENT_ROOT,
+    cfg.dir,
+    cfg.ext === null ? id : `${id}${cfg.ext}`,
+  );
+}
+
 /**
  * 解析 `kind:id` 形式的条目引用。
  * @param {string} entry

package/lib/merge.js

@@ -10,6 +10,7 @@ import {
   PROJECT_DIR_ALIASES,
   TOOLS,
   isTool,
+  mergeKindsOf,
   mergeTarget,
   projectDirOf,
 } from './target.js';
@@ -63,6 +64,49 @@ function isPlain(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+/**
+ * 有 BOM 就剥掉。
+ *
+ * Windows 上记事本、PowerShell 的 `>` 重定向默认都写带 BOM 的 UTF-8，而
+ * `JSON.parse` 见 BOM 直接抛。**这份知识以前散在好几个地方**：merge.js 在
+ * `readJsonFile` 里内联做了一次，config.js 抄了一份（还注明「merge.js 早就这么
+ * 处理了，这里跟上」），而 record.js 压根没做——于是记事本改一下
+ * `.agents/.agent-sync.json`，记录当场判为「不可用」，合并产物的归属跟着全丢。
+ * 收在这里一处，谁读 JSON 谁拿去用。
+ *
+ * @param {string} text
+ */
+export function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/**
+ * 这个错误是不是「路径上真的没有东西」。
+ *
+ * **只有 `ENOENT` / `ENOTDIR` 算不存在，其余（`EPERM` / `EACCES` / `EBUSY` /
+ * `ELOOP`…）一律是「有东西，但读不到」。** 别逐个列举权限类错误码：Windows 上
+ * 同一件事可能是 EPERM 也可能是 EACCES，漏一个就退化成「不存在」。
+ *
+ * 这个区分不是洁癖，两个方向都出过事：
+ *
+ * - **降级成「不存在」→ 接着写。** `readJsonFile` 的 blocker 就是这么来的：
+ *   读不到被当成「这文件没有」，调用方走「没坏、可以写」那条分支，把用户已有的
+ *   `.mcp.json` 整份覆盖掉。
+ * - **降级成「不存在」→ 报给用户看。** `status` 的内容计数原先 `catch` 一律返回
+ *   null，于是权限错、IO 错都打成「无此目录」——用户看到的是「这儿没东西」，
+ *   而真相是「这儿的东西我看不到」。
+ *
+ * 全项目四处要做这个判断（`readJsonFile`、`presentIn`、`config.js` 读配置、
+ * `status.js` 数内容），所以收在这里一份。文件在 merge.js 而不是某个新模块：
+ * 那三个调用方本来就都从 merge.js 拿东西，不用为此新增一条依赖边。
+ *
+ * @param {unknown} err
+ */
+export function isMissingPath(err) {
+  const code = /** @type {NodeJS.ErrnoException} */ (err)?.code;
+  return code === 'ENOENT' || code === 'ENOTDIR';
+}
+
 /**
  * 路径是否存在，**断链也算存在**。
  *
@@ -561,8 +605,8 @@ export function readJsonFile(abs) {
   } catch (e) {
     const code = /** @type {NodeJS.ErrnoException} */ (e).code;
     // ENOENT：真的没有。ENOTDIR：路径中间被一个文件挡住了（`.mcp.json/x`）——
-    // 对我们的用途来说同样等于「这个路径上没有文件」。
-    if (code === 'ENOENT' || code === 'ENOTDIR') {
+    // 对我们的用途来说同样等于「这个路径上没有文件」（判据见 isMissingPath）。
+    if (isMissingPath(e)) {
       return { exists: false, empty: false, bom: false, value: {}, error: null };
     }
     // 其余一律是「有东西，但读不到」。**绝不能降级成「不存在」**：那会让调用方
@@ -708,13 +752,27 @@ export function applyMerge({ projectRoot, tool, kind, sources, prev, keep = [],
   const problems = sourceProblems.map(tag);
   const warnings = sourceWarnings.map(tag);
 
-  /** 收工：把已经攒下的诊断带上，别让调用方以为一切正常 */
+  /**
+   * 收工：把已经攒下的诊断带上，别让调用方以为一切正常。
+   *
+   * **`recorded` 的默认值是「上一轮那份」，不是空。** 走到这几条早退路径
+   * （目标是链接 / 是目录 / 读不了）时文件一个字节都没动过，而
+   * **「没动过」不等于「不是我们写的」**——抹掉归属是不可逆的：下一轮 `prev`
+   * 成了 `{}`，那几个 id 立刻落进「与记录之外的 server 重名」那一支，sync 会
+   * 劝用户「删掉那一份，或写进 protect」，而那份本来就是它自己写的。
+   *
+   * 触发方式简单到离谱（实测过）：`.mcp.json` 里多一个尾逗号 → 读不了 →
+   * 归属当场消失，把文件修好也回不来。
+   *
+   * 同一条口径在 mergeMcp / mergeHooks 里也写着（读不懂现场时 `recorded: {...prev}`），
+   * 只有这里漏了。写失败那条路仍然显式传 `recorded`（那时确实是我们算出来的新归属）。
+   */
   const done = (extra = {}) => ({
     rel: target.rel,
     verified: target.verified,
     changed: false,
     created: false,
-    recorded: {},
+    recorded: { ...prev },
     problems,
     conflicts: [],
     warnings,
@@ -848,6 +906,31 @@ export function checkMerge({ projectRoot, tool, kind, sources, prev, keep = [] }
 // 按 [工具 × 类型] 展开
 // ---------------------------------------------------------------------------
 
+/**
+ * 把 `agents.json` 的 `protect` 折算成**合并层**的「整个不碰」名单。
+ *
+ * `protect` 是条目层的写法（`"hook:dept-hooks"`），合并层按目录分组（`hooks`），
+ * 中间要过一次 `ITEM_KINDS` 的映射。
+ *
+ * **这段原先在 sync / status / doctor 里各写了一遍**——三份一模一样的语义判断。
+ * 加一类合并内容时漏改任何一处，那一处的 `protect` 就会静默失效（用户以为锁上了，
+ * 实际照删），而这正是 `ITEM_KINDS` 那张表存在的理由。
+ *
+ * @param {string[]} [protect]
+ * @returns {Record<string, string[]>} 目录名 → 锁住的 id
+ */
+export function keepByProtect(protect = []) {
+  /** @type {Record<string, string[]>} */
+  const out = Object.fromEntries(MERGE_KINDS.map((d) => [d, /** @type {string[]} */ ([])]));
+  for (const key of protect) {
+    const colon = key.indexOf(':');
+    if (colon === -1) continue;
+    const dir = ITEM_KINDS[key.slice(0, colon)]?.dir;
+    if (dir && MERGE_KINDS.includes(dir)) out[dir].push(key.slice(colon + 1));
+  }
+  return out;
+}
+
 /**
  * 一次完整的合并：声明了的每个工具 × 每一类内容，各走一遍 `applyMerge`。
  *
@@ -997,8 +1080,7 @@ export function presentIn(projectRoot, dir) {
   try {
     names = fs.readdirSync(path.resolve(projectRoot, CONTENT_ROOT, dir));
   } catch (e) {
-    const code = /** @type {NodeJS.ErrnoException} */ (e).code;
-    if (code === 'ENOENT' || code === 'ENOTDIR') return [];
+    if (isMissingPath(e)) return [];
     return null;
   }
   return names.filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -'.json'.length));
@@ -1108,3 +1190,66 @@ export function checkMergeAll({
 
   return out;
 }
+
+/**
+ * `status` / `doctor` 共用的「合并产物」只读检查。
+ *
+ * 两个命令原先各写一遍（各三十多行），只有文案不同：读记录 → `presentIn` →
+ * 按 `protect` 折算 keep → `checkMergeAll` → 没有合并目标的工具 → 未实证的路径。
+ * 文案各写各的没问题，**判断必须是同一份**——两处各写一套的下场，就是
+ * `checkMergeAll` 注释里记的那种「status 报 drift、sync 故意不写，用户卡在
+ * 退出码 1 没有任何命令能修好」。
+ *
+ * @param {{
+ *   projectRoot: string,
+ *   config: {tools: string[], protect: string[]},
+ *   record: {usable: boolean, installed: string[], merged?: Record<string, any>},
+ * }} input
+ */
+export function checkMergeView({ projectRoot, config, record }) {
+  const merged = record?.merged ?? {};
+  const present = Object.fromEntries(MERGE_KINDS.map((d) => [d, presentIn(projectRoot, d)]));
+  const presentCount = MERGE_KINDS.reduce((n, d) => n + (present[d]?.length ?? 0), 0);
+  // 「读不了」和「是空的」是两件事：前者我们根本不知道里面有什么，
+  // 也就答不了「该合的合了没有」——调用方要各自说一句，别当成空
+  const unreadable = MERGE_KINDS.filter((d) => present[d] === null);
+
+  /** 该工具根本没有这一类内容的合并目标（codex 的 mcp）——删掉 status 里那句
+   *  「合并器未实现」之后，这是唯一还会为「装了不生效」说话的地方 */
+  const unsupported = [];
+  for (const tool of config.tools) {
+    for (const dir of MERGE_KINDS) {
+      if (mergeTarget(tool, dir)) continue;
+      const count = present[dir]?.length ?? 0;
+      if (count > 0) unsupported.push({ tool, dir, count });
+    }
+  }
+
+  /** 没实证的路径（目前只有 Trae）——不能报得跟 Claude 那条一样肯定 */
+  const unverified = [];
+  for (const tool of config.tools) {
+    for (const dir of mergeKindsOf(tool)) {
+      const t = mergeTarget(tool, dir);
+      if (t && !t.verified) unverified.push({ tool, rel: t.rel });
+    }
+  }
+
+  return {
+    present,
+    presentCount,
+    unreadable,
+    /** 这一节有没有值得显示的东西——空项目不该因为「文件不存在」吃一笔警告 */
+    hasWork: presentCount > 0 || unreadable.length > 0 || Object.keys(merged).length > 0,
+    rows: checkMergeAll({
+      projectRoot,
+      tools: config.tools,
+      sourcesByKind: Object.fromEntries(
+        MERGE_KINDS.map((d) => [d, sourcesFromDisk(projectRoot, record, d)]),
+      ),
+      keepByKind: keepByProtect(config.protect),
+      prevMerged: merged,
+    }),
+    unsupported,
+    unverified,
+  };
+}