code-frontmatter 0.2.5 → 0.2.7

package/dist/tools/write.js

@@ -0,0 +1,130 @@
+/*---
+intent: "实现 cfm_write 工具：将标准 CFM 表头写入指定代码文件，确保字段名和注释格式严格合规"
+role: service
+exports:
+  - "writeFrontmatter: 将 CFM 表头写入指定文件"
+depends_on: ["../registry.ts", "../schema.ts"]
+when_to_load: "修改表头写入逻辑、格式生成或替换策略时加载"
+ai_notes: "此工具是 CFM 规范的唯一写入入口，从根源杜绝字段名不统一的问题"
+---*/
+import { readFile, writeFile } from "node:fs/promises";
+import { extname } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { getLanguageByExtension } from "../registry.js";
+/**
+ * 将 CFM 表头写入指定文件
+ *
+ * 流程：
+ * 1. 根据扩展名查找语言注释规则
+ * 2. 构建标准 YAML 内容
+ * 3. 用正确的注释语法包裹
+ * 4. 替换旧表头或插入到文件顶部
+ *
+ * @param filePath - 文件绝对路径
+ * @param data - CFM 表头数据
+ * @returns 操作结果
+ */
+export async function writeFrontmatter(filePath, data) {
+    const ext = extname(filePath);
+    const lang = getLanguageByExtension(ext);
+    if (!lang) {
+        return {
+            success: false,
+            message: `不支持的文件类型 "${ext}"，请先用 cfm_register_language 注册该语言。`,
+        };
+    }
+    const { comment_start, comment_end, line_prefix } = lang.rule;
+    // ── 构建 YAML 内容 ──
+    // 按照标准字段顺序构建对象，只包含有值的字段
+    const orderedData = {};
+    orderedData.intent = data.intent;
+    orderedData.role = data.role;
+    orderedData.exports = data.exports;
+    if (data.depends_on && data.depends_on.length > 0)
+        orderedData.depends_on = data.depends_on;
+    if (data.when_to_load)
+        orderedData.when_to_load = data.when_to_load;
+    if (data.mutates_state !== undefined)
+        orderedData.mutates_state = data.mutates_state;
+    if (data.side_effects && data.side_effects.length > 0)
+        orderedData.side_effects = data.side_effects;
+    if (data.domain)
+        orderedData.domain = data.domain;
+    if (data.ai_notes)
+        orderedData.ai_notes = data.ai_notes;
+    const yamlStr = stringifyYaml(orderedData, { lineWidth: 0 }).trim();
+    // ── 生成注释块 ──
+    let header;
+    if (line_prefix) {
+        // 脚本语言（Python, Ruby 等）：每行加前缀
+        const yamlLines = yamlStr.split("\n");
+        const prefixedLines = yamlLines.map((line) => line ? `${line_prefix}${line}` : line_prefix.trim());
+        header = `${comment_start}\n${prefixedLines.join("\n")}\n${comment_end}`;
+    }
+    else {
+        // C 家族语言（JS, TS, Java 等）：块注释
+        header = `${comment_start}\n${yamlStr}\n${comment_end}`;
+    }
+    // ── 读取原文件 ──
+    let content;
+    try {
+        content = await readFile(filePath, "utf-8");
+    }
+    catch {
+        return {
+            success: false,
+            message: `无法读取文件: ${filePath}`,
+        };
+    }
+    // 统一换行符
+    const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    // ── 检测是否已有表头，如果有则替换 ──
+    const newContent = replaceOrInsertHeader(normalized, comment_start, comment_end, header);
+    // ── 写入文件 ──
+    try {
+        await writeFile(filePath, newContent, "utf-8");
+    }
+    catch {
+        return {
+            success: false,
+            message: `无法写入文件: ${filePath}`,
+        };
+    }
+    return {
+        success: true,
+        message: `CFM 表头已写入 ${filePath}`,
+    };
+}
+/**
+ * 替换已有表头或在文件顶部插入新表头
+ */
+function replaceOrInsertHeader(content, commentStart, commentEnd, newHeader) {
+    const trimmed = content.trimStart();
+    const leadingWhitespace = content.slice(0, content.length - trimmed.length);
+    // 检查是否以 shebang (#!) 开头
+    let shebangLine = "";
+    let restContent = trimmed;
+    if (trimmed.startsWith("#!")) {
+        const newlineIdx = trimmed.indexOf("\n");
+        if (newlineIdx !== -1) {
+            shebangLine = trimmed.slice(0, newlineIdx + 1);
+            restContent = trimmed.slice(newlineIdx + 1);
+        }
+    }
+    const restTrimmed = restContent.trimStart();
+    // 检查是否已有 CFM 表头
+    if (restTrimmed.startsWith(commentStart)) {
+        const afterStart = restTrimmed.slice(commentStart.length);
+        const endIdx = afterStart.indexOf(commentEnd);
+        if (endIdx !== -1) {
+            // 找到旧表头，替换
+            const afterOldHeader = afterStart.slice(endIdx + commentEnd.length);
+            // 保留旧表头后的空行
+            const cleaned = afterOldHeader.replace(/^\n{0,2}/, "\n");
+            return shebangLine + newHeader + cleaned;
+        }
+    }
+    // 没有旧表头，插入到文件顶部
+    return shebangLine + newHeader + "\n\n" + restContent;
+}
+//# sourceMappingURL=write.js.map

package/dist/tools/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/tools/write.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-frontmatter",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "让每一个代码文件拥有自己的身份证，让 AI 不读全文就能理解你的整个项目。An MCP Server that gives every code file a self-describing frontmatter header for AI assistants.",
   "type": "module",
   "main": "dist/index.js",
@@ -8,8 +8,8 @@
     "code-frontmatter": "dist/index.js"
   },
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "tsc",
+    "dev": "tsc --watch",
     "start": "node dist/index.js",
     "prepublishOnly": "npm run build"
   },
@@ -37,6 +37,10 @@
     "type": "git",
     "url": "https://github.com/coobi7/code-frontmatter.git"
   },
+  "bugs": {
+    "url": "https://github.com/coobi7/code-frontmatter/issues"
+  },
+  "homepage": "https://github.com/coobi7/code-frontmatter#readme",
   "engines": {
     "node": ">=18.0.0"
   },
@@ -47,7 +51,6 @@
   },
   "devDependencies": {
     "@types/node": "^22.15.3",
-    "tsup": "^8.5.1",
     "typescript": "^5.8.3"
   }
 }