agent-syncer 0.1.0

package/lib/prompt.js

@@ -0,0 +1,125 @@
+// @ts-check
+import process from 'node:process';
+import readline from 'node:readline';
+import { bold, cyan, dim, green } from './log.js';
+
+/**
+ * 是否具备交互条件。
+ *
+ * 必须严格判断：CI、管道、postinstall 里 stdin 不是 TTY，
+ * 这时弹提示会**永久挂住**——宁可退回非交互的默认行为，也不能卡住。
+ *
+ * @param {NodeJS.ReadStream} [input] @param {NodeJS.WriteStream} [output]
+ */
+export function isInteractive(input = process.stdin, output = process.stdout) {
+  return Boolean(input.isTTY && output.isTTY);
+}
+
+/**
+ * 多选列表。零依赖，用 node:readline 的 keypress 事件解析方向键。
+ *
+ * 按键：↑↓（或 k/j）移动　空格 勾选　a 全选/全不选　回车 确认　Ctrl-C 取消
+ *
+ * 输入输出可注入，便于测试时不必去动全局的 process.stdin / process.stdout。
+ *
+ * @param {{
+ *   message: string,
+ *   choices: {value: string, label: string, note?: string, checked?: boolean}[],
+ *   hint?: string,
+ *   input?: NodeJS.ReadStream,
+ *   output?: NodeJS.WriteStream,
+ * }} opts
+ * @returns {Promise<string[]|null>} 选中的 value 列表；取消返回 null
+ */
+export function checkbox({ message, choices, hint, input = process.stdin, output = process.stdout }) {
+  return new Promise((resolve) => {
+    if (choices.length === 0) {
+      resolve([]);
+      return;
+    }
+
+    const items = choices.map((c) => ({ ...c, checked: Boolean(c.checked) }));
+    const trailing = hint ?? '↑↓ 移动 · 空格 勾选 · a 全选 · 回车 确认 · Ctrl-C 取消';
+
+    let cursor = 0;
+    let drawn = 0;
+    let settled = false;
+
+    /** 重绘：先退回已画的行数再重画，避免刷屏 */
+    const render = (final = false) => {
+      if (drawn > 0) {
+        readline.moveCursor(output, 0, -drawn);
+        readline.cursorTo(output, 0);
+        readline.clearScreenDown(output);
+      }
+
+      const lines = [bold(message)];
+      items.forEach((c, i) => {
+        const active = i === cursor && !final;
+        const box = c.checked ? green('◉') : dim('◯');
+        const text = active ? cyan(c.label) : c.label;
+        lines.push(`  ${active ? cyan('❯') : ' '} ${box} ${text}${c.note ? `  ${dim(c.note)}` : ''}`);
+      });
+      if (!final) lines.push(dim(`  ${trailing}`));
+
+      output.write(`${lines.join('\n')}\n`);
+      drawn = lines.length;
+    };
+
+    /** @param {string[]|null} result */
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      input.removeListener('keypress', onKey);
+      try {
+        input.setRawMode(false);
+      } catch {
+        // 非 TTY 时 setRawMode 会抛，忽略即可
+      }
+      input.pause();
+      try {
+        render(true);
+      } catch {
+        // 输出流可能已被关闭，渲染失败不应影响返回值
+      }
+      resolve(result);
+    };
+
+    /** @param {string} _str @param {import('node:readline').Key} key */
+    const onKey = (_str, key) => {
+      if (!key) return;
+
+      if (key.ctrl && key.name === 'c') {
+        finish(null);
+        return;
+      }
+      if (key.name === 'up' || key.name === 'k') {
+        cursor = (cursor - 1 + items.length) % items.length;
+      } else if (key.name === 'down' || key.name === 'j') {
+        cursor = (cursor + 1) % items.length;
+      } else if (key.name === 'space') {
+        items[cursor].checked = !items[cursor].checked;
+      } else if (key.name === 'a') {
+        const allChecked = items.every((c) => c.checked);
+        for (const c of items) c.checked = !allChecked;
+      } else if (key.name === 'return' || key.name === 'enter') {
+        finish(items.filter((c) => c.checked).map((c) => c.value));
+        return;
+      } else {
+        return;
+      }
+
+      render();
+    };
+
+    readline.emitKeypressEvents(input);
+    try {
+      input.setRawMode(true);
+    } catch {
+      // 同上：真实交互场景下不会走到这里
+    }
+    input.resume();
+    input.on('keypress', onKey);
+    render();
+  });
+}

package/lib/target.js

@@ -0,0 +1,144 @@
+// @ts-check
+import path from 'node:path';
+
+/**
+ * 所有 AI 资产的规范存放目录（相对项目根）。
+ * 内容只在这一处保存一份，各工具目录通过链接指向它。
+ */
+export const CONTENT_ROOT = '.agents';
+
+/** 内容类型。与 .agents/ 下的子目录名一一对应。 */
+export const KINDS = ['skills', 'rules', 'commands', 'agents'];
+
+/**
+ * 工具 → 目标路径映射表。
+ *
+ * 这是全项目唯一需要关心「哪个工具把内容放哪」的地方——
+ * link.js / status.js / doctor.js 都不得出现 if-tool 分支。
+ *
+ * - claude：skills / rules / commands / agents 四类都是目录
+ *   （rules 目录的有效性已在本机 Claude Code 2.1.267 上实测确认，含嵌套子目录）
+ * - trae：三类目录，无 agents
+ * - codex：只有 skills 是目录。
+ *
+ *   ⚠️ 这不代表 Codex 没有规则机制——它有，只是形态不同。Codex 的规则走
+ *   **AGENTS.md 系列文件**而非目录，优先级为
+ *   `AGENTS.override.md` > `AGENTS.md` > `project_doc_fallback_filenames` 里配置的名字，
+ *   且按作用域生效（"the entire directory tree rooted at the folder that contains it"）。
+ *   它也没有 `@import` 语法，所以 rules 无法靠目录链接分发，只能合并进 AGENTS.md
+ *   （第二阶段实现）。合并时要留意 `project_doc_max_bytes`（默认 32768）。
+ */
+export const TOOLS = {
+  claude: {
+    label: 'Claude Code',
+    links: {
+      skills: '.claude/skills',
+      rules: '.claude/rules',
+      commands: '.claude/commands',
+      agents: '.claude/agents',
+    },
+  },
+  trae: {
+    label: 'Trae',
+    links: {
+      skills: '.trae/skills',
+      rules: '.trae/rules',
+      commands: '.trae/commands',
+    },
+  },
+  codex: {
+    label: 'Codex CLI',
+    links: {
+      skills: '.codex/skills',
+    },
+  },
+};
+
+export const TOOL_NAMES = Object.keys(TOOLS);
+
+/** 工具是否已知 */
+export function isTool(name) {
+  return Object.hasOwn(TOOLS, name);
+}
+
+/** 内容源目录的绝对路径：<项目根>/.agents/<kind> */
+export function contentDir(projectRoot, kind) {
+  return path.resolve(projectRoot, CONTENT_ROOT, kind);
+}
+
+/**
+ * 某工具支持的内容类型列表
+ * @param {string} tool
+ * @returns {string[]}
+ */
+export function kindsOf(tool) {
+  const cfg = TOOLS[tool];
+  if (!cfg) throw new Error(`未知工具：${tool}。可用值：${TOOL_NAMES.join(', ')}`);
+  return KINDS.filter((k) => Object.hasOwn(cfg.links, k));
+}
+
+/** 条目的规范写法："claude/skills" */
+export function specOf(tool, kind) {
+  return `${tool}/${kind}`;
+}
+
+/** 某工具支持的全部条目（用于 `tools` 形式的配置展开） */
+export function allSpecs(tool) {
+  return kindsOf(tool).map((k) => specOf(tool, k));
+}
+
+/**
+ * 解析 "claude/skills" 形式的条目。非法即抛错——配置写错时要立刻说清楚，
+ * 不能静默忽略，否则用户会以为已经生效。
+ * @param {string} spec
+ * @returns {{tool: string, kind: string}}
+ */
+export function parseSpec(spec) {
+  if (typeof spec !== 'string') {
+    throw new Error(`条目必须是字符串，收到 ${JSON.stringify(spec)}`);
+  }
+  const slash = spec.indexOf('/');
+  if (slash === -1) {
+    throw new Error(`条目 ${JSON.stringify(spec)} 格式不对，应为 "工具/类型"，例如 "claude/skills"`);
+  }
+  const tool = spec.slice(0, slash).trim().toLowerCase();
+  const kind = spec.slice(slash + 1).trim();
+
+  if (!isTool(tool)) {
+    throw new Error(`未知工具 "${tool}"（可用值：${TOOL_NAMES.join(', ')}）`);
+  }
+  if (!Object.hasOwn(TOOLS[tool].links, kind)) {
+    throw new Error(`工具 ${tool} 不支持内容类型 "${kind}"（可用：${kindsOf(tool).join(', ')}）`);
+  }
+  return { tool, kind };
+}
+
+/**
+ * 把条目展开成待处理的链接清单
+ * @param {string} projectRoot
+ * @param {string[]} specs
+ * @returns {{spec: string, tool: string, kind: string, rel: string, source: string, target: string}[]}
+ */
+export function plannedLinks(projectRoot, specs) {
+  return specs.map((spec) => {
+    const { tool, kind } = parseSpec(spec);
+    const rel = TOOLS[tool].links[kind];
+    return {
+      spec,
+      tool,
+      kind,
+      rel,
+      source: contentDir(projectRoot, kind),
+      target: path.resolve(projectRoot, rel),
+    };
+  });
+}
+
+/**
+ * 条目里出现过哪些工具，按 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

@@ -0,0 +1,34 @@
+{
+  "name": "agent-syncer",
+  "version": "0.1.0",
+  "description": "把 .agents/ 下的 AI 资产（skills / rules / commands）分发到 Claude Code、Trae、Codex 等工具的配置目录",
+  "type": "module",
+  "bin": {
+    "agent-syncer": "bin/agent-sync.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "claude-code",
+    "codex",
+    "trae",
+    "skills",
+    "symlink",
+    "junction"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT"
+}