agent-syncer 0.1.0 → 0.1.1

package/lib/stale.js

@@ -0,0 +1,130 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { STATUS, inspect, samePath } from './link.js';
+import { deepEqualJSON, readJsonFile } from './merge.js';
+import { MERGE_KINDS, TOOLS, TOOL_NAMES, contentDir, kindsOf, mergeTarget } from './target.js';
+
+/**
+ * 找出「已经建好、但当前配置里不再需要」的链接。
+ *
+ * 为什么必须有这一步：**link 只加不减**。把某个工具从 agents.json 的 links 里
+ * 去掉，已经建好的 junction 会原地留下，而 .gitignore 托管段却已经不忽略它们了。
+ * 于是 git 会穿透这些链接，把 .agents/ 的内容**再提交一份**——托管段存在的
+ * 唯一目的就此被绕过，全程没有任何提示。
+ *
+ * 只认**指向本项目 .agents/<kind>/ 的链接**：指向别处的链接不是本工具建的，
+ * 该不该删与本次配置无关，交给用户自己判断。
+ *
+ * 断链也算——链接指着 .agents/rules、而 .agents/rules 已经被删掉，
+ * 同样是该清理的残留。
+ *
+ * 纯只读，不修改任何东西。
+ *
+ * @param {string} projectRoot
+ * @param {string[]} tools 当前配置里要保留的工具
+ * @returns {{tool: string, kind: string, rel: string, target: string}[]}
+ */
+export function findStaleLinks(projectRoot, tools) {
+  /** @type {Set<string>} */
+  const wanted = new Set();
+  for (const tool of tools) {
+    for (const kind of kindsOf(tool)) wanted.add(TOOLS[tool].links[kind]);
+  }
+
+  /** @type {{tool: string, kind: string, rel: string, target: string}[]} */
+  const out = [];
+
+  for (const tool of TOOL_NAMES) {
+    for (const kind of kindsOf(tool)) {
+      const rel = TOOLS[tool].links[kind];
+      if (wanted.has(rel)) continue;
+
+      const target = path.resolve(projectRoot, rel);
+      const expected = contentDir(projectRoot, kind);
+      const st = inspect(target, expected);
+
+      const ours =
+        st.status === STATUS.HEALTHY ||
+        (st.status === STATUS.BROKEN && st.actual !== undefined && samePath(st.actual, expected));
+      if (!ours) continue;
+
+      out.push({ tool, kind, rel, target });
+    }
+  }
+
+  return out;
+}
+
+/**
+ * 文件里还找得到这一条吗。找不到就别报，免得虚惊一场。
+ *
+ * mcp 按 id 查键；hook 没有 id 这个概念（条目按事件名排），只能在对应事件
+ * 里按深度相等找我们记下的那些条目。
+ *
+ * @param {Record<string, any>} cfg @param {string} kind @param {string} id @param {any} value
+ */
+function stillPresent(cfg, kind, id, value) {
+  if (kind === 'mcp') {
+    const servers = cfg.mcpServers;
+    return (
+      servers !== null && typeof servers === 'object' && !Array.isArray(servers) && Object.hasOwn(servers, id)
+    );
+  }
+
+  const hooks = cfg.hooks;
+  if (hooks === null || typeof hooks !== 'object' || Array.isArray(hooks)) return false;
+  for (const [event, entries] of Object.entries(value ?? {})) {
+    const list = Array.isArray(hooks[event]) ? hooks[event] : [];
+    for (const entry of entries ?? []) {
+      if (list.some((x) => deepEqualJSON(x, entry))) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * 找出「本工具合进过、但当前配置里已经不要那个工具了」的合并产物。
+ *
+ * 和 `findStaleLinks` 完全同构，后果也一样：`.mcp.json` 是我们写的、已经提交
+ * 进版本库，而那个工具从 `links` 里去掉之后**没有任何东西会去清它**——文件里
+ * 留着一条谁也不认识的 server 定义，一句提示都没有。
+ *
+ * 判定只用记录里的 `merged`（「我们往哪个文件里写了什么」），不看文件里
+ * 「有没有像我们的东西」——后者是猜，而这个项目一贯的立场是拿不准就不动。
+ * 另外要求那条**现在还在文件里**，否则用户自己删过了还报「有残留」就是虚惊。
+ *
+ * 纯只读。
+ *
+ * @param {string} projectRoot
+ * @param {string[]} tools 当前配置里要保留的工具
+ * @param {Record<string, any>} merged 记录里的 merged
+ * @returns {{tool: string, kind: string, rel: string, ids: string[]}[]}
+ */
+export function findStaleMerges(projectRoot, tools, merged) {
+  const keep = new Set(tools);
+  /** @type {{tool: string, kind: string, rel: string, ids: string[]}[]} */
+  const out = [];
+
+  for (const tool of TOOL_NAMES) {
+    if (keep.has(tool)) continue;
+
+    for (const kind of MERGE_KINDS) {
+      const target = mergeTarget(tool, kind);
+      if (!target) continue;
+
+      const recorded = merged?.[tool]?.[kind] ?? {};
+      if (Object.keys(recorded).length === 0) continue;
+
+      const abs = path.resolve(projectRoot, target.rel);
+      if (!fs.existsSync(abs)) continue; // 文件都删了，没有残留可言
+      const read = readJsonFile(abs);
+      if (read.error) continue; // 读不了就别乱说
+
+      const ids = Object.keys(recorded).filter((id) => stillPresent(read.value, kind, id, recorded[id]));
+      if (ids.length > 0) out.push({ tool, kind, rel: target.rel, ids });
+    }
+  }
+
+  return out;
+}

package/lib/target.js

@@ -7,14 +7,69 @@ import path from 'node:path';
  */
 export const CONTENT_ROOT = '.agents';
 
-/** 内容类型。与 .agents/ 下的子目录名一一对应。 */
+/** 可链接的内容类型。与 .agents/ 下的子目录名一一对应。 */
 export const KINDS = ['skills', 'rules', 'commands', 'agents'];
 
+/**
+ * 工具的配置目录名（相对项目根）：claude → `.claude`。
+ *
+ * 「工具名就是目录名去掉点」这条约定原先在 link.js（拼表格）、doctor.js
+ * （PACKAGE_TOOL_HINTS）各写了一遍，现在收到这里单点维护——它和下面的 TOOLS
+ * 属于同一类知识：哪个工具把东西放哪。
+ *
+ * @param {string} tool
+ */
+export function toolDir(tool) {
+  return `.${tool}`;
+}
+
+/**
+ * 合并层认的内容类型。**用的是目录名（复数）**，不是条目类型名。
+ *
+ * 这个项目里有两套词汇，是故意的：
+ *
+ * - **选择层**用单数条目名（`skill` / `hook` / `mcp`）——那是 `include` 里要写的词，
+ *   见 `manifest.js` 的 `ITEM_KINDS`
+ * - **文件层**用复数目录名（`skills` / `hooks` / `mcp`）——那是 `.agents/` 下的路径
+ *
+ * 合并器在**文件层**干活（读 `.agents/mcp/*.json`、写工具自己的配置文件），
+ * 所以这里和记录里的 `merged` 一律用复数。**这个坑真踩过**：`list` 初版按目录名
+ * 过滤，而数据是单数类型名，那句「装了不生效」的警告一声不吭。
+ */
+export const MERGE_KINDS = ['mcp', 'hooks'];
+
+/**
+ * 项目根在内容里的写法。**不引入新的中性占位符**，改成一张别名表：
+ * 内容里写哪个都认，合并时统一翻译成目标工具自己的写法。
+ *
+ * 理由是这个项目的铁律——内容只描述「这是什么」，不描述「写到哪」。而
+ * `args` / `env` / `headers` 里引用项目内的脚本时又确实需要一个「项目根」的
+ * 写法，各工具叫法还不同。别名表让两边都成立：已经写下的
+ * `${CLAUDE_PROJECT_DIR}` 不会作废，写 `${workspaceFolder}` 的内容也能在
+ * Claude 上跑。
+ */
+export const PROJECT_DIR_ALIASES = ['CLAUDE_PROJECT_DIR', 'workspaceFolder'];
+
+/**
+ * .agents/ 下**需要提交到版本库**的全部目录。
+ *
+ * 前四类是可链接的（见 KINDS）；hooks / mcp / scripts 不链接到任何工具目录，
+ * 它们由合并器读取、或被 hook 命令直接引用，但同样是真实文件而非链接。
+ *
+ * .gitignore 的白名单漏掉这三个，会导致 hook 脚本和 MCP 配置根本提交不上去——
+ * 别人克隆下来只有一个空壳。
+ */
+export const CONTENT_DIRS = [...KINDS, 'hooks', 'mcp', 'scripts'];
+
 /**
  * 工具 → 目标路径映射表。
  *
  * 这是全项目唯一需要关心「哪个工具把内容放哪」的地方——
- * link.js / status.js / doctor.js 都不得出现 if-tool 分支。
+ * link.js / status.js / doctor.js / merge.js 都不得出现 if-tool 分支。
+ *
+ * `links` 管**目录链接**（skills / rules / commands / agents），
+ * `merges` 管**合并进工具自己的配置文件**（hooks / mcp）——两套机制，
+ * 两套键，别互相污染。`merges` **缺键即不支持**，见 `mergeTarget()`。
  *
  * - claude：skills / rules / commands / agents 四类都是目录
  *   （rules 目录的有效性已在本机 Claude Code 2.1.267 上实测确认，含嵌套子目录）
@@ -37,6 +92,14 @@ export const TOOLS = {
       commands: '.claude/commands',
       agents: '.claude/agents',
     },
+    // 本机 Claude Code 2.1.267 实测：`claude mcp add --scope project` 写的就是
+    // 项目根的 `.mcp.json`，顶层是 `mcpServers` 对象。插件根目录下的 `.mcp.json`
+    // 用的是**扁平形式**（没有包装），那是插件特有的，别混。
+    merges: {
+      mcp: { rel: '.mcp.json' },
+      hooks: { rel: '.claude/settings.json' },
+    },
+    projectDir: { var: 'CLAUDE_PROJECT_DIR' },
   },
   trae: {
     label: 'Trae',
@@ -45,12 +108,23 @@ export const TOOLS = {
       rules: '.trae/rules',
       commands: '.trae/commands',
     },
+    // ⚠️ 本机没装 Trae，下面这两项**都没有实证**，来自网络资料。写错了的后果是
+    // 这个文件不生效（不会破坏别的东西），但 doctor 不该把它报成「一切正常」——
+    // 见 mergeTarget() 的 verified。
+    merges: {
+      mcp: { rel: '.trae/mcp.json', verified: false },
+    },
+    projectDir: { var: 'workspaceFolder', verified: false },
   },
   codex: {
     label: 'Codex CLI',
     links: {
       skills: '.codex/skills',
     },
+    // **没有 merges，是有意的**：Codex 的 MCP 配置是 `~/.codex/config.toml` 那样的
+    // TOML，项目级 `.codex/config.toml` 又只在**受信任项目**里加载，而且
+    // `codex mcp add` 只能写用户级（上游 issue #23487 还开着）。
+    // 缺键 = 不支持，调用方据此明确报警，而不是静默跳过。
   },
 };
 
@@ -66,27 +140,100 @@ export function contentDir(projectRoot, kind) {
   return path.resolve(projectRoot, CONTENT_ROOT, kind);
 }
 
+/** 取工具配置。未知工具一律抛错——静默忽略一份写错的配置太危险 */
+function toolCfg(tool) {
+  const cfg = TOOLS[tool];
+  if (!cfg) throw new Error(`未知工具：${tool}。可用值：${TOOL_NAMES.join(', ')}`);
+  return cfg;
+}
+
 /**
  * 某工具支持的内容类型列表
  * @param {string} tool
  * @returns {string[]}
  */
 export function kindsOf(tool) {
-  const cfg = TOOLS[tool];
-  if (!cfg) throw new Error(`未知工具：${tool}。可用值：${TOOL_NAMES.join(', ')}`);
+  const cfg = toolCfg(tool);
   return KINDS.filter((k) => Object.hasOwn(cfg.links, k));
 }
 
+/**
+ * 某工具对某一类内容有没有合并目标。**没有就是「不支持」**。
+ *
+ * 「没有这个文件」有三种截然不同的意思，别混成一种：
+ *
+ * 1. 该工具这次没被 `links` 选中 → 什么都不该说
+ * 2. 选中了，但该工具根本没有这个机制（codex 的 mcp）→ **必须报警**
+ *    「内容装上了，但没有地方能合，不会生效」
+ * 3. 支持，但目标文件还不存在 → 正常，创建
+ *
+ * `verified: false` 表示「这条路没有实证」（目前只有 Trae）。调用方拿它去
+ * 决定该报 `ok` 还是「未实证」——**不能把没验证过的东西报成一切正常**。
+ *
+ * @param {string} tool @param {string} kind MERGE_KINDS 之一
+ * @returns {{rel: string, verified: boolean}|null}
+ */
+export function mergeTarget(tool, kind) {
+  const m = toolCfg(tool).merges?.[kind];
+  if (!m) return null;
+  return { rel: m.rel, verified: m.verified !== false };
+}
+
+/**
+ * 某工具支持合并的内容类型。
+ * @param {string} tool
+ * @returns {string[]}
+ */
+export function mergeKindsOf(tool) {
+  const cfg = toolCfg(tool);
+  return MERGE_KINDS.filter((k) => Object.hasOwn(cfg.merges ?? {}, k));
+}
+
+/**
+ * 项目根变量在该工具里该写成什么。**没有合并目标的工具返回 `null`**——
+ * 它压根没有需要写路径的地方（codex 的 MCP 是 TOML，本工具不做）。
+ *
+ * @param {string} tool
+ * @returns {{var: string, verified: boolean}|null}
+ */
+export function projectDirOf(tool) {
+  const p = toolCfg(tool).projectDir;
+  return p ? { var: p.var, verified: p.verified !== false } : null;
+}
+
 /** 条目的规范写法："claude/skills" */
 export function specOf(tool, kind) {
   return `${tool}/${kind}`;
 }
 
-/** 某工具支持的全部条目（用于 `tools` 形式的配置展开） */
+/** 某工具支持的全部条目 */
 export function allSpecs(tool) {
   return kindsOf(tool).map((k) => specOf(tool, k));
 }
 
+/**
+ * 把工具名列表展开成条目列表。
+ *
+ * 配置里只写工具名（`"links": ["claude", "trae"]`）——选用一个工具就是全量适配，
+ * 细化到单个目录没有实际意义。条目形式（"claude/skills"）仅作为内部表示存在，
+ * 由这个函数单点展开，别处不再各自拼。
+ *
+ * @param {string[]} tools
+ */
+export function specsOfTools(tools) {
+  return tools.flatMap(allSpecs);
+}
+
+/**
+ * 按 TOOL_NAMES 的固定顺序排序工具名，顺带去重。
+ * 固定顺序是为了让每次写出的配置 diff 稳定，不随勾选顺序变化。
+ * @param {string[]} tools
+ */
+export function sortTools(tools) {
+  const set = new Set(tools);
+  return TOOL_NAMES.filter((t) => set.has(t));
+}
+
 /**
  * 解析 "claude/skills" 形式的条目。非法即抛错——配置写错时要立刻说清楚，
  * 不能静默忽略，否则用户会以为已经生效。
@@ -134,11 +281,3 @@ export function plannedLinks(projectRoot, specs) {
   });
 }
 
-/**
- * 条目里出现过哪些工具，按 TOOL_NAMES 的固定顺序返回
- * @param {string[]} specs
- */
-export function toolsOfSpecs(specs) {
-  const seen = new Set(specs.map((s) => parseSpec(s).tool));
-  return TOOL_NAMES.filter((t) => seen.has(t));
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-syncer",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "把 .agents/ 下的 AI 资产（skills / rules / commands）分发到 Claude Code、Trae、Codex 等工具的配置目录",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "bin",
     "lib",
-    "README.md"
+    "README.md",
+    "CONTENT-REPO.md"
   ],
   "engines": {
     "node": ">=20.11.0"