agent-syncer 0.1.0 → 0.1.2

package/lib/record.js

@@ -0,0 +1,460 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { SUPPORT_DIR, parseItem, projectItemPath } from './manifest.js';
+// BOM 处理只有一份实现（见 merge.js 里 stripBom 的注释）。这个文件的依赖方向
+// 又一次「逆」——记「装过什么」的模块去借处理 JSON 的工具。可以接受：真实
+// 依赖是「JSON 文本怎么读」这件小事，而这份知识散成好几份正是踩过的坑。
+import { stripBom } from './merge.js';
+import { CONTENT_ROOT } from './target.js';
+
+/**
+ * 「装过什么」的记录文件。
+ *
+ * ## 为什么必须有它
+ *
+ * 光靠文件系统推不出来。看起来有条捷径：「`.agents/` 里有、内容仓库里没有 ⇒
+ * 是用户自己建的，别动」。但它恰恰在最要紧的情况下失效——**内容仓库某次
+ * 把某个技能整个删掉了**，那份内容真的源里已经没有它了，这个启发式会把它
+ * 误判成用户内容而永久保留。sync 只会说一句「不在本模板里——不会自动删除」，
+ * 用户既不知道它是谁装的，也没有任何办法把它清掉。
+ *
+ * 更要命的是 `scripts/`：`findOrphans` 明确跳过了它，所以内容仓库删掉一个脚本，
+ * 项目里那份会**一声不吭**地留着。
+ *
+ * 所以需要一个记录，回答「这些内容是本工具放进去的吗」。
+ *
+ * ## 只记名字，不记内容指纹
+ *
+ * 一开始这里存的是每条内容的哈希，用来判断「用户改过没有」。去掉了，两个原因：
+ *
+ * 1. **换行符**。`core.autocrlf` 的 Windows 检出会把同一份内容算成不同哈希，
+ *    于是记录会在 LF / CRLF 两种值之间来回翻，而每个项目都提交一份这个文件。
+ *    误判的方向倒是保守（该删的变成不删），但翻来覆去本身就是冲突源。
+ * 2. **它让记录频繁变动**。内容一更新哈希就变，等于每次内容改动都在每个项目的
+ *    仓库里多出一份 diff，而那份改动 `.agents/` 里本来就看得见。
+ *
+ * 代价是「用户改过的残留」不再被自动认出来。补法是在 `agents.json` 里**显式声明**
+ * `protect`——把「猜」换成「说」，也是这个项目一贯的口径：拿不准就不动，拿不准
+ * 就让用户讲。
+ *
+ * ## 只记名字，也不记内容仓库地址
+ *
+ * 这个文件是**要提交进版本库**的（它描述的是 `.agents/` 的内容，与机器无关；
+ * 不提交的话队友克隆后清理功能等于失效）。因此里面绝不能出现内部 git 地址——
+ * 部门规则第 3 条，也避免每个项目仓库都带上一份内部坐标。
+ *
+ * ## 还有一个 `merged`：合并产物的归属
+ *
+ * skills / rules 那几类落在 `.agents/` 里，`installed` 说「这个文件是本工具放的」
+ * 就够了。但 hooks / mcp 要**合并进各工具自己的配置文件**（`.mcp.json`、
+ * `.claude/settings.json`），那些文件里还有用户自己的东西——于是问题变成了
+ * 「配置文件里的**那一条**是不是我们写的」，而 `installed` 回答不了：
+ *
+ * - 用户 `.mcp.json` 里本来就有一个同名 server，我们报冲突没敢写，但
+ *   `installed` 照样会记上 `mcp:foo`（`.agents/mcp/foo.json` 确实是装了的），
+ *   于是**下一轮就把它当成自己人覆盖掉**——静默丢掉用户的东西
+ * - 用户手删了 `.agents/mcp/foo.json`，`planRemovals` 因为存在性检查不成立
+ *   而不认它，配置文件里那一条就**永久残留**
+ *
+ * 所以另记一份 `merged`：**我们到底往哪个文件里写了什么**。判定因此升级成
+ * 「记录说是我写的，**且现场确实还是我写的那份**」才动——现场对不上就判为
+ * 用户编辑过，保留并警告。
+ *
+ * 存的是**解析后的结构**，不是原文、也不是哈希。所以上面「去掉哈希」那两条理由
+ * 在这里不成立：`core.autocrlf` 影响的是字节，解析出来的结构是一样的。
+ * 比较一律走**无序**深度相等——工具重排键序不该被当成「内容变了」。
+ */
+export const RECORD_REL = `${CONTENT_ROOT}/.agent-sync.json`;
+
+/**
+ * 记录文件的格式版本，与内容仓库的 schemaVersion 无关。
+ * 2 = 去掉内容指纹，`installed` / `scripts` 改成字符串数组。
+ */
+export const RECORD_SCHEMA = 2;
+
+/** @param {string} projectRoot */
+export function recordPath(projectRoot) {
+  return path.resolve(projectRoot, RECORD_REL);
+}
+
+/** @param {string} projectRoot @param {string} rel */
+function scriptPath(projectRoot, rel) {
+  return path.resolve(projectRoot, CONTENT_ROOT, SUPPORT_DIR, rel);
+}
+
+/** 只留字符串、去重、排序——手改坏了的记录不该让整件事崩掉 */
+function strList(value) {
+  if (!Array.isArray(value)) return [];
+  /** @type {string[]} */
+  const out = [];
+  for (const v of value) if (typeof v === 'string' && !out.includes(v)) out.push(v);
+  return out.sort();
+}
+
+/** JSON 意义上的「一个对象」——null 和数组都不算 */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * 换行符归一，**只为比较用**。写出去的一律是 LF。
+ *
+ * `core.autocrlf=true` 的检出会让盘上的记录变成 CRLF，而我们是按 LF 拼的。
+ * 按字节比的话，每次重新检出之后第一次 sync 都会重写这个文件，git 里永远
+ * 挂着一份 modified——正是上面「去掉哈希」那段要躲的病，换了个渠道又回来了。
+ * 归一之后只比不管：盘上是什么换行就让它留着。
+ *
+ * @param {string|null} s
+ */
+function eol(s) {
+  return s === null ? null : s.replace(/\r\n/g, '\n');
+}
+
+/**
+ * 归一化 `merged`。
+ *
+ * 结构：`{ <工具>: { mcp: {<id>: server对象}, hooks: {<id>: {<事件名>: [条目]}} } }`
+ *
+ * 手改坏的部分一律丢掉——一份被改坏的记录不该把 sync 弄崩。丢掉的方向是
+ * 保守的：不认的条目就等于「不是本工具写的」，于是不碰。
+ *
+ * @param {any} value
+ * @returns {Record<string, any>}
+ */
+function mergedMap(value) {
+  if (!isPlainObject(value)) return {};
+
+  /** @type {Record<string, any>} */
+  const out = {};
+  for (const [tool, kinds] of Object.entries(value)) {
+    if (!isPlainObject(kinds)) continue;
+    /** @type {Record<string, any>} */
+    const kept = {};
+
+    if (isPlainObject(kinds.mcp)) {
+      /** @type {Record<string, any>} */
+      const mcp = {};
+      for (const [id, server] of Object.entries(kinds.mcp)) {
+        if (isPlainObject(server)) mcp[id] = server;
+      }
+      // 空的不记。「一条都没写」和「没有这一项」是同一件事，
+      // 记成空对象只会让这份要提交的文件里多出一堆 {}",{}。
+      if (Object.keys(mcp).length > 0) kept.mcp = mcp;
+    }
+
+    if (isPlainObject(kinds.hooks)) {
+      /** @type {Record<string, any>} */
+      const hooks = {};
+      for (const [id, events] of Object.entries(kinds.hooks)) {
+        if (!isPlainObject(events)) continue;
+        /** @type {Record<string, any>} */
+        const ev = {};
+        for (const [name, entries] of Object.entries(events)) {
+          if (Array.isArray(entries)) ev[name] = entries;
+        }
+        if (Object.keys(ev).length > 0) hooks[id] = ev;
+      }
+      if (Object.keys(hooks).length > 0) kept.hooks = hooks;
+    }
+
+    if (Object.keys(kept).length > 0) out[tool] = kept;
+  }
+  return out;
+}
+
+/**
+ * 读记录。文件不存在、坏了、版本不认识，一律当作「没有记录」——
+ * 那是保守方向：没有记录时什么都不会删。
+ *
+ * ⚠️ 「当作没有记录」对**删除**是保守的，对**归属**却是破坏性的：sync 拿到
+ * 一份 unusable 的记录，紧接着就会用一份全新的把它覆盖掉，`merged` 里记的归属
+ * 全丢（现场还在文件里，但那之后本工具认不出它是自己写的了）。所以调用方
+ * 读到 `reason` 时应当先 `backupUnreadableRecord` 留个档再重建。
+ *
+ * @param {string} projectRoot
+ * @returns {{usable: boolean, reason: string|null, installed: string[], scripts: string[], merged: Record<string, any>}}
+ */
+export function readRecord(projectRoot) {
+  /** @type {{usable: boolean, reason: string|null, installed: string[], scripts: string[], merged: Record<string, any>}} */
+  const empty = { usable: false, reason: null, installed: [], scripts: [], merged: {} };
+
+  const p = recordPath(projectRoot);
+  if (!fs.existsSync(p)) return empty;
+
+  /** @type {any} */
+  let raw;
+  try {
+    // 先去 BOM 再解析：Windows 上记事本、PowerShell 的 `>` 都会写带 BOM 的 UTF-8，
+    // 而 JSON.parse 见 BOM 直接抛——一份完全正常的记录会因此被判成「不可用」，
+    // 后果是清理静默失效 + 合并归属全丢。config.js 早就防着这一手，这里原先漏了。
+    raw = JSON.parse(stripBom(fs.readFileSync(p, 'utf8')));
+  } catch (e) {
+    return {
+      ...empty,
+      reason: `${RECORD_REL} 不是合法的 JSON（${/** @type {Error} */ (e).message}），本次按「没有记录」处理`,
+    };
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ...empty, reason: `${RECORD_REL} 的顶层必须是一个对象，本次按「没有记录」处理` };
+  }
+  if (raw.schemaVersion !== RECORD_SCHEMA) {
+    return {
+      ...empty,
+      reason:
+        `${RECORD_REL} 的 schemaVersion 是 ${JSON.stringify(raw.schemaVersion)}，` +
+        `本工具只支持 ${RECORD_SCHEMA}，本次按「没有记录」处理`,
+    };
+  }
+
+  // merged 缺字段（老记录）→ {}：`.agent-sync.json` 要提交进每个项目的版本库，
+  // 不能因为加了个字段就要求所有人先迁移一遍。
+  return {
+    usable: true,
+    reason: null,
+    installed: strList(raw.installed),
+    scripts: strList(raw.scripts),
+    merged: mergedMap(raw.merged),
+  };
+}
+
+/**
+ * 算出「本工具以前装的、现在不需要了」的东西。
+ *
+ * 判定只需要两条，都来自明面：
+ * - 记录里说装过
+ * - 本次不再选中，且没被 `protect` 锁住
+ *
+ * 本地已经不存在的不返回——它本来就没了，新记录里自然也不会再有。
+ *
+ * @param {string} projectRoot
+ * @param {{installed: string[], scripts: string[]}} record
+ * @param {{items: string[], scripts: string[], protect?: string[]}} wanted
+ * @returns {{key: string, abs: string}[]}
+ */
+export function planRemovals(projectRoot, record, wanted) {
+  const protectedKeys = new Set(wanted.protect ?? []);
+  /** @type {{key: string, abs: string}[]} */
+  const out = [];
+
+  for (const key of record.installed) {
+    if (wanted.items.includes(key) || protectedKeys.has(key)) continue;
+    // 名字都解析不了的，映射不到任何路径，谈不上删——跳过。
+    // **绝不能让它把整条命令崩掉**：记录是手改得坏的东西，`strList` 那边已经
+    // 定过口径「手改坏了的记录不该让整件事崩掉」，这里原先漏了——手写一条
+    // "oops" 就能让 status 直接抛异常。跳过的方向也是保守的：不删。
+    let parsed;
+    try {
+      parsed = parseItem(key);
+    } catch {
+      continue;
+    }
+    const abs = projectItemPath(projectRoot, parsed.kind, parsed.id);
+    if (fs.existsSync(abs)) out.push({ key, abs });
+  }
+
+  for (const rel of record.scripts) {
+    const key = `script:${rel}`;
+    if (wanted.scripts.includes(rel) || protectedKeys.has(key)) continue;
+    const abs = scriptPath(projectRoot, rel);
+    if (fs.existsSync(abs)) out.push({ key, abs });
+  }
+
+  return out;
+}
+
+/**
+ * 给本次装好的内容拍一张记录快照。
+ *
+ * 只记磁盘上确实存在的——记了装不上的，下次会被误当成「需要清理」。
+ * `projectRoot` 就是为了这个存在性检查（以及让调用方不必自己拼路径）。
+ *
+ * `merged` 不是从文件系统推出来的——它记的是「我们往别人文件里写了什么」，
+ * 只能由合并器算好后传进来。默认 `{}`：没有合并能力的那条路径不必关心它。
+ *
+ * @param {string} projectRoot @param {string[]} items @param {string[]} scripts
+ * @param {Record<string, any>} [merged]
+ */
+export function snapshotRecord(projectRoot, items, scripts, merged = {}) {
+  /** @type {string[]} */
+  const installed = [];
+  for (const spec of items) {
+    try {
+      const { kind, id } = parseItem(spec);
+      if (fs.existsSync(projectItemPath(projectRoot, kind, id))) installed.push(spec);
+    } catch {
+      // 名字都解析不了就更不该记
+    }
+  }
+
+  /** @type {string[]} */
+  const s = [];
+  for (const rel of scripts) {
+    if (fs.existsSync(scriptPath(projectRoot, rel))) s.push(rel);
+  }
+
+  return {
+    schemaVersion: RECORD_SCHEMA,
+    installed: strList(installed),
+    scripts: strList(s),
+    merged: mergedMap(merged),
+  };
+}
+
+/**
+ * 写记录。内容没变就不碰文件。
+ *
+ * ⚠️ 这里是**整份重建**的：任何字段在这个字面量里漏掉，下次 sync 就会被静默丢弃。
+ * 加字段时 `readRecord` / `snapshotRecord` / 这里 / `carryOver` 四处都要过一遍。
+ *
+ * @param {string} projectRoot
+ * @param {{installed: string[], scripts: string[], merged?: Record<string, any>}} snapshot
+ * @param {{dryRun?: boolean}} [opts]
+ */
+export function writeRecord(projectRoot, snapshot, opts = {}) {
+  const p = recordPath(projectRoot);
+  const text = `${JSON.stringify(
+    {
+      schemaVersion: RECORD_SCHEMA,
+      installed: strList(snapshot.installed),
+      scripts: strList(snapshot.scripts),
+      merged: mergedMap(snapshot.merged),
+    },
+    null,
+    2,
+  )}\n`;
+
+  /** @type {string|null} */
+  let current = null;
+  try {
+    current = fs.readFileSync(p, 'utf8');
+  } catch {
+    // 不存在，下面照常写
+  }
+
+  const changed = eol(current) !== eol(text);
+  if (changed && !opts.dryRun) {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, text);
+  }
+  return { changed, path: p };
+}
+
+/**
+ * 这次没删成的条目要留在记录里继续跟踪。
+ *
+ * 不能一删了之：它们既不属于本次选择，也不属于用户从头写的东西，
+ * 直接从记录里抹掉就等于失联——下次同步再也说不出「这是本工具装的」，
+ * 用户漏看一次就永远找不回来了。
+ *
+ * `merged` 原样带过，这里不碰它——它是「往别人文件里写了什么」，撤销失败的
+ * 那部分该不该留着，只有合并器自己判断得了。调用方把它放进 snapshot 就是了。
+ *
+ * @param {{installed: string[], scripts: string[], merged?: Record<string, any>}} snapshot
+ * @param {string[]} keys 形如 "skill:x" 或 "script:a.sh"
+ */
+export function carryOver(snapshot, keys) {
+  for (const key of keys) {
+    if (key.startsWith('script:')) {
+      const rel = key.slice('script:'.length);
+      if (!snapshot.scripts.includes(rel)) snapshot.scripts.push(rel);
+    } else if (!snapshot.installed.includes(key)) {
+      snapshot.installed.push(key);
+    }
+  }
+  snapshot.installed = strList(snapshot.installed);
+  snapshot.scripts = strList(snapshot.scripts);
+  return snapshot;
+}
+
+/**
+ * 这条记录跟踪的是不是某个键（`"skill:x"` 或 `"script:a.sh"`）。
+ * @param {{installed: string[], scripts: string[]}} record @param {string} key
+ */
+export function isTracked(record, key) {
+  return key.startsWith('script:')
+    ? record.scripts.includes(key.slice('script:'.length))
+    : record.installed.includes(key);
+}
+
+/**
+ * 记录里跟踪的条目，本地还在不在。
+ * 给 status 用——它没有内容仓库，判断不了「该不该装」，但报得出「还在不在」。
+ *
+ * @param {string} projectRoot
+ * @param {{installed: string[], scripts: string[]}} record
+ */
+export function checkRecord(projectRoot, record) {
+  /** @type {{key: string, abs: string, exists: boolean}[]} */
+  const out = [];
+
+  const check = (key, abs) => out.push({ key, abs, exists: fs.existsSync(abs) });
+
+  for (const key of record.installed) {
+    // 同 planRemovals：名字解析不了就跳过，不能为一条手改坏的名字把 status 打崩
+    // （调用方拿 unparsableKeys 单独把这件事说出来）
+    let parsed;
+    try {
+      parsed = parseItem(key);
+    } catch {
+      continue;
+    }
+    check(key, projectItemPath(projectRoot, parsed.kind, parsed.id));
+  }
+  for (const rel of record.scripts) check(`script:${rel}`, scriptPath(projectRoot, rel));
+
+  return out;
+}
+
+/**
+ * 记录里**名字都解析不了**的条目（`installed` 里那些）。
+ *
+ * 它们映射不到任何路径，所以处置只能是「跳过」——但跳过不等于没有这回事：
+ * 清理功能会因此少管几项，而用户只看到「跟踪 N 项」莫名其妙变少了。
+ * 让调用方说一句，比默默少几条强。
+ *
+ * `scripts` 不在这里：它们记的是相对路径，本来就没有 `类型:名字` 的格式。
+ *
+ * @param {{installed: string[]}} record
+ * @returns {string[]}
+ */
+export function unparsableKeys(record) {
+  /** @type {string[]} */
+  const out = [];
+  for (const key of record.installed) {
+    try {
+      parseItem(key);
+    } catch {
+      out.push(key);
+    }
+  }
+  return out;
+}
+
+/**
+ * 记录读不出来时先留个档，**别让新记录把它直接盖掉**。
+ *
+ * `writeRecord` 是整份重写的。读到一份解析不了的记录（坏 JSON / BOM / 本版本不
+ * 认识的 schemaVersion）就往下写的话，盘上那份就永久没了——而它里面记的是
+ * 「哪些内容是本工具装的」，**没有第二处能推导出来**（见文件开头那段）。
+ * 判据和 config.js 里那条一样：读失败装作不存在、然后接着写，是**进攻方向**。
+ *
+ * 只在还没有 `.bak` 时做一次：反复跑 sync 不该把最初那份越冲越远。
+ * 备份放在记录旁边（`.agents/` 下），托管段只放行 `.agent-sync.json` 这一个
+ * 文件名，所以 `.bak` 不会被提交进版本库。
+ *
+ * @param {string} projectRoot
+ * @returns {string|null} 备份文件的相对路径；没做（没有 / 已存在 / 失败）返回 null
+ */
+export function backupUnreadableRecord(projectRoot) {
+  const p = recordPath(projectRoot);
+  const bak = `${p}.bak`;
+  if (!fs.existsSync(p) || fs.existsSync(bak)) return null;
+  try {
+    fs.copyFileSync(p, bak);
+    return `${RECORD_REL}.bak`;
+  } catch {
+    // 备份不成也不能让 sync 整个失败——下面照常写新记录，只是没留档
+    return null;
+  }
+}