@reglow/reui-mcp 0.1.0

package/setup.mjs

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+/**
+ * reui-setup：为 Trae / CodeBuddy / Qoder 等 AI 工具一键配置 ReUI 能力
+ *
+ * 做两件事：
+ * 1. **写 MCP 配置** —— 在项目（或用户级）配置文件中合并 `mcpServers["reui-mcp"]` 条目；
+ * 2. **装 Skills** —— 把 `skills/reui-components/` 复制到该工具的 Skills 目录。
+ *
+ * 用法：
+ *   npx -y -p @reglow/reui-mcp reui-setup                       # 默认 trae,codebuddy,qoder
+ *   npx -y -p @reglow/reui-mcp reui-setup --tools trae,qoder    # 只配指定工具
+ *   npx -y -p @reglow/reui-mcp reui-setup --tools all --scope user
+ *   npx -y -p @reglow/reui-mcp reui-setup --dry-run             # 仅预览将写入的内容
+ *
+ * 也支持通过主命令：npx -y @reglow/reui-mcp --setup trae,codebuddy,qoder
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEntryModule } from "./cli-utils.mjs";
+import {
+  ALL_TOOLS,
+  DEFAULT_ARGS,
+  DEFAULT_SERVER_NAME,
+  DEFAULT_SETUP_TOOLS,
+  TOOL_INTEGRATIONS,
+  buildMcpEntry,
+  parseTools,
+  resolveConfigPath,
+  resolveSkillsDir,
+} from "./integrations.mjs";
+import { installSkills } from "./skills.mjs";
+
+// ============================ JSONC 解析与合并 ============================
+
+/**
+ * 解析 JSONC（JSON with Comments）
+ *
+ * 支持 `//` 行注释、`/* *​/` 块注释与尾逗号 —— CodeBuddy / Qoder 的配置文件允许这些写法。
+ * 注释出现在字符串内部时不会被误删。
+ */
+export function parseJsonc(text) {
+  const source = String(text ?? "").replace(/^\uFEFF/, "");
+  let output = "";
+  let inString = false;
+  let quote = "";
+  for (let i = 0; i < source.length; i += 1) {
+    const char = source[i];
+    const next = source[i + 1];
+    if (inString) {
+      output += char;
+      if (char === "\\") {
+        output += next ?? "";
+        i += 1;
+        continue;
+      }
+      if (char === quote) inString = false;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      inString = true;
+      quote = char;
+      output += char;
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      const end = source.indexOf("\n", i);
+      i = end === -1 ? source.length : end - 1;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      const end = source.indexOf("*/", i + 2);
+      i = end === -1 ? source.length : end + 1;
+      continue;
+    }
+    output += char;
+  }
+  // 去尾逗号（对象 / 数组末尾）
+  output = output.replace(/,(\s*[}\]])/g, "$1");
+  return JSON.parse(output);
+}
+
+/** 读取 MCP 配置文件（不存在 / 为空时返回空对象） */
+export function readMcpConfig(file) {
+  if (!file || !fs.existsSync(file))
+    return { data: {}, exists: false, raw: "", hadComments: false };
+  const raw = fs.readFileSync(file, "utf8");
+  const hadComments = /(^|[^:"'])\/\/|(^|[^:"'])\/\*/.test(raw);
+  if (raw.trim() === "")
+    return { data: {}, exists: true, raw, hadComments: false };
+  try {
+    return { data: parseJsonc(raw), exists: true, raw, hadComments };
+  } catch (error) {
+    return { data: null, exists: true, raw, hadComments, error: error.message };
+  }
+}
+
+/** 把 server 条目合并进 mcpServers，返回新对象与变更信息 */
+export function mergeMcpConfig(
+  existing,
+  { serverName = DEFAULT_SERVER_NAME, entry } = {},
+) {
+  const base = existing && typeof existing === "object" ? existing : {};
+  const servers = { ...(base.mcpServers ?? {}) };
+  const previous = servers[serverName];
+  servers[serverName] = { ...entry };
+  const changed = JSON.stringify(previous) !== JSON.stringify(entry);
+  return { next: { ...base, mcpServers: servers }, previous, changed };
+}
+
+function serializeConfig(data) {
+  return `${JSON.stringify(data, null, 2)}\n`;
+}
+
+// ============================ 单工具配置 ============================
+
+/**
+ * 配置单个工具（写 MCP 配置 + 装 Skills）
+ *
+ * @param {{
+ *   tool: string,
+ *   cwd?: string,
+ *   scope?: "project" | "user",
+ *   serverName?: string,
+ *   args?: string[],
+ *   env?: Record<string, string>,
+ *   dryRun?: boolean,
+ *   force?: boolean,
+ *   withMcp?: boolean,
+ *   withSkills?: boolean,
+ *   installSkillsFn?: typeof installSkills,
+ * }} options
+ */
+export function setupTool(options) {
+  const {
+    tool,
+    cwd = process.cwd(),
+    scope = "project",
+    serverName = DEFAULT_SERVER_NAME,
+    args = DEFAULT_ARGS,
+    env,
+    dryRun = false,
+    force = false,
+    withMcp = true,
+    withSkills = true,
+  } = options;
+
+  const spec = TOOL_INTEGRATIONS[tool];
+  if (!spec)
+    throw new Error(`未知工具「${tool}」，可选：${ALL_TOOLS.join(" / ")}`);
+
+  const result = {
+    tool,
+    label: spec.label,
+    scope,
+    status: "ok",
+    configFile: null,
+    configAction: null,
+    configError: null,
+    hadComments: false,
+    skillsDir: null,
+    skillFiles: [],
+    skippedSkillFiles: [],
+    manualSteps: [...(spec.mcp.manualSteps ?? [])],
+    notes: [...(spec.mcp.notes ?? [])],
+    docsUrl: spec.docsUrl,
+  };
+
+  // ---- MCP 配置 ----
+  if (withMcp) {
+    const file = resolveConfigPath(tool, scope, { cwd });
+    result.configFile = file;
+    if (!file) {
+      result.status = "skipped";
+      result.configAction =
+        scope === "user" ? "该工具无用户级配置文件" : "该工具无项目级配置文件";
+    } else {
+      const entry = buildMcpEntry(tool, { serverName, args, env });
+      const { data, exists, hadComments, error } = readMcpConfig(file);
+      result.hadComments = Boolean(hadComments);
+      if (error && !force) {
+        result.status = "error";
+        result.configError = `配置文件不是合法 JSON/JSONC（${error}）；加 --force 将备份后用标准 JSON 重写`;
+        result.manualSteps = [
+          `手动在 ${file} 中加入：mcpServers.${serverName} = ${JSON.stringify(entry)}`,
+        ];
+      } else {
+        const { next, previous, changed } = mergeMcpConfig(data ?? {}, {
+          serverName,
+          entry,
+        });
+        const action = !exists ? "created" : changed ? "updated" : "unchanged";
+        result.configAction = action;
+        result.serverEntry = entry;
+        if (!dryRun) {
+          fs.mkdirSync(path.dirname(file), { recursive: true });
+          if (error && force && exists) {
+            fs.copyFileSync(file, `${file}.bak`);
+            result.configAction = "rewritten";
+          }
+          fs.writeFileSync(file, serializeConfig(next));
+        }
+        result.previousEntry = previous;
+      }
+    }
+  }
+
+  // ---- Skills ----
+  if (withSkills) {
+    const dir = resolveSkillsDir(tool, scope, { cwd });
+    result.skillsDir = dir;
+    if (!dir) {
+      if (result.status === "ok") result.status = "skipped";
+      result.skillFiles = [];
+    } else {
+      const relative = path.relative(cwd, dir) || dir;
+      const installed = (options.installSkillsFn ?? installSkills)({
+        cwd,
+        targets: [relative],
+        force,
+        dryRun,
+        logger: () => { },
+      });
+      result.skillFiles = installed.installed[0]?.files ?? [];
+      result.skippedSkillFiles = installed.installed[0]?.skipped ?? [];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 批量配置（默认 Trae / CodeBuddy / Qoder）
+ *
+ * @param {{ tools?: string[], cwd?: string, scope?: "project"|"user", serverName?: string,
+ *           args?: string[], env?: Record<string,string>, dryRun?: boolean, force?: boolean,
+ *           withMcp?: boolean, withSkills?: boolean }} options
+ */
+export function setup(options = {}) {
+  const tools = options.tools?.length
+    ? options.tools
+    : [...DEFAULT_SETUP_TOOLS];
+  const results = tools.map((tool) => setupTool({ ...options, tool }));
+  return {
+    cwd: options.cwd ?? process.cwd(),
+    scope: options.scope ?? "project",
+    serverName: options.serverName ?? DEFAULT_SERVER_NAME,
+    results,
+  };
+}
+
+// ============================ 输出 ============================
+
+const ACTION_LABEL = {
+  created: "已新建",
+  updated: "已更新",
+  unchanged: "无变化",
+  rewritten: "已备份并重写",
+};
+
+/** 生成人类可读的配置报告 */
+export function renderSetupReport(report, { dryRun = false } = {}) {
+  const lines = [];
+  lines.push(
+    `${dryRun ? "[dry-run] " : ""}ReUI AI 能力配置（scope=${report.scope}）`,
+  );
+  lines.push("");
+  for (const item of report.results) {
+    lines.push(`## ${item.label}（${item.tool}）`);
+    if (item.configFile) {
+      const action =
+        ACTION_LABEL[item.configAction] ?? item.configAction ?? "-";
+      lines.push(`- MCP 配置：\`${item.configFile}\` → ${action}`);
+      if (item.configError) lines.push(`  ⚠️ ${item.configError}`);
+      if (item.hadComments && item.configAction !== "unchanged") {
+        lines.push("  ℹ️ 原文件含注释，已按标准 JSON 重写（请留意注释丢失）");
+      }
+    }
+    if (item.skillsDir) {
+      const written = item.skillFiles.length;
+      const skipped = item.skippedSkillFiles.length;
+      lines.push(
+        `- Skills 目录：\`${item.skillsDir}\` → 写入 ${written} 个文件${skipped ? `，跳过已存在 ${skipped} 个（--force 可覆盖）` : ""}`,
+      );
+    }
+    if (item.manualSteps.length > 0) {
+      lines.push("- 仍需手动完成：");
+      for (const step of item.manualSteps) lines.push(`  - ${step}`);
+    }
+    lines.push("");
+  }
+  lines.push(
+    "下一步：重启（或重载）对应工具，然后让 AI「用 reui 组件写一个 XX 页面」验证工具是否被调用。",
+  );
+  lines.push(`校验 MCP 本体：npx -y ${DEFAULT_ARGS[1]} --check`);
+  return lines.join("\n");
+}
+
+// ============================ CLI ============================
+
+const SETUP_USAGE = [
+  "reui-setup —— 为 AI 工具一键配置 ReUI（MCP + Skills）",
+  "",
+  "用法：npx -y -p @reglow/reui-mcp reui-setup [选项]",
+  "",
+  "选项：",
+  `      --tools <list>      目标工具，逗号分隔（默认 ${DEFAULT_SETUP_TOOLS.join(",")}）；all = 全部（${ALL_TOOLS.join("/")}）`,
+  "      --scope <scope>     project（默认）| user（写入用户级配置目录）",
+  "      --server-name <n>   MCP 服务器名，默认 reui-mcp",
+  "      --cwd <dir>         项目根目录，默认当前目录",
+  "      --skills-only       只安装 Skills，不写 MCP 配置",
+  "      --mcp-only          只写 MCP 配置，不安装 Skills",
+  "      --dry-run           只打印将要写入的内容",
+  "      --force             覆盖已存在的 Skills 文件；配置非法时备份后重写",
+  "      --list-tools        列出支持的工具与路径",
+  "  -h, --help              显示帮助",
+].join("\n");
+
+/** 列出各工具的项目级 MCP 配置文件与 Skills 目录 */
+export function renderToolList(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const lines = [`支持的工具（项目级默认路径，cwd=${cwd}）：`, ""];
+  for (const tool of ALL_TOOLS) {
+    const spec = TOOL_INTEGRATIONS[tool];
+    lines.push(`- ${spec.label}（${tool}）`);
+    lines.push(`  - MCP 配置：${resolveConfigPath(tool, "project", { cwd })}`);
+    lines.push(`  - Skills：${resolveSkillsDir(tool, "project", { cwd })}`);
+    if (spec.mcp.userFile) {
+      lines.push(`  - 用户级：${resolveConfigPath(tool, "user", { cwd })}`);
+    }
+    lines.push(`  - 文档：${spec.docsUrl}`);
+  }
+  return lines.join("\n");
+}
+
+/** CLI 入口 */
+export function runSetupCli(argv = process.argv.slice(2)) {
+  const options = {
+    dryRun: false,
+    force: false,
+    scope: "project",
+    withMcp: true,
+    withSkills: true,
+  };
+  let toolsInput;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--tools" || arg === "-t") toolsInput = argv[++i];
+    else if (arg.startsWith("--tools="))
+      toolsInput = arg.slice("--tools=".length);
+    else if (arg === "--scope") options.scope = argv[++i];
+    else if (arg.startsWith("--scope="))
+      options.scope = arg.slice("--scope=".length);
+    else if (arg === "--server-name") options.serverName = argv[++i];
+    else if (arg.startsWith("--server-name="))
+      options.serverName = arg.slice("--server-name=".length);
+    else if (arg === "--cwd") options.cwd = argv[++i];
+    else if (arg.startsWith("--cwd=")) options.cwd = arg.slice("--cwd=".length);
+    else if (arg === "--dry-run") options.dryRun = true;
+    else if (arg === "--force") options.force = true;
+    else if (arg === "--skills-only") options.withMcp = false;
+    else if (arg === "--mcp-only") options.withSkills = false;
+    else if (arg === "--list-tools") {
+      console.log(renderToolList(options));
+      return 0;
+    } else if (arg === "--help" || arg === "-h") {
+      console.log(SETUP_USAGE);
+      return 0;
+    } else if (!arg.startsWith("-") && !toolsInput) {
+      // 兼容 `--setup trae,codebuddy` 这类「位置参数即工具清单」的写法
+      toolsInput = arg;
+    }
+  }
+
+  if (options.scope !== "project" && options.scope !== "user") {
+    console.error(
+      `[reui-setup] --scope 仅支持 project / user，收到：${options.scope}`,
+    );
+    return 1;
+  }
+
+  const tools = parseTools(toolsInput);
+  const report = setup({ ...options, tools });
+  console.log(renderSetupReport(report, { dryRun: options.dryRun }));
+  if (options.dryRun) {
+    console.log("（dry-run 模式：以上内容未写入磁盘）");
+  }
+  return report.results.some((item) => item.status === "error") ? 1 : 0;
+}
+
+if (isEntryModule(import.meta.url)) {
+  try {
+    process.exitCode = runSetupCli();
+  } catch (error) {
+    console.error(`[reui-setup] 配置失败：${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/site.mjs

@@ -0,0 +1,155 @@
+/**
+ * 官方文档站点兜底读取
+ *
+ * 当本地 / 指定版本的包内缺少组件文档（例如历史版本未把 `components/**` 打进产物）时，
+ * 回退抓取官方文档站点 https://reglow.huoli.tech/components-library/reui 的组件页并转成 Markdown。
+ * 返回值中始终标注来源与链接，便于 AI 明确「这是最新版官网内容」。
+ */
+
+import { DOCS_BASE, docsUrlFor } from "./catalog.mjs";
+
+const DEFAULT_TIMEOUT = 15000;
+/** 单页最大读取字节，防御异常大页面 */
+const MAX_BYTES = 3 * 1024 * 1024;
+
+/** 解开常见 HTML 实体 */
+function decodeEntities(text) {
+  return text
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&apos;/g, "'")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, code) => String.fromCodePoint(Number.parseInt(code, 16)));
+}
+
+/** 去掉标签、解码实体、压缩空白（行内片段用） */
+function inlineText(html) {
+  return decodeEntities(html.replace(/<[^>]*>/g, ""))
+    .replace(/[ \t]+/g, " ")
+    .trim();
+}
+
+/**
+ * HTML → 简化 Markdown
+ *
+ * 覆盖官方文档页实际用到的元素：标题、段落、列表、表格、代码块、行内代码、链接、强调。
+ * 目标是「让 AI 拿到可读正文」，不追求像素级还原。
+ */
+export function htmlToMarkdown(html) {
+  let source = String(html ?? "")
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(/<script[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[\s\S]*?<\/style>/gi, "")
+    .replace(/<svg[\s\S]*?<\/svg>/gi, "");
+
+  // 尽量只取正文区域
+  const regionMatch =
+    source.match(/<main[^>]*>([\s\S]*?)<\/main>/i) ??
+    source.match(/<article[^>]*>([\s\S]*?)<\/article>/i);
+  if (regionMatch) source = regionMatch[1];
+
+  // 代码块：先占位，避免内部标签/空白被后续处理破坏
+  const codeBlocks = [];
+  source = source.replace(/<pre[^>]*>([\s\S]*?)<\/pre>/gi, (_match, inner) => {
+    const code = decodeEntities(
+      inner
+        .replace(/<br\s*\/?>/gi, "\n")
+        .replace(/<[^>]*>/g, ""),
+    ).replace(/^\n+|\n+$/g, "");
+    codeBlocks.push(code);
+    return `\n\u0000CODE${codeBlocks.length - 1}\u0000\n`;
+  });
+
+  // 表格：先行内处理，转成 markdown 表格
+  source = source.replace(/<table[\s\S]*?<\/table>/gi, (table) => {
+    const rows = [...table.matchAll(/<tr[^>]*>([\s\S]*?)<\/tr>/gi)].map((row) =>
+      [...row[1].matchAll(/<(t[hd])[^>]*>([\s\S]*?)<\/\1>/gi)].map((cell) =>
+        inlineText(cell[2]).replace(/\|/g, "\\|"),
+      ),
+    );
+    if (rows.length === 0) return "\n";
+    const header = rows[0];
+    const body = rows.slice(1);
+    const lines = [
+      `| ${header.join(" | ")} |`,
+      `| ${header.map(() => "---").join(" | ")} |`,
+      ...body.map((row) => `| ${row.join(" | ")} |`),
+    ];
+    return `\n${lines.join("\n")}\n`;
+  });
+
+  source = source
+    .replace(/<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi, (_m, level, text) => `\n${"#".repeat(Number(level))} ${inlineText(text)}\n`)
+    .replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, (_m, text) => `\n- ${inlineText(text)}`)
+    .replace(/<(p|div|section|tr|thead|tbody|ul|ol|blockquote)[^>]*>/gi, "\n")
+    .replace(/<\/(p|div|section|tr|thead|tbody|ul|ol|blockquote)>/gi, "\n")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, (_m, text) => `\`${inlineText(text)}\``)
+    .replace(/<a[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi, (_m, href, text) => {
+      const label = inlineText(text);
+      return label ? `[${label}](${href})` : href;
+    })
+    .replace(/<(strong|b)[^>]*>([\s\S]*?)<\/\1>/gi, (_m, _tag, text) => `**${inlineText(text)}**`)
+    .replace(/<[^>]*>/g, "");
+
+  source = decodeEntities(source);
+
+  // 还原代码块
+  source = source.replace(/\u0000CODE(\d+)\u0000/g, (_m, index) => {
+    const code = codeBlocks[Number(index)] ?? "";
+    return `\n\`\`\`\n${code}\n\`\`\`\n`;
+  });
+
+  return source
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+/** 带超时的文本抓取 */
+async function fetchText(url, timeout = DEFAULT_TIMEOUT) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: { "user-agent": "reui-mcp", accept: "text/html,*/*" },
+    });
+    if (!response.ok) return null;
+    const buffer = Buffer.from(await response.arrayBuffer());
+    return buffer.subarray(0, MAX_BYTES).toString("utf8");
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * 抓取某组件的官网文档并转 Markdown
+ *
+ * @param {string} name 组件名（如 `splitter`）
+ * @returns {Promise<{ markdown: string, url: string, source: "site" } | null>}
+ */
+export async function fetchSiteDocument(name) {
+  const url = docsUrlFor(name);
+  if (!url) return null;
+  const html = await fetchText(url);
+  if (!html) return null;
+  const markdown = htmlToMarkdown(html);
+  if (markdown.length < 40) return null;
+  return { markdown, url, source: "site" };
+}
+
+/** 抓取官网组件总览（分类 + 说明） */
+export async function fetchSiteOverview() {
+  const html = await fetchText(DOCS_BASE);
+  if (!html) return null;
+  const markdown = htmlToMarkdown(html);
+  if (!markdown) return null;
+  return { markdown, url: DOCS_BASE, source: "site" };
+}