agent-syncer 0.1.0 → 0.1.2

package/lib/install.js

@@ -0,0 +1,260 @@
+// @ts-check
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { isSymlink } from './link.js';
+import { ITEM_KINDS, SUPPORT_DIR, itemPath, parseItem, projectItemPath } from './manifest.js';
+import { CONTENT_ROOT } from './target.js';
+
+/**
+ * 目录树的稳定指纹：所有文件的「相对路径 + 内容哈希」，按路径排序。
+ * 单文件则直接返回内容哈希。
+ *
+ * 用它而不是 mtime 来判断「变了没有」——内容仓库重新克隆后 mtime 全变，
+ * 但内容其实一模一样，那时不该报「更新」。
+ *
+ * ⚠️ **按原始字节算，所以换行符差异（CRLF / LF）会被算成「变了」。**
+ * 检出成 CRLF 的那份和内容仓库里的 LF 对不上，sync 会多报一次「更新」并把文件
+ * 重写回 LF，之后自愈（实测：第二遍就报「已是最新」）。
+ *
+ * 会不会污染 git，取决于**项目仓库自己的配置**，与本工具无关：
+ * - `core.autocrlf=true` → `git status` 会短暂显示 M，但 `git add` 不产生内容差异
+ * - `core.autocrlf=false` → 行尾改动作会被当成真改动提交进去
+ *
+ * 根治办法是项目里放一份 `.gitattributes`（`* text=auto`），让行尾行为不再取决于
+ * 每个人各自的 core.autocrlf。内容仓库那边已经有这个要求，项目仓库这边同样需要。
+ *
+ * @param {string} p
+ */
+function fingerprint(p) {
+  const st = fs.statSync(p);
+  if (!st.isDirectory()) {
+    return crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+  }
+
+  /** @type {string[]} */
+  const parts = [];
+  const walk = (dir, base) => {
+    const entries = fs
+      .readdirSync(dir, { withFileTypes: true })
+      .sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      const abs = path.join(dir, e.name);
+      const rel = base ? `${base}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(abs, rel);
+      else parts.push(`${rel}:${crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex')}`);
+    }
+  };
+  walk(p, '');
+  return parts.join('\n');
+}
+
+/** new = 项目里还没有；same = 内容一致；update = 有差异会被覆盖 */
+function statusOf(from, to) {
+  if (!fs.existsSync(to)) return 'new';
+  try {
+    return fingerprint(from) === fingerprint(to) ? 'same' : 'update';
+  } catch {
+    // 目标不是常规文件/目录（比如是链接），一律当作会被覆盖，让上层去拦
+    return 'update';
+  }
+}
+
+/**
+ * 落点路径上、**项目范围内**有没有链接——不含最后一段（那一段由调用方判，
+ * 消息不一样）。
+ *
+ * 为什么必须往上找：守卫原先只看叶子，于是 `.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;
+}
+
+/**
+ * 递归列出目录下的所有文件（相对路径，正斜杠）。
+ * @param {string} dir @returns {string[]}
+ */
+function walkFiles(dir) {
+  /** @type {string[]} */
+  const out = [];
+  const walk = (d, base) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const rel = base ? `${base}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(d, e.name), rel);
+      else out.push(rel);
+    }
+  };
+  walk(dir, '');
+  return out.sort();
+}
+
+/**
+ * 本次选择里有没有 hook 或 mcp —— **只有这两类会引用 `scripts/` 里的文件**。
+ * @param {string[]} items
+ */
+function wantsSupport(items) {
+  return items.some((spec) => {
+    const { kind } = parseItem(spec);
+    return kind === 'hook' || kind === 'mcp';
+  });
+}
+
+/**
+ * `scripts/` 是支撑目录：hook 和 mcp 都按路径引用脚本，单独挑拣容易漏，
+ * 所以整目录同步。它不参与 bundle 的条目挑选。
+ *
+ * 「整目录」指的是**在 scripts/ 内部不再细分**，而不是「无条件同步」——
+ * 要不要同步它，由 `planInstall` 按本次选择决定，见那里的注释。
+ */
+function collectSupport(repoRoot, projectRoot) {
+  const from = path.resolve(repoRoot, SUPPORT_DIR);
+  if (!fs.existsSync(from)) return [];
+
+  return walkFiles(from).map((rel) => {
+    const src = path.join(from, rel);
+    const dst = path.resolve(projectRoot, CONTENT_ROOT, SUPPORT_DIR, rel);
+    return {
+      spec: `script:${rel}`,
+      kind: 'script',
+      id: rel,
+      from: src,
+      to: dst,
+      status: statusOf(src, dst),
+    };
+  });
+}
+
+/**
+ * 算出「要装什么、每个的当前状态」，但不写盘。
+ * @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, linkAt?: string}[]} */
+  const entries = [];
+
+  for (const spec of items) {
+    const { kind, id } = parseItem(spec);
+    const from = itemPath(repoRoot, kind, id);
+    const to = projectItemPath(projectRoot, kind, id);
+    entries.push({ spec, kind, id, from, to, status: statusOf(from, to) });
+  }
+
+  // `scripts/` 只在**本轮真的选了 hook 或 mcp** 时才同步。
+  //
+  // 「整目录同步」的理由是「hook / mcp 按路径引用脚本，逐个挑拣容易漏，漏了就是
+  // 运行时静默失败」——那个理由只在有 hook / mcp 的时候成立。一个都没选的时候，
+  // `.agents/` 里没有任何东西会去引用它们，同步过去只是把一堆用不上的文件塞进
+  // 每个项目，而**它们是要提交进版本库的**。
+  //
+  // 注意判据是 `items`（本次选择），不是滤掉 protect 之后的计划：锁住的 hook
+  // 仍然躺在 `.agents/hooks/` 里，它引用的脚本还得留着。
+  if (wantsSupport(items)) entries.push(...collectSupport(repoRoot, projectRoot));
+
+  // 路径上有链接的一律拦下——那多半是 link 命令建的反向链接，
+  // 写进去等于把内容仓库的东西写进一个链接指向的地方。叶子和中间目录都查。
+  for (const e of entries) {
+    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;
+}
+
+/**
+ * 落盘。
+ *
+ * 覆盖策略：先整体删掉目标再拷。不能用 `cpSync` 的 force——它只覆盖同名文件，
+ * 内容仓库里**删掉的文件**会残留在项目里，越积越多。
+ *
+ * @param {ReturnType<typeof planInstall>} entries
+ * @param {{dryRun?: boolean}} [opts]
+ */
+export function applyInstall(entries, opts = {}) {
+  const { dryRun = false } = opts;
+  let written = 0;
+  const skipped = entries.filter((e) => e.status === 'same').length;
+  /** @type {{spec: string, message: string}[]} */
+  const problems = [];
+
+  if (dryRun) {
+    return { written: 0, skipped, problems };
+  }
+
+  for (const e of entries) {
+    if (e.status === 'same' || e.status === 'blocked') continue;
+    try {
+      fs.mkdirSync(path.dirname(e.to), { recursive: true });
+      fs.rmSync(e.to, { recursive: true, force: true });
+      fs.cpSync(e.from, e.to, { recursive: true });
+      written += 1;
+    } catch (err) {
+      problems.push({ spec: e.spec, message: /** @type {Error} */ (err).message });
+    }
+  }
+
+  return { written, skipped, problems };
+}
+
+/**
+ * 找出项目 `.agents/` 下、但不在本次安装清单里的条目。
+ *
+ * 只报告、不删除——无法区分「上次装完残留的」和「用户自己加的」，
+ * 代用户做删除决定风险太大。
+ *
+ * 不检查 `scripts/`：它随内容一起整体同步，不属于任何 bundle 条目，
+ * 列进来只会每次误报。
+ *
+ * @param {string} projectRoot @param {string[]} items
+ */
+export function findOrphans(projectRoot, items) {
+  const wanted = new Set(items.map((s) => parseItem(s)).map(({ kind, id }) => `${kind}:${id}`));
+  /** @type {string[]} */
+  const orphans = [];
+
+  for (const [kind, cfg] of Object.entries(ITEM_KINDS)) {
+    const dir = path.resolve(projectRoot, CONTENT_ROOT, cfg.dir);
+    /** @type {fs.Dirent[]} */
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const id = cfg.ext === null ? e.name : e.name.endsWith(cfg.ext) ? e.name.slice(0, -cfg.ext.length) : null;
+      if (id === null) continue;
+      if (!wanted.has(`${kind}:${id}`)) orphans.push(`${kind}:${id}`);
+    }
+  }
+
+  return orphans.sort();
+}

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('/');