@roarpeng/graphflow 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roarpeng/graphflow",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -72,7 +72,7 @@
     "@types/node": "^25.9.1",
     "@typescript-eslint/eslint-plugin": "^8.60.0",
     "@typescript-eslint/parser": "^8.60.0",
-    "@vitest/coverage-v8": "^4.1.8",
+    "@vitest/coverage-v8": "^3.2.6",
     "eslint": "^10.4.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.4.0",
@@ -80,7 +80,7 @@
     "tree-sitter-wasms": "0.1.11",
     "tsx": "^4.22.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^3.2.6"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/scripts/safe-postinstall.cjs

@@ -1,11 +1,56 @@
 #!/usr/bin/env node
-const { existsSync, mkdirSync, copyFileSync, readFileSync } = require("node:fs");
+const { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, unlinkSync } = require("node:fs");
 const { join } = require("node:path");
 const { homedir } = require("node:os");
 const { spawnSync } = require("node:child_process");
 
 const isWindows = process.platform === "win32";
 
+// ─── 版本比较与自动更新 ───
+
+/** 版本标记文件路径：记录上次安装的 GraphFlow 版本号 */
+const VERSION_FILE = join(homedir(), ".graphflow-install-version");
+
+/**
+ * 读取上次安装时记录的版本号
+ * @returns {string | null} 上次版本号，不存在则返回 null
+ */
+function readPreviousVersion() {
+  try {
+    if (existsSync(VERSION_FILE)) {
+      return readFileSync(VERSION_FILE, "utf8").trim();
+    }
+  } catch {
+    // 忽略读取失败
+  }
+  return null;
+}
+
+/**
+ * 将当前版本号写入标记文件
+ * @param {string} version 当前版本号
+ */
+function writeCurrentVersion(version) {
+  try {
+    writeFileSync(VERSION_FILE, version, "utf8");
+  } catch {
+    // 忽略写入失败
+  }
+}
+
+/**
+ * 比较版本号，判断是否需要强制更新 Skill/Rules/MCP 文件
+ * @param {string} currentVersion 当前安装的版本号
+ * @returns {boolean} 是否需要强制更新
+ */
+function needsForceUpdate(currentVersion) {
+  const previousVersion = readPreviousVersion();
+  if (!previousVersion) {
+    return true; // 首次安装或无版本记录，强制更新
+  }
+  return previousVersion !== currentVersion;
+}
+
 function resolveHomePaths() {
   const home = homedir();
   const appData = process.env.APPDATA || (isWindows ? join(home, "AppData", "Roaming") : "");
@@ -147,6 +192,231 @@ function isGlobalInstall() {
   return false;
 }
 
+/**
+ * 获取 Cursor Rules 源文件路径（graphflow.mdc）
+ * 优先从 dist 目录查找，回退到 src 目录。
+ * @returns {string | null} 源文件路径，不存在则返回 null
+ */
+function getCursorRulesSourceFile() {
+  const candidates = [
+    join(__dirname, "..", "dist", "surfaces", "cursor-rules", "graphflow.mdc"),
+    join(__dirname, "..", "src", "surfaces", "cursor-rules", "graphflow.mdc"),
+  ];
+  for (const filePath of candidates) {
+    if (existsSync(filePath)) {
+      return filePath;
+    }
+  }
+  return null;
+}
+
+/**
+ * 获取 CLAUDE.md 源文件路径
+ * 优先从包根目录查找。
+ * @returns {string | null} 源文件路径，不存在则返回 null
+ */
+function getClaudeMdSourceFile() {
+  const candidates = [
+    join(__dirname, "..", "CLAUDE.md"),
+  ];
+  for (const filePath of candidates) {
+    if (existsSync(filePath)) {
+      return filePath;
+    }
+  }
+  return null;
+}
+
+/**
+ * 获取 Cursor rules 目录列表。
+ * Cursor 的 rules 目录为 ~/.cursor/rules/（跨平台一致），
+ * 也有用户使用 %APPDATA%/Cursor/User/rules/。
+ * @returns {Array<{name: string, rulesDir: string}>} Cursor rules 目录列表
+ */
+function getCursorRulesDirs() {
+  const { home, appData } = resolveHomePaths();
+  const dirs = [];
+
+  // ~/.cursor/rules — Cursor 的标准 rules 目录
+  if (existsSync(join(home, ".cursor"))) {
+    dirs.push({
+      name: "Cursor (~/.cursor)",
+      rulesDir: join(home, ".cursor", "rules"),
+    });
+  }
+
+  // %APPDATA%/Cursor/User/rules — Windows 上的备选目录
+  if (isWindows && existsSync(join(appData, "Cursor", "User"))) {
+    dirs.push({
+      name: "Cursor (AppData)",
+      rulesDir: join(appData, "Cursor", "User", "rules"),
+    });
+  }
+
+  return dirs;
+}
+
+/**
+ * 通用文件安装逻辑：检测 marker → 创建目标目录 → 复制文件 → 已存在且内容相同则跳过
+ * @param {string} sourceFile 源文件路径
+ * @param {string} destDir 目标目录
+ * @param {string} destFileName 目标文件名
+ * @returns {{status: string, reason?: string}} 安装结果
+ */
+function installFileToDir(sourceFile, destDir, destFileName) {
+  if (!existsSync(sourceFile)) {
+    return { status: "skipped", reason: "源文件不存在" };
+  }
+
+  const destFile = join(destDir, destFileName);
+  const existed = existsSync(destFile);
+
+  if (existed) {
+    const existingContent = readFileSync(destFile, "utf8");
+    const newContent = readFileSync(sourceFile, "utf8");
+    if (existingContent === newContent) {
+      return { status: "skipped", reason: "已是最新" };
+    }
+  }
+
+  mkdirSync(destDir, { recursive: true });
+  copyFileSync(sourceFile, destFile);
+
+  return { status: existed ? "updated" : "created" };
+}
+
+/**
+ * 检测并安装 Cursor Rules（graphflow.mdc）到 Cursor rules 目录
+ * @returns {{status: string, reason?: string} | null} 安装结果，无需安装则返回 null
+ */
+function installCursorRules() {
+  const sourceFile = getCursorRulesSourceFile();
+  if (!sourceFile) {
+    return { status: "skipped", reason: "Cursor Rules 源文件不存在" };
+  }
+
+  const dirs = getCursorRulesDirs();
+  if (dirs.length === 0) {
+    return null; // 未检测到 Cursor，跳过
+  }
+
+  // 只需要安装到第一个有效目录
+  const target = dirs[0];
+  return installFileToDir(sourceFile, target.rulesDir, "graphflow.mdc");
+}
+
+/**
+ * 检测并安装 CLAUDE.md 到 ~/.claude/CLAUDE.md（Claude Code 约定）
+ * @returns {{status: string, reason?: string} | null} 安装结果，无需安装则返回 null
+ */
+function installClaudeMd() {
+  const sourceFile = getClaudeMdSourceFile();
+  if (!sourceFile) {
+    return { status: "skipped", reason: "CLAUDE.md 源文件不存在" };
+  }
+
+  const { home } = resolveHomePaths();
+  const claudeDir = join(home, ".claude");
+
+  // 检测 ~/.claude 是否存在（Claude Code 的 marker 目录）
+  if (!existsSync(claudeDir)) {
+    return null; // 未检测到 Claude Code，跳过
+  }
+
+  return installFileToDir(sourceFile, claudeDir, "CLAUDE.md");
+}
+
+/**
+ * 注入 workspace 级 MCP 配置到已存在的 workspace MCP 文件。
+ * 仅在检测到 .cursor/mcp.json 或 .vscode/mcp.json 时生效（更安全，只在当前项目内）。
+ * @param {string} workspaceRoot 当前项目根目录
+ * @returns {Array<{configPath: string, status: string}>} 注入结果列表
+ */
+function installWorkspaceLevelMcp(workspaceRoot) {
+  const results = [];
+  const configFiles = [
+    { path: join(workspaceRoot, ".cursor", "mcp.json"), name: "Cursor", key: "mcpServers" },
+    { path: join(workspaceRoot, ".vscode", "mcp.json"), name: "VS Code", key: "servers" },
+  ];
+
+  const mcpEntry = {
+    command: "npx",
+    args: ["-y", "--package=@roarpeng/graphflow", "graphflow-mcp"],
+    env: { GRAPHFLOW_MCP_STDIO: "1", GRAPHFLOW_LOG_JSON: "1" },
+  };
+
+  for (const config of configFiles) {
+    if (!existsSync(config.path)) {
+      continue; // 该 workspace 级配置不存在，跳过
+    }
+
+    try {
+      let json = {};
+      try {
+        json = JSON.parse(readFileSync(config.path, "utf8"));
+      } catch {
+        // 配置文件为空或损坏，初始化为空对象
+      }
+
+      const servers = json[config.key] || {};
+      if (servers.graphflow) {
+        results.push({ configPath: config.path, status: "skipped", name: config.name, reason: "already configured" });
+        continue;
+      }
+
+      servers.graphflow = mcpEntry;
+      json[config.key] = servers;
+      writeFileSync(config.path, JSON.stringify(json, null, 2) + "\n", "utf8");
+      results.push({ configPath: config.path, status: "created", name: config.name });
+      console.log(`[GraphFlow] Workspace 级 MCP 已注入到 ${config.path} (${config.name})`);
+    } catch (err) {
+      results.push({ configPath: config.path, status: "error", name: config.name, reason: err.message });
+      console.log(`[GraphFlow] Workspace 级 MCP 注入失败 ${config.path}: ${err.message}`);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * 在 workspace 级创建 .graphflow/skills/ 目录并复制 Skill 文件。
+ * 仅在检测到 .cursor/mcp.json 或 .vscode/mcp.json 时生效。
+ * @param {string} workspaceRoot 当前项目根目录
+ */
+function installWorkspaceLevelSkills(workspaceRoot) {
+  const configFiles = [
+    join(workspaceRoot, ".cursor", "mcp.json"),
+    join(workspaceRoot, ".vscode", "mcp.json"),
+  ];
+  const hasWorkspaceConfig = configFiles.some((p) => existsSync(p));
+
+  if (!hasWorkspaceConfig) {
+    return; // 无 workspace 级 MCP 配置，跳过 Skill 安装
+  }
+
+  const skillSourceDir = getSkillSourceDir();
+  if (!skillSourceDir) {
+    return;
+  }
+
+  // 在 .graphflow/skills/graphflow/ 下创建 workspace 级 Skill
+  const skillDestDir = join(workspaceRoot, ".graphflow", "skills", "graphflow");
+  const result = installSkill(skillDestDir, skillSourceDir);
+  if (result.status !== "skipped") {
+    console.log(`[GraphFlow] Workspace 级 Skill: ${result.status}${result.reason ? ` (${result.reason})` : ""} -> ${skillDestDir}`);
+  }
+
+  // 同时安装 Cursor Rules 到 workspace 级 .cursor/rules/
+  const cursorRulesSource = getCursorRulesSourceFile();
+  if (cursorRulesSource && existsSync(join(workspaceRoot, ".cursor"))) {
+    const cursorRulesDir = join(workspaceRoot, ".cursor", "rules");
+    const rulesResult = installFileToDir(cursorRulesSource, cursorRulesDir, "graphflow.mdc");
+    if (rulesResult.status !== "skipped") {
+      console.log(`[GraphFlow] Workspace 级 Cursor Rules: ${rulesResult.status}${rulesResult.reason ? ` (${rulesResult.reason})` : ""}`);
+    }
+  }
+}
+
 function main() {
   if (process.env.GRAPHFLOW_SKIP_POSTINSTALL === "1" || process.env.CI === "true") {
     process.exit(0);
@@ -156,13 +426,44 @@ function main() {
   const explicitlyEnabled = process.env.GRAPHFLOW_ENABLE_POSTINSTALL === "1";
 
   if (!globalInstall && !explicitlyEnabled) {
-    console.log("[GraphFlow] Local install detected. Auto-setup skipped to avoid modifying your global config.");
-    console.log("[GraphFlow] To install GraphFlow MCP + Skill, run:");
-    console.log("[GraphFlow]   npx @roarpeng/graphflow install");
+    // 本地安装：检测 workspace 级 MCP 配置，若有则自动注入 workspace 级 MCP + Skill
+    const workspaceRoot = process.cwd();
+    const workspaceMcpResults = installWorkspaceLevelMcp(workspaceRoot);
+    const hasWorkspaceConfig = workspaceMcpResults.some((r) => r.status === "created" || r.status === "skipped");
+
+    if (hasWorkspaceConfig) {
+      console.log("[GraphFlow] 检测到 workspace 级 MCP 配置，已自动注入 workspace 级 GraphFlow MCP。");
+      installWorkspaceLevelSkills(workspaceRoot);
+      console.log("[GraphFlow] 如需完整安装（用户级 MCP + Trae Skill），运行:");
+      console.log("[GraphFlow]   npx @roarpeng/graphflow install");
+    } else {
+      console.log("[GraphFlow] Local install detected. Auto-setup skipped to avoid modifying your global config.");
+      console.log("[GraphFlow] To install GraphFlow MCP + Skill, run:");
+      console.log("[GraphFlow]   npx @roarpeng/graphflow install");
+    }
     process.exit(0);
   }
 
+  // 读取当前版本号，用于版本比较和强制更新
+  let currentVersion = "unknown";
+  try {
+    const pkg = require("../package.json");
+    currentVersion = pkg.version || "unknown";
+  } catch {
+    // npm 包中 package.json 在上层目录；如果读取失败则跳过版本比较
+  }
+
+  const forceUpdate = needsForceUpdate(currentVersion);
+  const previousVersion = readPreviousVersion();
+
   console.log(`[GraphFlow] Running post-install setup (${globalInstall ? "global install" : "explicitly enabled"})...`);
+  console.log(`[GraphFlow] 版本: ${currentVersion}`);
+
+  if (forceUpdate && previousVersion) {
+    console.log(`[GraphFlow] 检测到版本变化 (${previousVersion} → ${currentVersion})，将强制更新所有 Skill/Rules/MCP 文件`);
+  } else if (forceUpdate && !previousVersion) {
+    console.log("[GraphFlow] 首次安装，将安装所有 Skill/Rules/MCP 文件");
+  }
 
   const skillSourceDir = getSkillSourceDir();
   const traeDirs = getTraeUserDirs();
@@ -185,6 +486,23 @@ function main() {
     console.log(`[GraphFlow] MCP install skipped: ${mcpResult.reason}`);
   }
 
+  // ─── Cursor Rules 安装 ───
+  const cursorRulesResult = installCursorRules();
+  if (cursorRulesResult) {
+    console.log(`[GraphFlow] Cursor Rules: ${cursorRulesResult.status}${cursorRulesResult.reason ? ` (${cursorRulesResult.reason})` : ""}`);
+  }
+
+  // ─── Claude Code 约定安装 ───
+  const claudeMdResult = installClaudeMd();
+  if (claudeMdResult) {
+    console.log(`[GraphFlow] Claude Code 约定: ${claudeMdResult.status}${claudeMdResult.reason ? ` (${claudeMdResult.reason})` : ""}`);
+  }
+
+  // 写入当前版本号标记文件
+  if (currentVersion !== "unknown") {
+    writeCurrentVersion(currentVersion);
+  }
+
   console.log("[GraphFlow] Post-install complete.");
 }
 
@@ -192,4 +510,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { installSkill, detectTrae, getTraeUserDirs, getSkillSourceDir };
+module.exports = { installSkill, detectTrae, getTraeUserDirs, getSkillSourceDir, readPreviousVersion, writeCurrentVersion, needsForceUpdate, VERSION_FILE };