cardbuddy 0.11.0 → 0.12.1

package/dist/vendored/tools/link-skills.mjs

@@ -0,0 +1,485 @@
+// tools/link-skills.mjs
+// 把仓库根 skills/（唯一物理副本）链接到主流 AI 工具的项目级 skills 目录。
+//
+// 支持两类落地方式：
+//   - directory：将整个 skills/ 链接成单个目录（WorkBuddy 使用 .workbuddy/skills）
+//   - skill-links：将 skills/ 下每个含 SKILL.md 的目录，逐个链接到工具 skills 目录
+//     （Qoder/Codex/ZCode/Claude Code 等使用）
+//
+// 首次运行会交互式列出工具并允许多选；选择结果写入 .local/link-skills.json，
+// 之后重复运行无需再次选择，只会增量同步当前 skills/ 的最新内容。
+//
+// 用法:
+//   node tools/link-skills.mjs                # 首次选择 / 之后按已保存选择同步
+//   node tools/link-skills.mjs --select       # 重新选择
+//   node tools/link-skills.mjs --list         # 查看支持的工具
+//   node tools/link-skills.mjs --tools qoder,workbuddy,zcode
+//   node tools/link-skills.mjs --all
+//   node tools/link-skills.mjs --dry-run      # 仅预览，不修改文件系统
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { execFileSync } from "node:child_process";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const SOURCE_DIR = join(ROOT, "skills");
+const CONFIG_FILE = join(ROOT, ".local", "link-skills.json");
+
+/**
+ * 工具清单。root 相对仓库根；mode:
+ *   - directory  : 把整个 skills/ 链接到 root/<linkName>
+ *   - skill-links: 把每个 skill 链接到 root/skills/<skillName>
+ */
+const TOOLS = [
+  { id: "workbuddy", name: "WorkBuddy", mode: "directory", root: ".workbuddy", linkName: "skills" },
+  { id: "qoder", name: "Qoder", mode: "skill-links", root: ".qoder" },
+  { id: "zcode", name: "ZCode", mode: "skill-links", root: ".zcode" },
+  { id: "codex", name: "Codex", mode: "skill-links", root: ".codex" },
+  { id: "claude", name: "Claude Code", mode: "skill-links", root: ".claude" },
+  { id: "cursor", name: "Cursor", mode: "skill-links", root: ".cursor" },
+  { id: "opencode", name: "OpenCode", mode: "skill-links", root: ".opencode" },
+  { id: "gemini", name: "Gemini CLI", mode: "skill-links", root: ".gemini" },
+  { id: "kilocode", name: "Kilo Code", mode: "skill-links", root: ".kilocode" },
+  { id: "cline", name: "Cline", mode: "skill-links", root: ".cline" },
+  { id: "roo", name: "Roo Code", mode: "skill-links", root: ".roo" },
+];
+
+const TOOL_BY_ID = new Map(TOOLS.map((tool) => [tool.id, tool]));
+
+function skillsRootFor(tool) {
+  if (tool.mode === "directory") {
+    return dirname(join(ROOT, tool.root, tool.linkName));
+  }
+  return join(ROOT, tool.root, "skills");
+}
+
+function skillLinkPathFor(tool, skillName) {
+  return join(skillsRootFor(tool), skillName);
+}
+
+function sourceSkillPath(skillName) {
+  return join(SOURCE_DIR, skillName);
+}
+
+function listSkills() {
+  try {
+    return readdirSync(SOURCE_DIR, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .filter((name) => existsSync(join(SOURCE_DIR, name, "SKILL.md")))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function isEmptyDir(path) {
+  try {
+    return lstatSync(path).isDirectory() && readdirSync(path).length === 0;
+  } catch {
+    return false;
+  }
+}
+
+function lstatOrNull(path) {
+  try {
+    return lstatSync(path);
+  } catch {
+    return null;
+  }
+}
+
+function realpathOrNull(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return null;
+  }
+}
+
+// 判断 linkPath 是否已经正确指向 expectedPath。
+// 使用 realpath 处理 WorkBuddy -> ../skills 这类链式链接。
+function linkIsValid(linkPath, expectedPath) {
+  const actual = realpathOrNull(linkPath);
+  if (!actual) return false;
+  const expected = realpathOrNull(expectedPath);
+  return Boolean(expected && actual === expected);
+}
+
+function ensureParentDir(path) {
+  mkdirSync(dirname(path), { recursive: true });
+}
+
+function removeEntry(path) {
+  rmSync(path, { recursive: true, force: true });
+}
+
+function assertPathCanBeReplaced(linkPath, label) {
+  const stat = lstatOrNull(linkPath);
+  if (!stat) return;
+
+  const isLinkLike =
+    stat.isSymbolicLink() ||
+    (process.platform === "win32" && stat.isDirectory()) ||
+    isEmptyDir(linkPath);
+
+  if (!isLinkLike) {
+    console.error(
+      `[link-skills] 错误：${label} ${linkPath} 是包含内容的实体目录且非链接。\n` +
+        `  唯一物理副本应为仓库根 skills/，请确认该目录无需保留后手动删除，再重试。`
+    );
+    process.exit(1);
+  }
+}
+
+function createJunctionOrSymlink(linkPath, targetPath) {
+  if (process.platform === "win32") {
+    execFileSync("cmd", ["/c", "mklink", "/J", linkPath, targetPath], { stdio: "inherit" });
+  } else {
+    const parent = dirname(linkPath);
+    const relTarget = relative(parent, targetPath);
+    execFileSync("ln", ["-s", relTarget, linkPath], { stdio: "inherit", cwd: parent });
+  }
+}
+
+function logLink(verb, linkPath, targetPath) {
+  console.log(`[link-skills] ${verb}: ${linkPath} -> ${targetPath}`);
+}
+
+function syncDirectoryLink(tool, { dryRun }) {
+  const linkPath = join(ROOT, tool.root, tool.linkName);
+  const targetPath = SOURCE_DIR;
+
+  if (linkIsValid(linkPath, targetPath)) {
+    console.log(`[link-skills] 已链接 ${tool.name}:`, linkPath, "→", targetPath);
+    return;
+  }
+
+  if (dryRun) {
+    console.log(`[dry-run] ${tool.name} 将链接:`, linkPath, "→", targetPath);
+    return;
+  }
+
+  assertPathCanBeReplaced(linkPath, `${tool.name} skills 目录`);
+  if (lstatOrNull(linkPath)) {
+    logLink("移除旧条目", linkPath, targetPath);
+    removeEntry(linkPath);
+  }
+
+  ensureParentDir(linkPath);
+  createJunctionOrSymlink(linkPath, targetPath);
+
+  if (!linkIsValid(linkPath, targetPath)) {
+    console.error(`[link-skills] 失败：${tool.name} 链接未生效，请检查平台权限。`);
+    process.exit(1);
+  }
+  logLink("已创建链接", linkPath, targetPath);
+}
+
+function staleSkillLinks(tool, currentSkillNames) {
+  const root = skillsRootFor(tool);
+  if (!existsSync(root)) return [];
+
+  const current = new Set(currentSkillNames);
+  const stale = [];
+
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (current.has(entry.name)) continue;
+    const entryPath = join(root, entry.name);
+    const stat = lstatOrNull(entryPath);
+    if (!stat) continue;
+
+    // 只清理“确实指向仓库 skills/ 下已不存在目标”的失效链接；
+    // 用户手工放置的其他链接（如 shared/）不要误删。
+    if (stat.isSymbolicLink() || (process.platform === "win32" && stat.isDirectory())) {
+      const actual = realpathOrNull(entryPath);
+      const isSourceSkillLink = actual && actual.startsWith(`${SOURCE_DIR}${sep}`);
+      if (!actual || (isSourceSkillLink && !existsSync(actual))) {
+        stale.push(entryPath);
+      }
+    }
+  }
+
+  return stale;
+}
+
+function syncSkillLinks(tool, { dryRun }) {
+  const root = skillsRootFor(tool);
+  const skills = listSkills();
+
+  if (skills.length === 0) {
+    console.warn(`[link-skills] 警告：${SOURCE_DIR} 下没有含 SKILL.md 的 skill。`);
+    return;
+  }
+
+  if (!dryRun) {
+    mkdirSync(root, { recursive: true });
+  }
+
+  for (const skillName of skills) {
+    const linkPath = skillLinkPathFor(tool, skillName);
+    const targetPath = sourceSkillPath(skillName);
+
+    if (linkIsValid(linkPath, targetPath)) {
+      console.log(`[link-skills] 已链接 ${tool.name}/${skillName}`);
+      continue;
+    }
+
+    if (dryRun) {
+      console.log(`[dry-run] ${tool.name} 将链接:`, linkPath, "→", targetPath);
+      continue;
+    }
+
+    assertPathCanBeReplaced(linkPath, `${tool.name}/${skillName}`);
+    if (lstatOrNull(linkPath)) {
+      removeEntry(linkPath);
+    }
+
+    createJunctionOrSymlink(linkPath, targetPath);
+
+    if (!linkIsValid(linkPath, targetPath)) {
+      console.error(`[link-skills] 失败：${tool.name}/${skillName} 链接未生效，请检查平台权限。`);
+      process.exit(1);
+    }
+    logLink("已创建链接", linkPath, targetPath);
+  }
+
+  if (!dryRun) {
+    for (const stalePath of staleSkillLinks(tool, skills.map((name) => name))) {
+      logLink("移除已不存在的旧 skill 链接", stalePath, "");
+      removeEntry(stalePath);
+    }
+  }
+}
+
+function readConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(toolIds) {
+  mkdirSync(dirname(CONFIG_FILE), { recursive: true });
+  writeFileSync(CONFIG_FILE, `${JSON.stringify({ tools: toolIds }, null, 2)}\n`);
+}
+
+function normalizeToolIds(ids) {
+  const valid = new Set(TOOL_BY_ID.keys());
+  const seen = new Set();
+  for (const id of ids) {
+    if (!valid.has(id)) {
+      console.error(`[link-skills] 未知工具: ${id}（可用 --list 查看）`);
+      process.exit(1);
+    }
+    seen.add(id);
+  }
+  return [...seen];
+}
+
+function printList() {
+  console.log("支持的工具：");
+  for (const [index, tool] of TOOLS.entries()) {
+    const path = tool.mode === "directory"
+      ? join(tool.root, tool.linkName)
+      : join(tool.root, "skills");
+    console.log(`  ${String(index + 1).padStart(2)}. ${tool.id.padEnd(10)} ${tool.name.padEnd(12)} ${path}`);
+  }
+}
+
+function printHelp() {
+  console.log(`用法: node tools/link-skills.mjs [options]
+
+选项:
+  --select, --reconfigure  重新选择工具（忽略已保存选择）
+  --list, -l               列出支持的工具
+  --tools <id[,id...]>     只同步指定工具，例如 --tools qoder,workbuddy
+  --all, -a                同步全部工具
+  --dry-run, -n            只打印将要执行的操作，不修改文件系统
+  --no-save                本次选择/操作不写入 .local/link-skills.json
+  --help, -h               显示帮助
+
+未传 --tools/--all 且存在已保存选择时，按已保存选择同步；
+否则在交互终端中列出工具并允许多选。`);
+}
+
+function parseAnswer(raw) {
+  const tokens = raw.trim().toLowerCase().split(/[\s,，、]+/).filter(Boolean);
+  const ids = [];
+
+  if (tokens.includes("a") || tokens.includes("all")) {
+    return TOOLS.map((tool) => tool.id);
+  }
+  if (tokens.includes("q") || tokens.includes("quit") || tokens.includes("c") || tokens.includes("cancel")) {
+    return [];
+  }
+
+  for (const token of tokens) {
+    if (/^\d+$/.test(token)) {
+      const index = Number(token) - 1;
+      if (TOOLS[index]) ids.push(TOOLS[index].id);
+    } else if (/^(\d+)-(\d+)$/.test(token)) {
+      const [, startRaw, endRaw] = token.match(/^(\d+)-(\d+)$/);
+      const start = Number(startRaw) - 1;
+      const end = Number(endRaw) - 1;
+      for (let index = Math.max(0, start); index <= Math.min(TOOLS.length - 1, end); index += 1) {
+        ids.push(TOOLS[index].id);
+      }
+    } else if (TOOL_BY_ID.has(token)) {
+      ids.push(token);
+    } else {
+      console.warn(`[link-skills] 忽略无法识别的选项: ${token}`);
+    }
+  }
+
+  return [...new Set(ids)];
+}
+
+async function promptForTools() {
+  console.log("选择要同步 skills 软链的工具（可多选）：");
+  for (const [index, tool] of TOOLS.entries()) {
+    const path = tool.mode === "directory"
+      ? join(tool.root, tool.linkName)
+      : join(tool.root, "skills");
+    console.log(`  ${String(index + 1).padStart(2)}. ${tool.name.padEnd(12)} ${path}`);
+  }
+  console.log("输入序号/工具 id，用逗号或空格分隔；a=全部，q=取消。");
+
+  const rl = createInterface({ input: stdin, output: process.stdout });
+  let answer;
+  try {
+    answer = await rl.question("> ");
+  } finally {
+    rl.close();
+  }
+
+  return parseAnswer(answer);
+}
+
+function readCliOptions(argv) {
+  const options = {
+    toolIds: null,
+    all: false,
+    list: false,
+    select: false,
+    dryRun: false,
+    save: true,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const next = argv[index + 1];
+
+    if (arg === "--select" || arg === "--reconfigure") {
+      options.select = true;
+    } else if (arg === "--list" || arg === "-l") {
+      options.list = true;
+    } else if (arg === "--all" || arg === "-a") {
+      options.all = true;
+    } else if (arg === "--dry-run" || arg === "-n") {
+      options.dryRun = true;
+    } else if (arg === "--no-save") {
+      options.save = false;
+    } else if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg === "--tools" || arg === "-t") {
+      const value = next && !next.startsWith("-") ? next : null;
+      if (value) {
+        options.toolIds = value.split(/[,\s]+/).filter(Boolean);
+        index += 1;
+      }
+    } else if (arg.startsWith("--tools=")) {
+      options.toolIds = arg.slice("--tools=".length).split(",").filter(Boolean);
+    }
+  }
+
+  return options;
+}
+
+function resolveToolIds(options, savedTools) {
+  if (options.all) return TOOLS.map((tool) => tool.id);
+  if (options.toolIds) return normalizeToolIds(options.toolIds);
+  if (!options.select && Array.isArray(savedTools)) {
+    console.log(`[link-skills] 使用已保存选择: ${savedTools.join(", ")}（--select 可重新选择）`);
+    return normalizeToolIds(savedTools);
+  }
+  return null;
+}
+
+async function main() {
+  const options = readCliOptions(process.argv.slice(2));
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  if (options.list) {
+    printList();
+    return;
+  }
+
+  const savedConfig = readConfig();
+  const savedTools = Array.isArray(savedConfig.tools) ? savedConfig.tools : null;
+  let toolIds = resolveToolIds(options, savedTools);
+
+  if (!toolIds) {
+    if (options.dryRun) {
+      toolIds = TOOLS.map((tool) => tool.id);
+      console.log("[link-skills] --dry-run 未指定工具，预览全部工具。");
+    } else if (stdin.isTTY) {
+      toolIds = await promptForTools();
+      if (!toolIds.length) {
+        console.log("[link-skills] 已取消，未修改任何内容。");
+        return;
+      }
+    } else {
+      toolIds = ["workbuddy"];
+      console.log(
+        "[link-skills] 非交互环境且无已保存选择，默认仅同步 WorkBuddy；" +
+          "可用 --tools/--all 显式指定。"
+      );
+    }
+  } else if (options.select) {
+    console.warn("[link-skills] 已提供 --tools/--all，忽略 --select。");
+  }
+
+  if (options.dryRun) {
+    console.log("[link-skills] dry-run：不会实际创建/删除链接。");
+  }
+
+  for (const id of toolIds) {
+    const tool = TOOL_BY_ID.get(id);
+    if (tool.mode === "directory") {
+      syncDirectoryLink(tool, { dryRun: options.dryRun });
+    } else {
+      syncSkillLinks(tool, { dryRun: options.dryRun });
+    }
+  }
+
+  if (!options.dryRun && options.save) {
+    writeConfig(toolIds);
+    console.log(`[link-skills] 已保存选择: ${toolIds.join(", ")} -> ${CONFIG_FILE}`);
+  }
+
+  console.log("[link-skills] 完成。");
+}
+
+main().catch((error) => {
+  console.error("[link-skills] 运行失败:", error);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cardbuddy",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Local dev service for the CardBuddy card editor — decouples card CRUD (sync/save/validate/render-status/screenshot) from the static public editor, so the editor can be deployed to any static host while each developer runs a local service against their own card source.",
   "type": "module",
   "bin": {
@@ -30,6 +30,7 @@
     "codejar": "^4.3.0",
     "connect": "^3.7.0",
     "dotenv": "^16.6.1",
+    "pngjs": "^5.0.0",
     "prismjs": "^1.30.0",
     "qrcode": "^1.5.4",
     "selfsigned": "^2.4.1",