agent-syncer 0.1.0 → 0.1.1

package/lib/record.js

@@ -0,0 +1,380 @@
+// @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 { 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;
+}
+
+/**
+ * 读记录。文件不存在、坏了、版本不认识，一律当作「没有记录」——
+ * 那是保守方向：没有记录时什么都不会删。
+ *
+ * @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 {
+    raw = JSON.parse(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;
+    const { kind, id } = parseItem(key);
+    const abs = projectItemPath(projectRoot, kind, 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) {
+    const { kind, id } = parseItem(key);
+    check(key, projectItemPath(projectRoot, kind, id));
+  }
+  for (const rel of record.scripts) check(`script:${rel}`, scriptPath(projectRoot, rel));
+
+  return out;
+}

package/lib/source.js

@@ -0,0 +1,240 @@
+// @ts-check
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+/**
+ * 判断 `content` 给的是 git 地址还是本地路径。
+ *
+ * 先排除本地路径的写法（Windows 盘符、绝对路径、相对路径），再看协议前缀。
+ * 顺序很重要：`C:/x/foo.git` 以 .git 结尾，但它显然是本地路径。
+ *
+ * @param {string} value
+ */
+export function isGitUrl(value) {
+  const s = value.trim();
+  if (s === '') return false;
+
+  // 本地路径的三种写法：盘符、POSIX 绝对路径、相对路径
+  if (/^[a-zA-Z]:[\\/]/.test(s)) return false;
+  if (s.startsWith('/') || s.startsWith('\\')) return false;
+  if (s.startsWith('.')) return false;
+
+  return (
+    /^(https?|git|ssh|file):\/\//i.test(s) ||
+    /^[^\s/@]+@[^\s/]+:/.test(s) || // scp 风格：git@host:path
+    s.endsWith('.git')
+  );
+}
+
+/** git 是否可用 */
+export function hasGit() {
+  const res = spawnSync('git', ['--version'], { encoding: 'utf8' });
+  return res.status === 0;
+}
+
+/**
+ * 把一个 git 仓库的某个 ref 取到临时目录。
+ *
+ * 取完即用、用完即删——不做本地缓存。多花的是一次 clone 的时间（内容仓库通常很小），
+ * 换来的是没有「缓存过期」这类说不清的状态。
+ *
+ * **`GIT_TERMINAL_PROMPT=0` 是必须的**：否则遇到需要凭据的仓库时 git 会停下来等输入，
+ * 在 CI 或 postinstall 里就是永久挂起——和交互式提示一样危险。
+ *
+ * @param {{url: string, ref?: string|null}} opts
+ * @returns {{root: string, cleanup: () => void}}
+ */
+export function fetchRepo({ url, ref }) {
+  if (!hasGit()) {
+    throw new Error('找不到 git 命令。请先安装 git，或把 content 指向一个本地已克隆的目录。');
+  }
+
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-syncer-src-'));
+  const dest = path.join(tmpRoot, 'repo');
+  const cleanup = () => fs.rmSync(tmpRoot, { recursive: true, force: true });
+
+  const baseEnv = {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0', // 绝不等待输入
+    GIT_ASKPASS: 'echo',
+  };
+
+  /** @param {string[]} args */
+  const run = (args) =>
+    spawnSync('git', args, {
+      encoding: 'utf8',
+      env: baseEnv,
+      // 不用 inherit：clone 的进度输出对使用者没有价值，失败时我们再完整打印 stderr
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+  /** @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;
+  }
+
+  if (res.status !== 0) {
+    cleanup();
+    const detail = (res.stderr || res.stdout || '').trim();
+    throw new Error(
+      `拉取失败：${url}${ref ? ` @ ${ref}` : ''}\n` +
+        (detail ? `  git 说：${detail}` : '  （git 没有输出更多信息）'),
+    );
+  }
+
+  return { root: dest, cleanup };
+}
+
+/**
+ * 列表类 git 调用的超时（毫秒）。
+ *
+ * 取 refs 是**问了才用**的一步：内容仓库连不上时，用户宁可看到「跳过这一步」
+ * 也不愿意对着一个不动的光标等下去。凭据那条路已经由 GIT_TERMINAL_PROMPT=0 堵死，
+ * 这里堵的是「连得上但不回话」——网络黑洞、被墙的 host、挂掉的 git server。
+ */
+const REF_LIST_TIMEOUT_MS = 15_000;
+
+/**
+ * 解析 `git` 列出来的 ref 行，分成分支和标签。
+ *
+ * 两种来源共用：`ls-remote` 给的是 `<sha>\t<ref>`，`for-each-ref` 给的是裸的
+ * `<ref>`。所以只认「最后一个字段」，前缀对不上的一律丢掉。
+ *
+ * 标签要去掉 `^{}` 后缀：注解标签在 `ls-remote` 里会出现两行（标签本身和它
+ * 指向的提交），不处理的话列表里会多出一个 `v1^{}`。
+ *
+ * @param {string} text
+ * @returns {{branches: string[], tags: string[]}}
+ */
+function parseRefs(text) {
+  /** @type {string[]} */
+  const branches = [];
+  /** @type {string[]} */
+  const tags = [];
+
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    const parts = trimmed.split(/\s+/);
+    const ref = parts[parts.length - 1];
+    if (ref.startsWith('refs/heads/')) {
+      branches.push(ref.slice('refs/heads/'.length));
+    } else if (ref.startsWith('refs/tags/')) {
+      const name = ref.slice('refs/tags/'.length).replace(/\^\{\}$/, '');
+      if (name !== '' && !tags.includes(name)) tags.push(name);
+    }
+  }
+
+  return { branches, tags };
+}
+
+/**
+ * 本地路径配了 `ref` 时该说的那句话。
+ *
+ * `sync` 对本地路径读的是那个目录的**工作树**（这正是本地路径「改完内容立刻能试」
+ * 的来由），`ref` 一个字都用不上。写进配置却不生效，比不写更糟——用户会以为版本
+ * 被钉住了，实际拿到的还是他当前检出的那份，而且**全程没有任何提示**。
+ *
+ * 想钉版本就把 `content` 写成 git 地址（`file:///…` 也算，那会走 clone）。
+ *
+ * @param {string} source @param {string|null|undefined} ref
+ * @returns {string|null} 要说的话；没什么要说的返回 null
+ */
+export function localRefWarning(source, ref) {
+  if (!ref || isGitUrl(source)) return null;
+  return (
+    `"ref": "${ref}" 对本地路径不生效——读的是那个目录的工作树，不是某个提交。` +
+    '要钉版本请把 content 写成 git 地址'
+  );
+}
+
+/**
+ * 列出内容仓库有哪些分支和标签。
+ *
+ * 远端走 `git ls-remote`（**不克隆**，只问一句），本地路径走 `git for-each-ref`。
+ * 本地路径不是 git 仓库、git 没装、离线、要凭据、超时——**一律返回 null，
+ * 不抛错**。这一条是刻意的：调用方（init）问这个问题只是为了给用户一个下拉列表，
+ * 取不到就该安静跳过，绝不能让「列不出 refs」把整个流程拦下来。
+ *
+ * `GIT_TERMINAL_PROMPT=0` 与 fetchRepo 同一个理由：要密码的仓库必须当场失败，
+ * 不能停下来等人输入——CI 里那就是永久挂起。
+ *
+ * @param {{source: string, cwd?: string}} opts `source` 是本地路径或 git 地址
+ * @returns {{branches: string[], tags: string[]}|null}
+ */
+export function listRefs({ source, cwd = process.cwd() }) {
+  if (typeof source !== 'string' || source.trim() === '') return null;
+  if (!hasGit()) return null;
+
+  const env = {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_ASKPASS: 'echo',
+  };
+  const opts = {
+    encoding: /** @type {const} */ ('utf8'),
+    env,
+    stdio: /** @type {const} */ (['ignore', 'pipe', 'pipe']),
+    timeout: REF_LIST_TIMEOUT_MS,
+  };
+
+  const res = isGitUrl(source)
+    ? spawnSync('git', ['ls-remote', '--heads', '--tags', '--', source], opts)
+    : spawnSync('git', ['-C', path.resolve(cwd, source), 'for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/tags'], opts);
+
+  // timeout 时 spawnSync 会把 status 置成 null 并给出 error，一并当作「取不到」
+  if (res.error || res.status !== 0) return null;
+  return parseRefs(res.stdout ?? '');
+}
+
+/**
+ * 把分支和标签排成下拉列表里的顺序。纯函数，单独测。
+ *
+ * 顺序是有讲究的，不是随便排的：
+ *
+ *   1. `main`、`master` —— 用户十有八九要选的就是它，而且 main 在 master 前面
+ *      （新仓库用 main，老仓库才是 master）
+ *   2. **标签** —— 想钉版本的人一眼能看到；这类名字（v1.2.3）和分支名不会混
+ *   3. 其它分支 —— 最不常选，垫底
+ *
+ * 组内按 `numeric` 的自然序排（v1.2 < v1.10，而不是字典序的 v1.10 < v1.2），
+ * 并且**排一次序**：输入顺序取决于 git 的返回顺序，那东西不稳定，而
+ * 下拉列表每次长得不一样会让人怀疑自己是不是点错了。
+ *
+ * 同名去重，保留先出现的那个——分支 `v1` 和标签 `v1` 撞名时按上面的优先级走。
+ *
+ * @param {{branches?: string[], tags?: string[]}} refs
+ * @returns {string[]}
+ */
+export function orderRefs({ branches = [], tags = [] } = {}) {
+  // 自然序：不带 numeric 的话 v1.10 会排在 v1.2 前面，而标签里这种名字最常见
+  const cmp = (/** @type {string} */ a, /** @type {string} */ b) =>
+    a.localeCompare(b, 'en', { numeric: true });
+
+  const rank = (/** @type {string} */ name) => (name === 'main' ? 0 : name === 'master' ? 1 : 2);
+  const head = branches.filter((b) => rank(b) < 2).sort((a, b) => rank(a) - rank(b) || cmp(a, b));
+  const rest = branches.filter((b) => rank(b) === 2).sort(cmp);
+
+  /** @type {string[]} */
+  const out = [];
+  for (const name of [...head, ...[...tags].sort(cmp), ...rest]) {
+    if (name !== '' && !out.includes(name)) out.push(name);
+  }
+  return out;
+}