agent-syncer 0.1.0 → 0.1.2

package/lib/manifest.js

@@ -0,0 +1,442 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONTENT_ROOT } from './target.js';
+
+/** 当前支持的内容仓库 schema 版本 */
+export const SCHEMA_VERSION = 1;
+
+/**
+ * 条目的六种类型。
+ *
+ * 注意这里的 `kind` 是**单数**（`skill:code-style`），而内容仓库里的目录名是复数。
+ * 两套词汇故意分开：仓库目录结构可以变，条目 id 是稳定的对外契约。
+ *
+ * @type {Record<string, {dir: string, ext: string|null, label: string}>}
+ */
+export const ITEM_KINDS = {
+  skill: { dir: 'skills', ext: null, label: '技能' },
+  rule: { dir: 'rules', ext: '.md', label: '规则' },
+  command: { dir: 'commands', ext: '.md', label: '命令' },
+  agent: { dir: 'agents', ext: '.md', label: '子代理' },
+  hook: { dir: 'hooks', ext: '.json', label: 'Hook' },
+  mcp: { dir: 'mcp', ext: '.json', label: 'MCP' },
+};
+
+export const ITEM_KIND_NAMES = Object.keys(ITEM_KINDS);
+
+/** hooks / mcp 靠路径引用脚本，所以 scripts/ 作为支撑目录整体同步，不参与条目挑选 */
+export const SUPPORT_DIR = 'scripts';
+
+/**
+ * 条目在内容仓库里的绝对路径。
+ * skill 是目录，其余是「<id><ext>」单文件。
+ * @param {string} repoRoot @param {string} kind @param {string} id
+ */
+export function itemPath(repoRoot, kind, id) {
+  const cfg = ITEM_KINDS[kind];
+  if (!cfg) throw new Error(`未知条目类型 "${kind}"（可用：${ITEM_KIND_NAMES.join('、')}）`);
+  return path.resolve(repoRoot, cfg.dir, cfg.ext === null ? id : `${id}${cfg.ext}`);
+}
+
+/**
+ * 条目在项目里的落点：`<项目根>/.agents/<仓库目录名>/<id>[ext]`。
+ *
+ * 和上面 `itemPath` 是镜像——一个问「内容仓库里在哪」，一个问「项目里在哪」。
+ * **放在一起是因为它们总是一起变**：加一类条目、改一次扩展名，两个函数必须同时
+ * 改对。（它原先住在 `install.js`，于是 `record.js` 为了拿它得反向依赖安装层——
+ * 一个「条目在哪」的问题，不该由「怎么把文件拷过去」那个模块来回答。）
+ *
+ * @param {string} projectRoot @param {string} kind @param {string} id
+ */
+export function projectItemPath(projectRoot, kind, id) {
+  const cfg = ITEM_KINDS[kind];
+  if (!cfg) throw new Error(`未知条目类型 "${kind}"（可用：${ITEM_KIND_NAMES.join('、')}）`);
+  return path.resolve(
+    projectRoot,
+    CONTENT_ROOT,
+    cfg.dir,
+    cfg.ext === null ? id : `${id}${cfg.ext}`,
+  );
+}
+
+/**
+ * 解析 `kind:id` 形式的条目引用。
+ * @param {string} entry
+ * @returns {{kind: string, id: string}}
+ */
+export function parseItem(entry) {
+  if (typeof entry !== 'string') {
+    throw new Error(`条目必须是字符串，收到 ${JSON.stringify(entry)}`);
+  }
+  const colon = entry.indexOf(':');
+  if (colon === -1) {
+    throw new Error(`条目 ${JSON.stringify(entry)} 格式不对，应为 "类型:名字"，例如 "skill:code-style"`);
+  }
+  const kind = entry.slice(0, colon).trim();
+  const id = entry.slice(colon + 1).trim();
+  if (!Object.hasOwn(ITEM_KINDS, kind)) {
+    throw new Error(`未知条目类型 "${kind}"（可用：${ITEM_KIND_NAMES.join('、')}）`);
+  }
+  if (id === '') throw new Error(`条目 ${JSON.stringify(entry)} 缺少名字`);
+  return { kind, id };
+}
+
+/**
+ * 加载并校验内容仓库的根清单。
+ * @param {string} repoRoot
+ */
+export function loadRepo(repoRoot) {
+  const p = path.resolve(repoRoot, 'dept.json');
+  if (!fs.existsSync(p)) {
+    throw new Error(`${repoRoot} 不是内容仓库：找不到 dept.json`);
+  }
+
+  /** @type {any} */
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (e) {
+    throw new Error(`dept.json 不是合法的 JSON：${/** @type {Error} */ (e).message}`);
+  }
+
+  if (raw?.schemaVersion !== SCHEMA_VERSION) {
+    throw new Error(
+      `内容仓库的 schemaVersion 是 ${JSON.stringify(raw?.schemaVersion)}，` +
+        `本工具只支持 ${SCHEMA_VERSION}。请升级 agent-syncer。`,
+    );
+  }
+  return { name: raw.name, version: raw.version, description: raw.description, root: path.resolve(repoRoot) };
+}
+
+/**
+ * 扫描内容仓库，列出每类条目下有哪些 id。
+ * @param {string} repoRoot
+ * @returns {Record<string, string[]>}
+ */
+export function listItems(repoRoot) {
+  /** @type {Record<string, string[]>} */
+  const out = {};
+
+  for (const [kind, cfg] of Object.entries(ITEM_KINDS)) {
+    const dir = path.resolve(repoRoot, cfg.dir);
+    /** @type {fs.Dirent[]} */
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      out[kind] = [];
+      continue;
+    }
+
+    out[kind] = entries
+      .filter((e) => (cfg.ext === null ? e.isDirectory() : e.isFile() && e.name.endsWith(cfg.ext)))
+      .map((e) => (cfg.ext === null ? e.name : e.name.slice(0, -cfg.ext.length)))
+      .sort();
+  }
+
+  return out;
+}
+
+/**
+ * 列出所有可选的 bundle。
+ * @param {string} repoRoot
+ */
+export function listBundles(repoRoot) {
+  const dir = path.resolve(repoRoot, 'bundles');
+  /** @type {{name: string, title?: string, description?: string}[]} */
+  const out = [];
+
+  /** @type {string[]} */
+  let files;
+  try {
+    files = fs.readdirSync(dir);
+  } catch {
+    return out;
+  }
+
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    const name = f.slice(0, -'.json'.length);
+    /** @type {any} */
+    let raw;
+    try {
+      raw = JSON.parse(fs.readFileSync(path.resolve(dir, f), 'utf8'));
+    } catch (e) {
+      out.push({ name, description: `（文件损坏：${/** @type {Error} */ (e).message}）` });
+      continue;
+    }
+    out.push({ name, title: raw?.title, description: raw?.description });
+  }
+
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * 规整顶层的 `bundle` 字段：单个字符串和字符串数组都收，统一成数组。
+ *
+ * 单个字符串也接受，理由和项目根一样——没道理为了加第二个模板先加方括号。
+ * 语义与项目根 `agents.json` 的 `bundle` 字段**完全一致**：被引用的每个模板
+ * 各自完整解析，然后取并集。
+ *
+ * @param {string} file 出错时用来指明是哪个文件，光说"bundle 格式不对"没法照着修
+ * @param {any} value
+ * @returns {string[]}
+ */
+function normalizeBundleField(file, value) {
+  if (value === undefined || value === null) return [];
+  if (typeof value !== 'string' && !Array.isArray(value)) {
+    throw new Error(`${file} 的 bundle 必须是字符串或字符串数组，收到 ${JSON.stringify(value)}`);
+  }
+
+  const arr = Array.isArray(value) ? value : [value];
+  /** @type {string[]} */
+  const out = [];
+  for (const [i, n] of arr.entries()) {
+    if (typeof n !== 'string') {
+      throw new Error(`${file} 的 bundle[${i}] 必须是字符串，收到 ${JSON.stringify(n)}`);
+    }
+    // 去空白、丢空串、去重、保序——**和项目根那份（config.js 的 normalizeList）
+    // 规则必须一模一样**。文档里说两层「字段名和含义一字不差」，那 `"common "`
+    // 和 `["common"]` 在两边就得是同一件事；不一致的后果很隐蔽：同一份配置写进
+    // 模板文件能用、写进 agents.json 就报「找不到模板 "common "」。
+    const s = n.trim();
+    if (s !== '' && !out.includes(s)) out.push(s);
+  }
+  return out;
+}
+
+/**
+ * 模板名只能是**一个文件名**，不能是路径。
+ *
+ * `readBundle` 拿名字去拼 `bundles/<名字>.json`。不拦的话，内容仓库里一句
+ * `"bundle": ["../../../../某处的配置"]` 就能读到仓库外的任意 JSON——而且
+ * 读出来的片段还会进报错信息，等于把那个文件的内容写进日志。
+ *
+ * 影响不算大（内容仓库通常是团队自有的，能读到的多半也只是 JSON），但
+ * 「内容仓库可以指定读仓库外的文件」这一条本身就不该成立，拦下来只要几行。
+ *
+ * @param {string} name
+ */
+function assertBundleName(name) {
+  if (name === '' || name === '.' || name === '..' || /[\\/]/.test(name) || name.includes('\0')) {
+    throw new Error(
+      `模板名必须是一个简单的名字，不能带路径：收到 ${JSON.stringify(name)}（例如 "common"）`,
+    );
+  }
+}
+
+/** 读一个 bundle 文件 */
+function readBundle(repoRoot, name) {
+  assertBundleName(name);
+  const p = path.resolve(repoRoot, 'bundles', `${name}.json`);
+  if (!fs.existsSync(p)) {
+    const available = listBundles(repoRoot).map((b) => b.name);
+    throw new Error(
+      `找不到模板 "${name}"。可用：${available.length > 0 ? available.join('、') : '（仓库里没有任何 bundle）'}`,
+    );
+  }
+  /** @type {any} */
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (e) {
+    throw new Error(`bundles/${name}.json 不是合法的 JSON：${/** @type {Error} */ (e).message}`);
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`bundles/${name}.json 的顶层必须是一个对象`);
+  }
+  if (raw.include !== undefined && !Array.isArray(raw.include)) {
+    throw new Error(`bundles/${name}.json 的 include 必须是数组`);
+  }
+  if (raw.exclude !== undefined && !Array.isArray(raw.exclude)) {
+    throw new Error(`bundles/${name}.json 的 exclude 必须是数组`);
+  }
+  // 顺手把 bundle 字段规整成数组，后面按同一套流水线走，不必再关心它是怎么写进来的
+  raw.bundle = normalizeBundleField(`bundles/${name}.json`, raw.bundle);
+  return raw;
+}
+
+/**
+ * 把一条 include / exclude 展开成条目列表。
+ *
+ * 支持两种写法：
+ * - `类型:*`      —— 该类型下的全部条目
+ * - `类型:名字`    —— 单个条目
+ *
+ * **模板之间的组合不走这里**，走顶层的 `bundle` 字段（`"bundle": ["common"]`）。
+ * 老写法 `@common` 已经移除，见到就直接抛错——静默忽略会让「引用没生效」
+ * 变成一个没人查得出来的哑谜，而错误信息里的新写法能让人当场改对。
+ *
+ * `lenient` 只放宽一件事：**条目在仓库里不存在时返回空、改成告警，而不是抛错**。
+ * 这专给 exclude 用——"排除一个当前不存在的东西"是合法的空操作，
+ * 而项目级的 exclude 是叠在模板之上的最后一层，模板内容一变动就把所有人的
+ * 配置搞崩，代价太大。类型写错、语法写错、`@` 老写法，这些一律照旧抛错，绝不放过。
+ *
+ * @param {string} repoRoot @param {string} entry
+ * @param {{lenient?: boolean, warnings?: string[]}} [opts]
+ * @returns {string[]}
+ */
+function expandEntry(repoRoot, entry, opts = {}) {
+  const { lenient = false, warnings = [] } = opts;
+
+  if (typeof entry === 'string' && entry.startsWith('@')) {
+    throw new Error(
+      `${JSON.stringify(entry)} 这种写法已经移除。模板之间的组合改用顶层字段：\n` +
+        '  "bundle": ["common"]\n' +
+        '（bundles/*.json 和 agents.json 里用的是同一个字段，include / exclude 不再接受 "@名字"）',
+    );
+  }
+
+  const { kind, id } = parseItem(entry);
+
+  if (id === '*') {
+    return listItems(repoRoot)[kind].map((x) => `${kind}:${x}`);
+  }
+
+  const p = itemPath(repoRoot, kind, id);
+  if (!fs.existsSync(p)) {
+    const available = listItems(repoRoot)[kind];
+    const detail =
+      `条目 ${JSON.stringify(entry)} 在内容仓库里不存在（找的是 ${path.relative(repoRoot, p)}）。` +
+      `该类型下现有：${available.length > 0 ? available.join('、') : '（空）'}`;
+    if (lenient) {
+      warnings.push(`${detail}（作为 exclude 跳过，不影响其它条目）`);
+      return [];
+    }
+    throw new Error(detail);
+  }
+  return [`${kind}:${id}`];
+}
+
+/**
+ * 展开一组条目引用（保序、去重）。
+ * @param {string} repoRoot @param {string[]} entries
+ * @param {{lenient?: boolean, warnings?: string[]}} [opts]
+ * @returns {string[]}
+ */
+function expandEntries(repoRoot, entries, opts = {}) {
+  /** @type {string[]} */
+  const out = [];
+  for (const entry of entries) {
+    for (const item of expandEntry(repoRoot, entry, opts)) {
+      if (!out.includes(item)) out.push(item);
+    }
+  }
+  return out;
+}
+
+/**
+ * 「模板并集 → 叠加 include → 最后过 exclude」这套三步流水线的共用实现。
+ *
+ * 模板内部（`resolveBundle`）和项目级（`resolveSelection`）走的是**同一套**：
+ * 两处各写一份的话，迟早会长出两套规则，而使用者根本分不清「模板里的 bundle」
+ * 和「agents.json 里的 bundle」能有什么区别——它们本来就该是同一个东西。
+ *
+ * 第 1 步刻意是"各自解析再取并集"，而不是把多个模板的 include 倒进一个池子
+ * 再统一过 exclude：模板应当是自洽的，A 模板的 exclude 不该悄悄砍掉 B 模板的内容，
+ * 否则 `bundle: ["a", "b"]` 的结果会依赖组合顺序和谁的 exclude 更宽，没法推理。
+ *
+ * @param {string} repoRoot
+ * @param {{bundle?: string[], include?: string[], exclude?: string[]}} spec
+ * @param {string[]} stack 循环引用的引用链，由 resolveBundle 维护
+ * @param {{lenient?: boolean, warnings?: string[]}} [opts] 只作用于本层的 exclude
+ * @returns {{items: string[], dropped: string[]}}
+ */
+function resolvePipeline(repoRoot, spec, stack, opts = {}) {
+  const { bundle = [], include = [], exclude = [] } = spec;
+  const { lenient = false, warnings = [] } = opts;
+
+  /** @type {string[]} */
+  const items = [];
+  const add = (list) => {
+    for (const item of list) if (!items.includes(item)) items.push(item);
+  };
+
+  // 1. 每个被引用的模板各自完整解析（递归地含它自己的 bundle / include / exclude），取并集
+  for (const name of bundle) add(resolveBundle(repoRoot, name, stack));
+
+  // 2. 本层的 include 叠在并集之上
+  add(expandEntries(repoRoot, include));
+
+  // 3. 本层的 exclude 最后过一遍 —— 它能砍掉上面任何一步加进来的东西
+  const excluded = new Set(expandEntries(repoRoot, exclude, { lenient, warnings }));
+  const dropped = items.filter((item) => excluded.has(item));
+
+  return { items: items.filter((item) => !excluded.has(item)), dropped };
+}
+
+/**
+ * 解析一个 bundle，得到最终要安装的条目清单（保序、去重）。
+ *
+ * 流水线见 resolvePipeline，和项目级完全一致：
+ *   1. 本文件 `bundle` 引用的每个模板各自完整解析 → 取并集
+ *   2. 叠加本文件的 `include`
+ *   3. 最后过本文件的 `exclude`
+ *
+ * 也就是说**模板自己就是个小号的 agents.json**——`bundle` / `include` / `exclude`
+ * 三个字段的名字和含义都和项目根一模一样，不用记两套。
+ *
+ * @param {string} repoRoot @param {string} name @param {string[]} [stack]
+ * @returns {string[]}
+ */
+export function resolveBundle(repoRoot, name, stack = []) {
+  if (stack.includes(name)) {
+    throw new Error(`bundle 循环引用：${[...stack, name].join(' → ')}`);
+  }
+
+  const bundle = readBundle(repoRoot, name);
+  stack.push(name);
+
+  try {
+    return resolvePipeline(repoRoot, bundle, stack).items;
+  } finally {
+    stack.pop();
+  }
+}
+
+/**
+ * 解析一次完整的安装选择，得到最终条目清单。
+ *
+ * 流水线（每一步都在上一步的结果上做增删，实现在 resolvePipeline）：
+ *
+ *   1. 每个 bundle 各自解析（递归地含它自己的 bundle → include → exclude），然后取**并集**
+ *   2. 加上项目级 include
+ *   3. 减掉项目级 exclude —— 最后过一遍，它能砍掉上面任何一步加进来的东西
+ *
+ * 与模板唯一的差别是 exclude 更宽容：项目级的 exclude 指着一条已经不在的条目，
+ * 只告警不报错（理由见 expandEntry）。
+ *
+ * @param {string} repoRoot
+ * @param {{bundles?: string[], include?: string[], exclude?: string[]}} selection
+ * @returns {{items: string[], dropped: string[], warnings: string[]}}
+ */
+export function resolveSelection(repoRoot, selection = {}) {
+  const { bundles = [], include = [], exclude = [] } = selection;
+  /** @type {string[]} */
+  const warnings = [];
+
+  const { items, dropped } = resolvePipeline(
+    repoRoot,
+    { bundle: bundles, include, exclude },
+    [],
+    { lenient: true, warnings },
+  );
+
+  return { items, dropped, warnings };
+}
+
+/**
+ * 按类型把条目分组，方便安装时逐类处理。
+ * @param {string[]} items
+ * @returns {Record<string, string[]>}
+ */
+export function groupByKind(items) {
+  /** @type {Record<string, string[]>} */
+  const out = {};
+  for (const item of items) {
+    const { kind, id } = parseItem(item);
+    (out[kind] ??= []).push(id);
+  }
+  return out;
+}