mdk-skills 2.4.19 → 2.4.21

package/scripts/core.js

@@ -1,63 +1,80 @@
 const fs = require("fs");
 const path = require("path");
 
-// 时间戳格式：YYYY-MM-DD HH:mm:ss
+// ---------- 纯函数（无需 I/O，保持同步）----------
+
 function timestamp() {
   const d = new Date();
   const pad = (n) => String(n).padStart(2, "0");
   return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
 }
 
-// 紧凑时间戳用于备份目录名：YYYYMMDD.HHmmss
 function backupTimestamp() {
   const d = new Date();
   const pad = (n) => String(n).padStart(2, "0");
   return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}.${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
 }
 
-/**
- * 追加日志到 .claude/.install.log
- * 需要传入 logFile 路径
- */
-function appendLog(logFile, level, message) {
+function isPlainObject(val) {
+  return Object.prototype.toString.call(val) === "[object Object]";
+}
+
+function deepMerge(userObj, pkgObj) {
+  const result = { ...userObj };
+  for (const key of Object.keys(pkgObj)) {
+    if (!(key in result)) {
+      result[key] = pkgObj[key];
+    } else if (isPlainObject(pkgObj[key]) && isPlainObject(result[key])) {
+      result[key] = deepMerge(result[key], pkgObj[key]);
+    }
+  }
+  return result;
+}
+
+async function pathExists(p) {
+  try { await fs.promises.access(p); return true; } catch { return false; }
+}
+
+// ---------- 日志 ----------
+
+async function appendLog(logFile, level, message) {
   const dir = path.dirname(logFile);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+  if (!(await pathExists(dir))) {
+    await fs.promises.mkdir(dir, { recursive: true });
   }
   const line = `[${timestamp()}] [${level}] ${message}\n`;
-  fs.appendFileSync(logFile, line, "utf-8");
+  await fs.promises.appendFile(logFile, line, "utf-8");
 }
 
-/**
- * 备份已有目录到 dir/backups/<timestamp>/
- * 排除 backups/ 自身，清理超过 3 份的旧备份
- */
-function backupDir(dir) {
-  if (!fs.existsSync(dir)) return null;
+// ---------- 备份 ----------
+
+async function backupDir(dir) {
+  if (!(await pathExists(dir))) return null;
 
   const backupsDir = path.join(dir, "backups");
-  if (!fs.existsSync(backupsDir)) {
-    fs.mkdirSync(backupsDir, { recursive: true });
+  if (!(await pathExists(backupsDir))) {
+    await fs.promises.mkdir(backupsDir, { recursive: true });
   }
 
   const ts = backupTimestamp();
   const bakPath = path.join(backupsDir, ts);
-  fs.mkdirSync(bakPath, { recursive: true });
+  await fs.promises.mkdir(bakPath, { recursive: true });
 
-  for (const item of fs.readdirSync(dir)) {
+  const items = await fs.promises.readdir(dir);
+  for (const item of items) {
     if (item === "backups") continue;
     const srcPath = path.join(dir, item);
     const destPath = path.join(bakPath, item);
-    if (fs.statSync(srcPath).isDirectory()) {
-      copyDirSync(srcPath, destPath);
+    const stat = await fs.promises.stat(srcPath);
+    if (stat.isDirectory()) {
+      await copyDir(srcPath, destPath);
     } else {
-      fs.copyFileSync(srcPath, destPath);
+      await fs.promises.copyFile(srcPath, destPath);
     }
   }
 
   // 清理旧备份，只保留最近 3 份
-  const backups = fs
-    .readdirSync(backupsDir)
+  const backups = (await fs.promises.readdir(backupsDir))
     .filter((name) => /^\d{8}\.\d{6}$/.test(name))
     .sort()
     .reverse();
@@ -65,70 +82,52 @@ function backupDir(dir) {
   if (backups.length > 3) {
     for (const old of backups.slice(3)) {
       const oldPath = path.join(backupsDir, old);
-      fs.rmSync(oldPath, { recursive: true, force: true });
+      await fs.promises.rm(oldPath, { recursive: true, force: true });
     }
   }
 
   return bakPath;
 }
 
-function isPlainObject(val) {
-  return Object.prototype.toString.call(val) === "[object Object]";
-}
+// ---------- 递归拷贝目录（异步，绕开 Windows fs.cpSync 中文路径 bug）----------
 
-/**
- * 手动递归拷贝目录，绕开 Windows 中文路径下 fs.cpSync({ recursive: true }) 死锁的 bug
- */
-function copyDirSync(src, dest) {
-  fs.mkdirSync(dest, { recursive: true });
-  for (const item of fs.readdirSync(src)) {
+async function copyDir(src, dest) {
+  await fs.promises.mkdir(dest, { recursive: true });
+  const items = await fs.promises.readdir(src);
+  for (const item of items) {
     const srcPath = path.join(src, item);
     const destPath = path.join(dest, item);
-    if (fs.statSync(srcPath).isDirectory()) {
-      copyDirSync(srcPath, destPath);
+    const stat = await fs.promises.stat(srcPath);
+    if (stat.isDirectory()) {
+      await copyDir(srcPath, destPath);
     } else {
-      fs.copyFileSync(srcPath, destPath);
+      await fs.promises.copyFile(srcPath, destPath);
     }
   }
 }
 
-/**
- * 递归深合并，用户值优先，目标新增字段补充
- */
-function deepMerge(userObj, pkgObj) {
-  const result = { ...userObj };
+// ---------- 列出技能目录 ----------
 
-  for (const key of Object.keys(pkgObj)) {
-    if (!(key in result)) {
-      result[key] = pkgObj[key];
-    } else if (isPlainObject(pkgObj[key]) && isPlainObject(result[key])) {
-      result[key] = deepMerge(result[key], pkgObj[key]);
-    }
+async function listSkillDirs(skillsPath) {
+  if (!(await pathExists(skillsPath))) return [];
+  const names = await fs.promises.readdir(skillsPath);
+  const result = [];
+  for (const name of names) {
+    if (name.startsWith(".")) continue;
+    const fullPath = path.join(skillsPath, name);
+    const stat = await fs.promises.stat(fullPath);
+    if (stat.isDirectory()) result.push(name);
   }
-
   return result;
 }
 
-/**
- * 列出技能目录下的有效技能目录（排除非目录项和隐藏目录）
- */
-function listSkillDirs(skillsPath) {
-  if (!fs.existsSync(skillsPath)) return [];
-  return fs.readdirSync(skillsPath).filter((name) => {
-    const fullPath = path.join(skillsPath, name);
-    return fs.statSync(fullPath).isDirectory() && !name.startsWith(".");
-  });
-}
+// ---------- 解析 SKILL.md frontmatter ----------
 
-/**
- * 解析 SKILL.md 的 YAML frontmatter
- * 返回 { name?, description?, version?, tags? }，解析失败返回 null
- */
-function parseFrontmatter(skillDir) {
+async function parseFrontmatter(skillDir) {
   const mdPath = path.join(skillDir, "SKILL.md");
-  if (!fs.existsSync(mdPath)) return null;
+  if (!(await pathExists(mdPath))) return null;
   let content;
-  try { content = fs.readFileSync(mdPath, "utf-8"); } catch { return null; }
+  try { content = await fs.promises.readFile(mdPath, "utf-8"); } catch { return null; }
   content = content.replace(/\r\n/g, "\n");
   const match = content.match(/^---\n([\s\S]*?)\n---/);
   if (!match) return null;
@@ -157,18 +156,16 @@ function parseFrontmatter(skillDir) {
   return result;
 }
 
-/**
- * 读取技能元信息。
- * 优先从 .meta.json 读取；没有或解析失败时，从 SKILL.md frontmatter 兜底。
- */
-function readMeta(skillDir) {
+// ---------- 读取技能元信息 ----------
+
+async function readMeta(skillDir) {
   const metaPath = path.join(skillDir, ".meta.json");
-  if (fs.existsSync(metaPath)) {
+  if (await pathExists(metaPath)) {
     try {
-      return JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+      return JSON.parse(await fs.promises.readFile(metaPath, "utf-8"));
     } catch {}
   }
-  const fm = parseFrontmatter(skillDir);
+  const fm = await parseFrontmatter(skillDir);
   if (fm) {
     return {
       version: fm.version || "1.0.0",
@@ -179,43 +176,42 @@ function readMeta(skillDir) {
   return null;
 }
 
-/**
- * 安装技能：逐个复制，补缺不覆盖
- */
-function installSkills(skillsSource, skillsDest, logFile) {
-  if (!fs.existsSync(skillsSource)) return [];
+// ---------- 安装技能 ----------
+
+async function installSkills(skillsSource, skillsDest, logFile) {
+  if (!(await pathExists(skillsSource))) return [];
 
-  if (!fs.existsSync(skillsDest)) {
-    fs.mkdirSync(skillsDest, { recursive: true });
+  if (!(await pathExists(skillsDest))) {
+    await fs.promises.mkdir(skillsDest, { recursive: true });
   }
 
-  const skillDirs = listSkillDirs(skillsSource);
+  const skillDirs = await listSkillDirs(skillsSource);
   const results = [];
 
   for (const dir of skillDirs) {
     const srcSkill = path.join(skillsSource, dir);
     const destSkill = path.join(skillsDest, dir);
-    const meta = readMeta(srcSkill);
+    const meta = await readMeta(srcSkill);
     const version = meta ? meta.version : "?";
 
-    if (!fs.existsSync(destSkill)) {
-      copyDirSync(srcSkill, destSkill);
-      appendLog(logFile, "SKILL", `${dir} (${version}) → installed`);
+    if (!(await pathExists(destSkill))) {
+      await copyDir(srcSkill, destSkill);
+      await appendLog(logFile, "SKILL", `${dir} (${version}) → installed`);
       results.push({ name: dir, version, action: "installed" });
     } else {
-      const destMeta = readMeta(destSkill);
+      const destMeta = await readMeta(destSkill);
       const needUpdate = meta && destMeta && meta.version !== destMeta.version;
 
       if (needUpdate) {
         const bakName = `${dir}.bak.${backupTimestamp()}`;
         const bakPath = path.join(skillsDest, bakName);
-        copyDirSync(destSkill, bakPath);
-        fs.rmSync(destSkill, { recursive: true, force: true });
-        copyDirSync(srcSkill, destSkill);
-        appendLog(logFile, "SKILL", `${dir} (${destMeta.version} → ${meta.version}) → updated`);
+        await copyDir(destSkill, bakPath);
+        await fs.promises.rm(destSkill, { recursive: true, force: true });
+        await copyDir(srcSkill, destSkill);
+        await appendLog(logFile, "SKILL", `${dir} (${destMeta.version} → ${meta.version}) → updated`);
         results.push({ name: dir, version: meta.version, action: "updated" });
       } else {
-        appendLog(logFile, "SKILL", `${dir} (${version}) → skipped (exists)`);
+        await appendLog(logFile, "SKILL", `${dir} (${version}) → skipped (exists)`);
         results.push({ name: dir, version, action: "skipped" });
       }
     }
@@ -224,10 +220,9 @@ function installSkills(skillsSource, skillsDest, logFile) {
   return results;
 }
 
-/**
- * 安装 settings.json，深度合并
- */
-function installSettings(sourceDir, destDir, logFile) {
+// ---------- 安装 settings.json ----------
+
+async function installSettings(sourceDir, destDir, logFile) {
   const settingsSource = path.join(sourceDir, "settings.json");
   const settingsDest = path.join(destDir, "settings.json");
   const localSource = path.join(sourceDir, "settings.local.json");
@@ -237,84 +232,84 @@ function installSettings(sourceDir, destDir, logFile) {
     { src: settingsSource, dest: settingsDest, name: "settings.json" },
     { src: localSource, dest: localDest, name: "settings.local.json" },
   ]) {
-    if (!fs.existsSync(src)) continue;
+    if (!(await pathExists(src))) continue;
 
-    if (fs.existsSync(dest)) {
-      const userData = JSON.parse(fs.readFileSync(dest, "utf-8"));
-      const pkgData = JSON.parse(fs.readFileSync(src, "utf-8"));
+    if (await pathExists(dest)) {
+      const userData = JSON.parse(await fs.promises.readFile(dest, "utf-8"));
+      const pkgData = JSON.parse(await fs.promises.readFile(src, "utf-8"));
       const merged = deepMerge(userData, pkgData);
-      fs.writeFileSync(dest, JSON.stringify(merged, null, 2) + "\n", "utf-8");
-      appendLog(logFile, "SETTINGS", `${name} merged`);
+      await fs.promises.writeFile(dest, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+      await appendLog(logFile, "SETTINGS", `${name} merged`);
     } else {
-      fs.copyFileSync(src, dest);
-      appendLog(logFile, "SETTINGS", `${name} created`);
+      await fs.promises.copyFile(src, dest);
+      await appendLog(logFile, "SETTINGS", `${name} created`);
     }
   }
 }
 
-/**
- * 获取包内的技能列表（带元信息）
- */
-function getPackageSkills(packageDir) {
+// ---------- 获取包内技能列表 ----------
+
+async function getPackageSkills(packageDir) {
   const skillsSource = path.join(packageDir, ".claude", "skills");
-  return listSkillDirs(skillsSource).map((name) => {
-    const meta = readMeta(path.join(skillsSource, name));
-    return {
+  const names = await listSkillDirs(skillsSource);
+  const result = [];
+  for (const name of names) {
+    const meta = await readMeta(path.join(skillsSource, name));
+    result.push({
       name,
       version: meta ? meta.version : "?",
       description: meta ? meta.description : "",
       tags: meta ? meta.tags : [],
       _updateCount: meta ? (meta._updateCount || 0) : 0,
-    };
-  });
+    });
+  }
+  return result;
 }
 
-/**
- * 解析技能源路径：
- * 从 settings.json 的 _skill_source 字段读取用户指定的本地技能目录
- * 没有设置则返回 null
- */
-function getSkillsSource(projectRoot) {
+// ---------- 获取技能源路径 ----------
+
+async function getSkillsSource(projectRoot) {
   const settingsPath = path.join(projectRoot, ".claude", "settings.json");
-  if (fs.existsSync(settingsPath)) {
+  if (await pathExists(settingsPath)) {
     try {
-      const s = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+      const s = JSON.parse(await fs.promises.readFile(settingsPath, "utf-8"));
       if (s._skill_source) return s._skill_source;
     } catch {}
   }
   return null;
 }
 
-/**
- * 获取用户已安装的技能及其 settings 中的 enabled 状态
- */
-function getUserSkills(claudeDest) {
+// ---------- 获取用户已安装技能 ----------
+
+async function getUserSkills(claudeDest) {
   const skillsDest = path.join(claudeDest, "skills");
-  if (!fs.existsSync(skillsDest)) return [];
+  if (!(await pathExists(skillsDest))) return [];
 
   const settingsPath = path.join(claudeDest, "settings.json");
   let settings = {};
-  if (fs.existsSync(settingsPath)) {
+  if (await pathExists(settingsPath)) {
     try {
-      settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+      settings = JSON.parse(await fs.promises.readFile(settingsPath, "utf-8"));
     } catch {
       settings = {};
     }
   }
 
   const skillConfigs = settings.skills || {};
-
-  return listSkillDirs(skillsDest).map((name) => {
-    const meta = readMeta(path.join(skillsDest, name));
+  const names = await listSkillDirs(skillsDest);
+  const result = [];
+  for (const name of names) {
+    const meta = await readMeta(path.join(skillsDest, name));
     const config = skillConfigs[name] || {};
-    return {
+    result.push({
       name,
       version: meta ? meta.version : "?",
       description: meta ? meta.description : config.description || "",
       tags: meta ? meta.tags : [],
       enabled: config.enabled !== false,
-    };
-  });
+    });
+  }
+  return result;
 }
 
 module.exports = {
@@ -322,7 +317,7 @@ module.exports = {
   backupTimestamp,
   appendLog,
   backupDir,
-  copyDirSync,
+  copyDir,
   deepMerge,
   listSkillDirs,
   readMeta,