agent-syncer 0.1.1 → 0.1.2

package/lib/record.js

@@ -1,8 +1,11 @@
 // @ts-check
 import fs from 'node:fs';
 import path from 'node:path';
-import { projectItemPath } from './install.js';
-import { SUPPORT_DIR, parseItem } from './manifest.js';
+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';
 
 /**
@@ -164,6 +167,11 @@ function mergedMap(value) {
  * 读记录。文件不存在、坏了、版本不认识，一律当作「没有记录」——
  * 那是保守方向：没有记录时什么都不会删。
  *
+ * ⚠️ 「当作没有记录」对**删除**是保守的，对**归属**却是破坏性的：sync 拿到
+ * 一份 unusable 的记录，紧接着就会用一份全新的把它覆盖掉，`merged` 里记的归属
+ * 全丢（现场还在文件里，但那之后本工具认不出它是自己写的了）。所以调用方
+ * 读到 `reason` 时应当先 `backupUnreadableRecord` 留个档再重建。
+ *
  * @param {string} projectRoot
  * @returns {{usable: boolean, reason: string|null, installed: string[], scripts: string[], merged: Record<string, any>}}
  */
@@ -177,7 +185,10 @@ export function readRecord(projectRoot) {
   /** @type {any} */
   let raw;
   try {
-    raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    // 先去 BOM 再解析：Windows 上记事本、PowerShell 的 `>` 都会写带 BOM 的 UTF-8，
+    // 而 JSON.parse 见 BOM 直接抛——一份完全正常的记录会因此被判成「不可用」，
+    // 后果是清理静默失效 + 合并归属全丢。config.js 早就防着这一手，这里原先漏了。
+    raw = JSON.parse(stripBom(fs.readFileSync(p, 'utf8')));
   } catch (e) {
     return {
       ...empty,
@@ -228,8 +239,17 @@ export function planRemovals(projectRoot, record, wanted) {
 
   for (const key of record.installed) {
     if (wanted.items.includes(key) || protectedKeys.has(key)) continue;
-    const { kind, id } = parseItem(key);
-    const abs = projectItemPath(projectRoot, kind, id);
+    // 名字都解析不了的，映射不到任何路径，谈不上删——跳过。
+    // **绝不能让它把整条命令崩掉**：记录是手改得坏的东西，`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 });
   }
 
@@ -371,10 +391,70 @@ export function checkRecord(projectRoot, record) {
   const check = (key, abs) => out.push({ key, abs, exists: fs.existsSync(abs) });
 
   for (const key of record.installed) {
-    const { kind, id } = parseItem(key);
-    check(key, projectItemPath(projectRoot, kind, id));
+    // 同 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;
+  }
+}

package/lib/source.js

@@ -35,6 +35,79 @@ export function hasGit() {
   return res.status === 0;
 }
 
+/**
+ * `git clone` 的超时（毫秒）。
+ *
+ * `GIT_TERMINAL_PROMPT=0` 堵的是「停下来等人输密码」，堵不住**网络黑洞**——
+ * 连得上、但不回话（代理 / VPN 不通、对面的 git server 挂着、被墙的 host）。
+ * 那种情况下 clone 会一直等下去，在 CI 或 postinstall 里就是永久挂起。
+ *
+ * 比 `ls-remote` 那个 15 秒宽松得多：那一步是「问了才用」的下拉列表，早点放弃没损失；
+ * 这一步**失败就是整条 sync 失败**，而内容仓库可能不小、浅克隆也不一定快。
+ * 60 秒远大于实测（内容仓库不到 1 秒），等于「只有真的连不上才会触发」。
+ *
+ * 超时之后**不重试、也不退回上次的内容**：后者要把缓存引回来，而缓存正是
+ * `fetchRepo` 刻意不要的东西。直接报错，让用户知道是网络而不是他的 URL 写错了。
+ */
+const CLONE_TIMEOUT_MS = 60_000;
+
+/** 这个 spawnSync 结果是不是「超时被杀」。超时时 `status` 是 null、`error.code` 是 ETIMEDOUT */
+function isTimeout(res) {
+  return /** @type {any} */ (res.error)?.code === 'ETIMEDOUT';
+}
+
+/**
+ * 第一次 clone 失败之后，要不要退回**完整克隆**再试一次。
+ *
+ * 退回的理由只有一个：`--branch` 不认裸 SHA，那一次失败得快且无辜，换完整克隆是正解。
+ * 所以**超时不在此列**——超时说明网络已经不行了，而完整克隆（没有 `--depth 1`）
+ * 比刚才那次更慢，再发起一次等于把一次黑洞拖成两次。
+ *
+ * 判据单独拿出来，是因为它值得被钉死，而端到端**造不出**这个场景：要造「连得上、
+ * 不回话」，得有一个只接受连接、永不回话的本地 server，可本机实测下来 git 对
+ * loopback 的连接根本不完成（对**正在监听**的 server 也一样），代理 / 防火墙各家
+ * 又不一样——那种测试会变成环境的函数。
+ *
+ * @param {any} res @param {string|null|undefined} ref
+ */
+export function shouldRetryFullClone(res, ref) {
+  if (!ref) return false; // 没有 ref 就没有「--branch 不认 SHA」这回事
+  if (res.error) return false; // 超时、被信号杀掉、git 起不来——都不是 ref 的锅
+  return res.status !== 0;
+}
+
+/**
+ * 按 ref 取一份克隆；必要时退回完整克隆再检出。
+ *
+ * 把执行方式 (`run`) 从参数传进来，**只为能测**：这段的分支（`--branch` 不认裸 SHA、
+ * 超时不重试）只有「克隆真的失败了」才走得到，而真造一次失败要么靠网络、要么靠一个
+ * 挂住的假 git，两头都不稳。第一版就是因为它内联在 `fetchRepo` 里测不着，于是写了条
+ * 「耗时小于 1 秒」的假测试——**还原掉整个防重试逻辑，它照样是绿的**。
+ *
+ * 导出也是为了测。`fetchRepo` 用的是同一个函数，不是复制一份。
+ *
+ * @param {{
+ *   run: (args: string[], timeoutMs?: number) => any,
+ *   url: string, dest: string, ref?: string|null, timeoutMs: number,
+ * }} p
+ * @returns {any} 最后一次 `run` 的结果
+ */
+export function cloneWithFallback({ run, url, dest, ref, timeoutMs }) {
+  /** @type {string[]} */
+  const args = ['clone', '--quiet', '--depth', '1'];
+  if (ref) args.push('--branch', ref);
+  args.push('--', url, dest);
+
+  const first = run(args, timeoutMs);
+  if (!shouldRetryFullClone(first, ref)) return first;
+
+  // `--branch` 只认分支名和标签名，不认裸 SHA。这时退回完整克隆再检出。
+  // 失败时可能留下半个目标目录，重试前必须先清掉，否则克隆会因「目录非空」再失败一次。
+  fs.rmSync(dest, { recursive: true, force: true });
+  const full = run(['clone', '--quiet', '--', url, dest], timeoutMs);
+  return full.status === 0 ? run(['-C', dest, 'checkout', '--quiet', '--detach', ref]) : full;
+}
+
 /**
  * 把一个 git 仓库的某个 ref 取到临时目录。
  *
@@ -44,10 +117,11 @@ export function hasGit() {
  * **`GIT_TERMINAL_PROMPT=0` 是必须的**：否则遇到需要凭据的仓库时 git 会停下来等输入，
  * 在 CI 或 postinstall 里就是永久挂起——和交互式提示一样危险。
  *
- * @param {{url: string, ref?: string|null}} opts
+ * @param {{url: string, ref?: string|null, timeoutMs?: number}} opts
+ *   `timeoutMs` 只为测试而开：正常调用别传，用默认值（见 `CLONE_TIMEOUT_MS`）。
  * @returns {{root: string, cleanup: () => void}}
  */
-export function fetchRepo({ url, ref }) {
+export function fetchRepo({ url, ref, timeoutMs = CLONE_TIMEOUT_MS }) {
   if (!hasGit()) {
     throw new Error('找不到 git 命令。请先安装 git，或把 content 指向一个本地已克隆的目录。');
   }
@@ -62,35 +136,33 @@ export function fetchRepo({ url, ref }) {
     GIT_ASKPASS: 'echo',
   };
 
-  /** @param {string[]} args */
-  const run = (args) =>
+  /**
+   * @param {string[]} args @param {number} [timeoutMs]
+   *   `timeoutMs` 只在 clone 那条路上给。`checkout` 是纯本地操作，套上超时没有意义。
+   */
+  const run = (args, timeoutMs) =>
     spawnSync('git', args, {
       encoding: 'utf8',
       env: baseEnv,
       // 不用 inherit：clone 的进度输出对使用者没有价值，失败时我们再完整打印 stderr
       stdio: ['ignore', 'pipe', 'pipe'],
+      ...(timeoutMs ? { timeout: timeoutMs } : {}),
     });
 
-  /** @type {string[]} */
-  const cloneArgs = ['clone', '--quiet', '--depth', '1'];
-  if (ref) cloneArgs.push('--branch', ref);
-  cloneArgs.push('--', url, dest);
-
-  let res = run(cloneArgs);
-
-  // `--branch` 只认分支名和标签名，不认裸 SHA。这时退回完整克隆再检出。
-  // 失败时可能留下半个目标目录，重试前必须先清掉，否则克隆会因「目录非空」再失败一次。
-  if (res.status !== 0 && ref) {
-    fs.rmSync(dest, { recursive: true, force: true });
-    const full = run(['clone', '--quiet', '--', url, dest]);
-    res =
-      full.status === 0
-        ? run(['-C', dest, 'checkout', '--quiet', '--detach', ref])
-        : full;
-  }
+  const res = cloneWithFallback({ run, url, dest, ref, timeoutMs });
 
   if (res.status !== 0) {
     cleanup();
+    // 超时说成「拉取失败」，用户第一反应是去查自己的 URL 写错了没有。
+    // 这是两回事：地址是对的，是网络没回话。
+    if (isTimeout(res)) {
+      throw new Error(
+        `拉取超时：${url}${ref ? ` @ ${ref}` : ''}\n` +
+          `  git 连上了，但 ${Math.round(timeoutMs / 1000)} 秒没有回话——` +
+          '多半是代理 / VPN 不通，或者对面的 git server 挂了。\n' +
+          '  也可以把 content 指向一个本地已克隆的目录：不联网、更快，改完内容立刻能试。',
+      );
+    }
     const detail = (res.stderr || res.stdout || '').trim();
     throw new Error(
       `拉取失败：${url}${ref ? ` @ ${ref}` : ''}\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-syncer",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "把 .agents/ 下的 AI 资产（skills / rules / commands）分发到 Claude Code、Trae、Codex 等工具的配置目录",
   "type": "module",
   "bin": {