agent-syncer 0.1.0 → 0.1.2

package/lib/commands/sync.js

@@ -0,0 +1,555 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_FILENAME, loadConfig } from '../config.js';
+import { applyInstall, findOrphans, planInstall } from '../install.js';
+import {
+  RECORD_REL,
+  backupUnreadableRecord,
+  carryOver,
+  isTracked,
+  planRemovals,
+  readRecord,
+  snapshotRecord,
+  writeRecord,
+} from '../record.js';
+import {
+  ITEM_KINDS,
+  SUPPORT_DIR,
+  groupByKind,
+  listBundles,
+  loadRepo,
+  resolveSelection,
+} from '../manifest.js';
+import { dim, fail, info, ok, plain, rel, title, warn } from '../log.js';
+import { isInteractive } from '../prompt.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';
+import { run as runLink } from './link.js';
+
+/** 列出可选模板，并告诉用户怎么选 */
+function printBundles(repoRoot) {
+  const bundles = listBundles(repoRoot);
+  if (bundles.length === 0) {
+    plain('  内容仓库里没有任何 bundle。');
+    return;
+  }
+  plain('\n  可用模板：');
+  for (const b of bundles) {
+    plain(`    ${b.name.padEnd(16)} ${(b.title ?? '').padEnd(10)} ${dim(b.description ?? '')}`);
+  }
+  plain(
+    `\n  用 ${dim('--bundle=<名字>')} 选（多个用逗号分隔），` +
+      `或写进 ${CONFIG_FILENAME} 的 "bundle" 字段。`,
+  );
+  plain(dim('  只想微调？"include" / "exclude" 可以叠在模板之上，exclude 最后生效。'));
+}
+
+/**
+ * 要透传给 `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 合并进各工具自己的配置文件。
+ *
+ * **期望内容取自 `plan` 的 `from`（内容仓库里那条路径），不是读 `.agents/`。**
+ * `--dry-run` 时 `applyInstall` 没执行，`.agents/mcp/foo.json` 可能还是上一轮的
+ * 旧内容、甚至根本不存在——从那儿读会让预演报「无变化」而真跑大改，或者报
+ * 「内容缺失」。
+ *
+ * 锁住的条目（`protect`）整个不参与合并：既不写入，也不摘除。
+ *
+ * @param {{
+ *   cwd: string, plan: any[], config: any, record: any, dryRun: boolean, prune: boolean,
+ * }} input
+ */
+function runMerge({ cwd, plan, config, record, dryRun, prune }) {
+  /** @type {Record<string, Record<string, string>>} */
+  const sourcesByKind = {};
+
+  // 注意 `plan` 里**不会有被 protect 锁住的条目**（sync 早就把它们滤掉了），
+  // 所以这里不必再判一次 protect。锁住的那些由 `keepByProtect` 单独收：它们不在
+  // plan 里，却很可能已经合并进过工具配置——不显式算进来的话，「锁住它」到了
+  // --prune 就失效，而用户写 protect 的正是「别动这个」。
+  for (const e of plan) {
+    const dir = ITEM_KINDS[e.kind]?.dir;
+    // scripts 没有条目类型，也不合并——它整目录同步，由 hook 按路径引用
+    if (!dir || !MERGE_KINDS.includes(dir)) continue;
+    (sourcesByKind[dir] ??= {})[e.id] = e.from;
+  }
+
+  return {
+    ...applyMergeAll({
+      projectRoot: cwd,
+      tools: config.tools,
+      sourcesByKind,
+      keepByKind: keepByProtect(config.protect),
+      prevMerged: record.merged ?? {},
+      dryRun,
+      prune,
+    }),
+    sourcesByKind,
+  };
+}
+
+/**
+ * 删完残留内容之后，把因此空掉的目录也收掉。
+ *
+ * 只试 `removable` 里那些条目**自己所在的目录**——没动过的目录一概不碰。
+ * `rmdirIfEmpty` 只对空目录成功，所以还有东西留着的目录天然删不掉。
+ *
+ * @param {string} cwd
+ * @param {{key: string, abs: string}[]} removable
+ * @returns {string[]} 被删掉的目录（相对项目根的写法）
+ */
+function pruneEmptyDirs(cwd, removable) {
+  /** @type {string[]} */
+  const out = [];
+  /** @type {Set<string>} */
+  const seen = new Set();
+  let touchedScripts = false;
+
+  for (const r of removable) {
+    // scripts/ 里的相对路径可能带子目录，交给 rmdirTreeIfEmpty 从下往上收
+    if (r.key.startsWith('script:')) {
+      touchedScripts = true;
+      continue;
+    }
+    const dir = path.dirname(r.abs);
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    if (rmdirIfEmpty(dir)) out.push(rel(cwd, dir));
+  }
+
+  if (touchedScripts) {
+    const root = path.resolve(cwd, CONTENT_ROOT, SUPPORT_DIR);
+    for (const d of rmdirTreeIfEmpty(root)) out.push(rel(cwd, d));
+  }
+
+  return out.sort();
+}
+
+/**
+ * agent-syncer sync —— 从内容仓库挑一个模板，装进项目的 .agents/，然后建链接。
+ *
+ * `content` 既可以是本地路径，也可以是 git 地址，自动判别：
+ * 本地路径直接读；git 地址先浅克隆到临时目录，用完即删。
+ *
+ * @param {{cwd: string, flags: Record<string, any>, input?: NodeJS.ReadStream, output?: NodeJS.WriteStream}} ctx
+ */
+export async function run({ cwd, flags, input, output }) {
+  const dryRun = Boolean(flags['dry-run']);
+  const assumeYes = Boolean(flags.yes);
+
+  title(`agent-syncer sync${dryRun ? dim('（--dry-run，不会写盘）') : ''}`);
+  plain(dim(`项目根：${cwd}`));
+
+  let config = loadConfig(cwd);
+
+  // 项目还没配置过，而这里又能问——与其把「agents.json 怎么写」甩回给用户，
+  // 不如当场带他走一遍 init。
+  //
+  // **三条同时成立才走**：没有配置文件 + 是交互终端 + 没给 --yes。
+  // 少一条都保持原来的行为（报错并说明怎么写）：CI、管道、postinstall 里
+  // 弹提示会永久挂住，这是这个仓库里最硬的一条规矩。
+  //
+  // --dry-run 也排除在外，它不是上面三条里的任何一条，但同一个道理：init 的**全部**
+  // 产出就是那份配置文件，一边说「预演，不写盘」一边把配置写下去，是自相矛盾。
+  // 想要配置就先跑 init，或者手写一份——两条路 --dry-run 都会告诉你。
+  //
+  // no-init 是 init 反过来调 sync 时带上的信号，防止两边绕成圈。
+  if (!config.exists && !assumeYes && !dryRun && !flags['no-init'] && isInteractive(input, output)) {
+    // 动态 import：init 反过来要调 sync，静态 import 会绕成环
+    const { run: runInit } = await import('./init.js');
+    const code = await runInit({ cwd, flags: { ...flags, 'no-init': true }, input, output });
+    if (code !== 0) return code;
+
+    // 用户可能改了 content / bundle / links，甚至选了别的工具——重新读一次再往下走。
+    // 还读不到就说明他在 init 里取消了（取消时不写盘），那不是什么错误。
+    config = loadConfig(cwd);
+    if (!config.exists) {
+      plain(dim('没有写配置，就此打住。'));
+      return 0;
+    }
+  }
+
+  // 上一次装了些什么。没有这份记录，内容仓库里删掉的条目就永远清不掉——
+  // 光看文件系统分不出「本工具装的残留」和「用户自己写的」，见 record.js
+  const record = readRecord(cwd);
+  if (record.reason) warn(record.reason);
+
+  // ---- 1. 内容来源 ----
+  const sourceArg = typeof flags.from === 'string' ? flags.from : config.content;
+  if (!sourceArg) {
+    fail('没有指定内容仓库');
+    plain(
+      `  在 ${CONFIG_FILENAME} 里写 ${dim('"content": "<本地路径 或 git 地址>"')}，` +
+        `或用 ${dim('--from=<路径>')}。`,
+    );
+    // 交互终端里本来会先带他走一遍 init，走到这儿只剩 --dry-run 那一种情况。
+    // 说一句，免得他以为这个命令除了报错什么都不会做。
+    if (!config.exists && !assumeYes && isInteractive(input, output)) {
+      plain(dim('  去掉 --dry-run 再跑一次，会先带你走一遍 agent-syncer init。'));
+    }
+    return 1;
+  }
+  const ref = typeof flags.ref === 'string' ? flags.ref : config.ref;
+
+  const remote = isGitUrl(sourceArg);
+
+  // 本地路径 + 写了 ref：**说一句**。ref 只对 git 地址生效，本地路径读的是那个
+  // 目录的工作树——不吭声的话，用户以为钉在某个版本上，实际拿到的是他当前检出的
+  // 那份。这是配置和实际行为对不上，和「漂移」是同一类事，不能静默。
+  const refWarning = localRefWarning(sourceArg, ref);
+  if (refWarning) warn(refWarning);
+  /** @type {string} */
+  let repoRoot;
+  /** @type {(() => void)|null} */
+  let cleanup = null;
+
+  if (remote) {
+    info(`拉取 ${sourceArg}${ref ? ` @ ${ref}` : ''} …`);
+    try {
+      const fetched = fetchRepo({ url: sourceArg, ref });
+      repoRoot = fetched.root;
+      cleanup = fetched.cleanup;
+    } catch (e) {
+      fail(/** @type {Error} */ (e).message);
+      return 1;
+    }
+  } else {
+    repoRoot = path.resolve(cwd, sourceArg);
+  }
+
+  try {
+    // ---- 2. 读仓库 ----
+    /** @type {{name: string, version?: string, root: string}} */
+    let repo;
+    try {
+      repo = loadRepo(repoRoot);
+    } catch (e) {
+      fail(/** @type {Error} */ (e).message);
+      return 1;
+    }
+    ok(
+      `内容仓库：${repo.name}${repo.version ? ` v${repo.version}` : ''}  ` +
+        dim(remote ? `${sourceArg}${ref ? ` @ ${ref}` : ''}` : repoRoot),
+    );
+
+    // ---- 3. 选内容：模板并集 + 项目级 include / exclude ----
+    const bundleFlag =
+      typeof flags.bundle === 'string'
+        ? flags.bundle
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : [];
+    const bundles = bundleFlag.length > 0 ? bundleFlag : config.bundles;
+    const { include, exclude } = config;
+
+    // 一个模板都不选也行——纯靠 include 挑条目就是"自定义"用法
+    if (bundles.length === 0 && include.length === 0) {
+      warn('没有指定要安装的内容');
+      printBundles(repoRoot);
+      return 1;
+    }
+
+    /** @type {string[]} */
+    let items;
+    /** @type {string[]} */
+    let dropped;
+    try {
+      const picked = resolveSelection(repoRoot, { bundles, include, exclude });
+      items = picked.items;
+      dropped = picked.dropped;
+      // exclude 里引用了仓库里没有的条目——不致命，但必须让人看见
+      for (const w of picked.warnings) warn(w);
+    } catch (e) {
+      fail(/** @type {Error} */ (e).message);
+      return 1;
+    }
+
+    if (items.length === 0) {
+      warn('选出来的条目是空的，无事可做');
+      return 0;
+    }
+
+    const what =
+      bundles.length > 0
+        ? `模板 ${bundles.join(' + ')}`
+        : '自定义 include（未使用模板）';
+    const summary = Object.entries(groupByKind(items))
+      .map(([k, v]) => `${ITEM_KINDS[k].label} ${v.length}`)
+      .join('　');
+    ok(`${what}：${items.length} 个条目　${dim(summary)}`);
+    if (include.length > 0 && bundles.length > 0) plain(dim(`    含项目级 include ${include.length} 条`));
+    if (dropped.length > 0) {
+      const shown = dropped.slice(0, 6).join('、');
+      info(
+        `exclude 排除了 ${dropped.length} 项：${shown}` +
+          (dropped.length > 6 ? ` … 还有 ${dropped.length - 6} 项` : ''),
+      );
+    }
+
+    // ---- 4. 算计划 ----
+    // 锁定的条目整个从计划里摘掉：**既不覆盖也不删**。只挡删除是不够的——
+    // sync 仍会把它当普通选中项覆盖掉，用户以为锁上了、内容却被冲了，比不锁更糟。
+    const locked = new Set(config.protect);
+    const keyOf = (e) => (e.kind === 'script' ? `script:${e.id}` : `${e.kind}:${e.id}`);
+
+    const full = planInstall(repoRoot, cwd, items);
+    const plan = full.filter((e) => !locked.has(keyOf(e)));
+    /** scripts/ 整体同步，不参与条目挑选，所以单独取一遍 */
+    const scripts = plan.filter((e) => e.kind === 'script').map((e) => e.id);
+
+    if (locked.size > 0) {
+      info(`锁定 ${locked.size} 项，本工具不会动它们：`);
+      for (const k of config.protect) plain(dim(`    · ${k}`));
+    }
+
+    /** @type {Record<string, typeof plan>} */
+    const by = { new: [], update: [], same: [], blocked: [] };
+    for (const e of plan) (by[e.status] ??= []).push(e);
+
+    // ---- 5. 报告 ----
+    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) {
+        const at = e.linkAt ?? e.to;
+        plain(`  · ${path.relative(cwd, at)}${at === e.to ? '' : dim('（是上层目录）')}`);
+      }
+      // 链接指向的地方很可能还有别的项目在管同一批内容（每个项目的记录各管各的），
+      // 这边写进去、那边 --prune 删掉，会互相踩
+      plain('  那儿可能还有别的项目在管同一批内容。先删掉链接或改用 link 管理，再重跑。');
+      return 1;
+    }
+
+    // ---- 6. 落盘 ----
+    const changed = by.new.length + by.update.length;
+    if (changed === 0) {
+      ok(`内容已是最新（${by.same.length} 项内容一致）`);
+    } else if (dryRun) {
+      info(`将写入 ${changed} 项：新增 ${by.new.length}，更新 ${by.update.length}`);
+    } else {
+      const { written, problems } = applyInstall(plan);
+      ok(`已写入 ${written} 项`);
+      if (problems.length > 0) {
+        title('写入失败');
+        for (const p of problems) plain(`  · ${p.spec}：${p.message}`);
+        return 1;
+      }
+    }
+
+    // ---- 7. 清理：本工具以前装的、这次不再需要的 ----
+    //
+    // 这一节是这套东西里唯一会删用户目录的地方。判定只用明面上的两条：
+    // **记录里说装过**，且**没被 protect 锁住**。
+    // 用户从头自己写的（不在记录里）一律不碰；想保住某个装过的条目，
+    // 就在 agents.json 的 protect 里写上它——不写，--prune 就会删。
+    const prune = Boolean(flags.prune);
+    /**
+     * 这次没删成的要留在新记录里继续跟踪。从记录里抹掉就等于失联：
+     * 下次同步再也说不出「这是本工具装的」，用户漏看一次就永远找不回来了。
+     * @type {string[]}
+     */
+    const carry = [];
+    /** @type {string[]} */
+    const failed = [];
+
+    // 锁住的条目也要留在记录里：它确实是本工具装的，将来从 protect 里去掉
+    // 之后还该认得出它是残留。不留下的话它会变成「不是本工具装的」，那就说错了。
+    if (record.usable) carry.push(...config.protect.filter((k) => isTracked(record, k)));
+
+    if (record.usable) {
+      const removable = planRemovals(cwd, record, { items, scripts, protect: config.protect });
+
+      if (removable.length > 0) {
+        if (!prune) {
+          carry.push(...removable.map((r) => r.key));
+          warn(`有 ${removable.length} 项是以前装的、现在不需要了——不会自动删除`);
+          for (const r of removable.slice(0, 8)) plain(dim(`    · ${r.key}`));
+          if (removable.length > 8) plain(dim(`    … 还有 ${removable.length - 8} 项`));
+          plain(dim('    加 --prune 删掉；要留住其中某个，写进 agents.json 的 protect。'));
+        } else if (dryRun) {
+          carry.push(...removable.map((r) => r.key));
+          info(`将删除 ${removable.length} 项不再需要的内容：${removable.slice(0, 6).map((r) => r.key).join('、')}`);
+        } else {
+          for (const r of removable) {
+            try {
+              fs.rmSync(r.abs, { recursive: true, force: true });
+              ok(`${r.key}  ${dim('已删除（不再需要）')}`);
+            } catch (e) {
+              fail(`${r.key}  删除失败：${/** @type {Error} */ (e).message}`);
+              failed.push(`${r.key}：${/** @type {Error} */ (e).message}`);
+              carry.push(r.key);
+            }
+          }
+          // 收掉因此空掉的目录。git 不跟踪空目录，所以留着不影响版本库；
+          // 但 `.agents/skills/` 空着和不存在在 status 里是两种说法，
+          // 而且删空了却不收，下次 sync 又会把它建出来，看着像没删干净。
+          const emptied = pruneEmptyDirs(cwd, removable);
+          if (emptied.length > 0) info(`顺带收掉空目录：${emptied.join('、')}`);
+        }
+      }
+    }
+
+    // ---- 8. 合并 hooks / mcp ----
+    //
+    // 这两类没法像前四类那样建链接——它们要写进各工具**自己的**配置文件，而
+    // 那些文件里还有用户自己的东西，不能整份覆盖。所以是「读—改—写」，而且
+    // 归属全靠记录验证（见 merge.js 开头那段）。
+    //
+    // 因此这一步必须在 writeRecord **之前**：本轮合并了什么，要和记录一起写下去，
+    // 下一轮才认得出哪些是我们的。
+    const merge = runMerge({ cwd, plan, config, record, dryRun, prune });
+
+    for (const a of merge.applied) {
+      const line = `${a.rel}  ${dim(`${a.kind} 合并`)}`;
+      if (dryRun) info(`将写入 ${line}`);
+      else if (a.created) ok(`新建 ${line}`);
+      else info(`更新 ${line}`);
+
+      // 没实证的路不能报得跟 Claude 那条一样肯定
+      if (!a.verified) {
+        plain(dim(`    ⚠️ ${TOOLS[a.tool].label} 的这条路径未经实证（本机没装），可能不生效`));
+      }
+    }
+
+    for (const w of merge.warnings) warn(w);
+
+    // 冲突 = 「解析下来本该是我们的，但现场不像」。保留 + 报出来，绝不覆盖回去。
+    for (const c of merge.conflicts) {
+      warn(`${TOOLS[c.tool].label} · ${c.rel}：有 ${c.messages.length} 条本工具没动`);
+      for (const m of c.messages) plain(dim(`    · ${m}`));
+    }
+
+    if (merge.stale.length > 0) {
+      const n = merge.stale.reduce((s, x) => s + x.ids.length, 0);
+      if (prune) {
+        if (dryRun) info(`将摘掉 ${n} 条不再需要的合并产物`);
+      } else {
+        // 和内容层一个口径：默认只报告不删
+        warn(`有 ${n} 条以前合并进工具配置的、现在不需要了——不会自动摘除`);
+        for (const s of merge.stale) {
+          plain(dim(`    · ${TOOLS[s.tool].label} ${s.kind}：${s.ids.join('、')}`));
+        }
+        plain(dim('    加 --prune 摘掉；要留住其中某个，写进 agents.json 的 protect。'));
+      }
+    }
+
+    // 删掉 status 里那句「合并器未实现」之后，这里是唯一还会为这种情况说话的地方：
+    // 内容装上了，但声明的工具里没有一个能承接它。
+    for (const u of merge.unsupported) {
+      warn(`${TOOLS[u.tool].label} 没有 ${u.kind} 的合并目标——这 ${u.count} 条装了也不会生效`);
+      plain(
+        dim(`    内容在 ${CONTENT_ROOT}/${u.kind}/ 里存着。该工具的配置格式本工具暂不支持，`) +
+          dim('需要手工处理。'),
+      );
+    }
+
+    // 写进去 ≠ 生效。这是最容易让人查半天的一条。
+    //
+    // 判据是「有没有 MCP 内容要合」，**不是「本轮有没有变化」**：新克隆的机器上
+    // `.mcp.json` 已经提交在仓库里、内容一模一样，本轮恰恰不会有任何变化——
+    // 而那正是最需要这句提醒的时候。
+    if (config.tools.includes('claude') && Object.keys(merge.sourcesByKind.mcp ?? {}).length > 0) {
+      plain('');
+      plain(dim('  提醒：MCP server 还要在 Claude Code 里**逐条批准**才会生效。'));
+      plain(dim('        批准记录存在你本机的 ~/.claude.json，不随仓库共享——队友要各自批一次。'));
+    }
+
+    if (merge.problems.length > 0) {
+      title('合并失败');
+      for (const p of merge.problems) plain(`  · ${p}`);
+    }
+
+    // 记录必须跟着本次结果重写，否则下次同步会拿旧账来对。
+    // 注意**不能放进上面的 `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));
+    }
+
+    // ---- 9. 本地多余项（只报告，不删）----
+    //
+    // 有记录之后就能分清两类了：记录里有的上面已经处理过；记录里没有的
+    // 就是用户自己写的，没必要每跑一次就唠叨一遍。还没记录时（首次运行、
+    // 或记录坏了）分不清，沿用老行为全部列出来。
+    const orphans = findOrphans(cwd, items);
+    const known = new Set(record.installed);
+    const theirs = orphans.filter((o) => !known.has(o));
+    if (theirs.length > 0) {
+      if (!record.usable) {
+        warn(`.agents/ 下有 ${theirs.length} 项不在本模板里——不会自动删除`);
+        for (const o of theirs.slice(0, 8)) plain(dim(`    · ${o}`));
+        if (theirs.length > 8) plain(dim(`    … 还有 ${theirs.length - 8} 项`));
+        plain(dim('    可能是上个模板的残留，也可能是你自己加的。确认后手工处理。'));
+      } else {
+        plain(dim(`（另有 ${theirs.length} 项不在本工具记录里，未做处理）`));
+      }
+    }
+
+    if (failed.length > 0) {
+      title('删除失败');
+      for (const f of failed) plain(`  · ${f}`);
+      return 1;
+    }
+    if (!record.usable && !dryRun) {
+      plain(dim(`（本次会写下 ${RECORD_REL}，下次起就能认出哪些是本工具装的了）`));
+    }
+
+    // ---- 10. 建链接 ----
+    if (dryRun) {
+      plain(dim('\n这是预演，未写盘。去掉 --dry-run 即可实际执行。'));
+      // 预演也要如实反映故障：同一份现场，`sync` 退 1 而 `sync --dry-run` 退 0，
+      // 就是「预演是绿的、真跑是红的」——CI 里只看退出码的人会被骗一道。
+      // 「同一现场同一结论」是 merge.js 里 checkMergeAll 那段定下的口径。
+      return merge.problems.length > 0 ? 1 : 0;
+    }
+
+    plain('');
+    // **只透传 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;
+  } finally {
+    // 拉取下来的临时目录用完即删——无论成功、失败还是抛错
+    if (cleanup) cleanup();
+  }
+}