code-frontmatter 0.2.5 → 0.2.7

package/README.md

@@ -1,40 +1,49 @@
 ---
-intent: "README for Code Frontmatter project"
+intent: "Project documentation and usage guide"
 role: documentation
-when_to_load: "Initial project setup or understanding CFM usage"
+when_to_load: "Initial setup or reference"
 ---
 
 # Code Frontmatter (CFM)
 
-> **"Identity Cards" for your code files.**  
-> **Let AI understand your entire project without reading every single line.**
+[![npm version](https://img.shields.io/npm/v/code-frontmatter.svg?style=flat-square)](https://www.npmjs.com/package/code-frontmatter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)
+
+[中文文档](./README.zh-CN.md) | [English](./README.md)
+
+> **The "Passport" for your code files.**  
+> **Empower AI to understand your entire repository with < 5% of the token cost.**
 
 ---
 
-Code Frontmatter (CFM) is an open standard and MCP (Model Context Protocol) Server that allows you to embed structured metadata (YAML) at the top of every source code file.
+**Code Frontmatter (CFM)** is an open standard and [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) Server that manages structured metadata within your source code. 
 
-By scanning these lightweight headers, AI coding assistants (like Cursor, Windsurf, Claude Code) can build a cognitive map of your entire project with **minimal token cost**, eliminating hallucinations caused by context overload.
+By adding a lightweight YAML header to your files, you promote your codebase from "text files" to a "semantic graph" that AI agents (like Cursor, Windsurf, Claude) can navigate instantly and accurately.
 
 ## 🚀 Why CFM?
 
-| Feature | Without CFM | With CFM |
-|---|---|---|
-| **Context Load** | Full project files (huge tokens) | Just headers (~5% tokens) |
-| **Accuracy** | High hallucination risk | Deterministic file intent |
-| **Cost** | $$$ Expensive API calls | $ Cheap & Efficient |
-| **Scale** | Fails on large repos | Works on 10k+ file repos |
+AI coding assistants often struggle with large codebases:
+1.  **Context Overflow**: Reading every file to understand the architecture consumes massive context windows ($$$).
+2.  **Hallucination**: Guessing file purposes leads to bugs.
+3.  **blindness**: Agents don't know *where* to look for specific logic.
+
+**CFM solves this by exposing high-level intent, architectural roles, and dependency graphs without requiring the AI to read the code body.**
+
+| Metric | Without CFM | With CFM |
+| :--- | :--- | :--- |
+| **Context Cost** | 100% (Full Source) | **~3-5% (Headers Only)** |
+| **Search Speed** | Slow (Grep/Read) | **Instant (Semantic Index)** |
+| **Accuracy** | Probabilistic | **Deterministic** |
 
 ## 📦 Installation
 
-To use CFM with your AI IDE (Cursor, Claude Desktop, etc.), install it as an MCP Server:
+This project is designed as a **Model Context Protocol (MCP)** server.
 
-```bash
-npx -y code-frontmatter
-```
+### 1. For [Cursor](https://cursor.sh)
 
-### Configuration
+Add the following to your `~/.cursor/mcp.json` (or strictly via the Cursor Settings UI):
 
-#### For Cursor (`~/.cursor/mcp.json`)
 ```json
 {
   "mcpServers": {
@@ -46,7 +55,10 @@ npx -y code-frontmatter
 }
 ```
 
-#### For Claude Desktop
+### 2. For [Claude Desktop](https://claude.ai/download)
+
+Add the following to your `claude_desktop_config.json`:
+
 ```json
 {
   "mcpServers": {
@@ -58,61 +70,89 @@ npx -y code-frontmatter
 }
 ```
 
-## 🛠 Usage
+## 🤖 Instructions for AI Agents (Critical)
+
+**To get the most out of CFM, you must instruct your AI assistant to use it.** 
+AI models are lazy; they will try to guess instead of calling tools unless explicitly told otherwise.
+
+**Copy and paste the following into your Project Rules (`.cursorrules` / `.windsurfrules`) or Custom Instructions:**
+
+```markdown
+# Code Frontmatter Protocol (CFM)
+
+This project uses Code Frontmatter (CFM) to manage file metadata. 
+You MUST follow these rules strictly:
+
+1.  **Initialize Context**: At the start of a session, ALWAYS call `cfm_read` (or `cfm_scan`) on the project root to build your mental map. 
+    - DO NOT list all files with `ls -R`. Use `cfm_read` instead.
+2.  **Search First**: When looking for specific functionality (e.g., "auth logic"), use `cfm_search` before reading file contents.
+3.  **Maintain Headers**: 
+    - When creating a new file, you MUST generate a valid CFM header (intent, role, exports).
+    - When significantly modifying code, you MUST update the `exports` and `ai_notes` in the header using `cfm_write`.
+    - KEEP `ai_notes` BRIEF. Only store permanent architectural constraints, not change logs.
+```
+
+## 🛠 Usage & Syntax
 
-### 1. Add Frontmatter to Your Code
+### The Header Format
 
-Add a CFM header to the top of your files using your language's comment syntax.
+CFM uses a YAML block inside your language's standard comment syntax.
 
-**JavaScript / TypeScript:**
-```javascript
+**TypeScript / JavaScript / Java / C#:**
+```typescript
 /*---
-intent: "Manages user authentication state and login logic"
+intent: "Handles JWT token validation and rotation"
 role: service
 exports:
-  - "login: Authenticate user with email/pass"
-  - "logout: Clear session"
-depends_on: ["api-client.ts", "store.ts"]
-when_to_load: "Modifying auth flow or session handling"
+  - "verifyToken: Checks signature"
+  - "refreshToken: Issues new access token"
+depends_on: ["config.ts", "db-client.ts"]
+ai_notes: "Do not modify the secret key derivation logic."
 ---*/
 
-export function login(email, password) { ... }
+export function verifyToken(token) { ... }
 ```
 
-**Python:**
+**Python / Ruby / Shell / YAML:**
 ```python
 #---
-# intent: "Data model for User entity"
+# intent: "User data model definition"
 # role: model
-# exports:
-#   - "User: Standard user class"
+# domain: "identity"
 # mutates_state: false
 #---
 
-class User: ...
+class User(BaseModel): ...
 ```
 
-### 2. Available Tools
+### Available Tools
 
-The MCP Server exposes the following tools to your AI assistant:
+When installed as an MCP server, your AI gains these super-powers:
 
-- **`cfm_read(directory)`**: Scans your project and returns a structured index of all CFM headers.
-- **`cfm_search(query)`**: Search for files by keyword, role, or domain without reading full contents.
-- **`cfm_register_language(name, config)`**: Teach CFM how to parse headers for a new language on the fly.
-
-## 📋 Schema
-
-A valid CFM header requires at least:
-- **`intent`**: What is this file for? (String)
-- **`role`**: What is its architectural role? (String, e.g., `component`, `service`, `util`)
-- **`exports`**: What key things does it export? (Array of Strings)
-
-Optional fields: `depends_on`, `when_to_load`, `side_effects`, `mutates_state`, `domain`, `ai_notes`.
+*   **`cfm_read({ directory })`**: 
+    *   Returns a high-level summary of all files (paths, intents, roles, exports) in one JSON object. 
+    *   *Best for: Initializing session context.*
+*   **`cfm_search({ query, role, domain })`**: 
+    *   Semantic search over the headers. 
+    *   *Best for: "Find where user billing is handled".*
+*   **`cfm_write({ file, intent, ... })`**: 
+    *   Writes or updates the header.
+    *   *Best for: Creating new files or updating documentation.*
+*   **`cfm_register_language({ name, extensions, ... })`**: 
+    *   Teaches the server how to parse headers for custom file types.
 
 ## 🤝 Contributing
 
-We welcome contributions! Please follow the standard GitHub workflow.
+We want to make this the industry standard for AI-Code interaction.
+1.  Fork the repo.
+2.  Create a feature branch.
+3.  Submit a PR.
+
+**Focus areas:**
+- Parsers for more languages (Rust, Go, Swift).
+- IDE Extensions (VS Code, JetBrains).
+- Analysis tools.
 
 ## 📄 License
 
-MIT © 2026 coobi7
+MIT © 2026 [coobi7](https://github.com/coobi7)

package/README.zh-CN.md

@@ -0,0 +1,156 @@
+---
+intent: "项目文档和使用指南（中文版）"
+role: documentation
+when_to_load: "初次安装或查阅使用说明"
+---
+
+# Code Frontmatter (CFM)
+
+[![npm version](https://img.shields.io/npm/v/code-frontmatter.svg?style=flat-square)](https://www.npmjs.com/package/code-frontmatter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)
+
+> **代码文件的“身份证”。**
+> **让 AI 仅用 < 5% 的 Token 成本就能理解你的整个代码库。**
+
+---
+
+**Code Frontmatter (CFM)** 是一个开放标准和 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器，用于管理源代码文件中的结构化元数据。
+
+通过在文件顶部添加轻量级的 YAML 头部，你可以将代码库从普通的“文本文件集合”升级为一张“语义图谱”，让 AI 助手（如 Cursor、Windsurf、Claude）能够即时、准确地导航。
+
+## 🚀 为什么要用 CFM?
+
+AI 编程助手在处理大型代码库时常面临以下问题：
+1.  **上下文溢出**：读取所有文件以理解架构会消耗巨大的上下文窗口（且昂贵）。
+2.  **幻觉**：AI 需猜测文件用途，容易导致 Bug。
+3.  **盲区**：Agent 不知道去哪里寻找特定的逻辑。
+
+**CFM 通过暴露高层意图、架构角色和依赖关系图，解决了这些问题，且无需 AI 读取代码正文。**
+
+| 指标 | 不使用 CFM | 使用 CFM |
+| :--- | :--- | :--- |
+| **上下文成本** | 100% (全源码) | **~3-5% (仅头部)** |
+| **检索速度** | 慢 (Grep/Read) | **即时 (语义索引)** |
+| **准确性** | 概率性猜测 | **确定性** |
+
+## 📦 安装
+
+本项目设计为 **Model Context Protocol (MCP)** 服务器。
+
+### 1. 适用于 [Cursor](https://cursor.sh)
+
+将以下内容添加到你的 `~/.cursor/mcp.json`（或者通过 Cursor 设置界面添加）：
+
+```json
+{
+  "mcpServers": {
+    "code-frontmatter": {
+      "command": "npx",
+      "args": ["-y", "code-frontmatter"]
+    }
+  }
+}
+```
+
+### 2. 适用于 [Claude Desktop](https://claude.ai/download)
+
+将以下内容添加到你的 `claude_desktop_config.json`：
+
+```json
+{
+  "mcpServers": {
+    "code-frontmatter": {
+      "command": "npx",
+      "args": ["-y", "code-frontmatter"]
+    }
+  }
+}
+```
+
+## 🤖 AI Agent 指引 (关键步骤)
+
+**为了充分利用 CFM，你必须明确指示你的 AI 助手使用它。**
+AI 模型通常比较“懒”，除非明确告知，否则它们倾向于猜测而不是调用工具。
+
+**请将以下内容复制并粘贴到你的项目规则 (`.cursorrules` / `.windsurfrules`) 或自定义指令中：**
+
+```markdown
+# Code Frontmatter Protocol (CFM)
+
+本项目使用 Code Frontmatter (CFM) 管理文件元数据。
+你必须严格遵守以下规则：
+
+1.  **初始化上下文**：在会话开始时，务必在项目根目录调用 `cfm_read` (或 `cfm_scan`) 以构建你的心理地图。
+    - 不要使用 `ls -R` 列出所有文件。请使用 `cfm_read`。
+2.  **搜索优先**：当查找特定功能（例如“认证逻辑”）时，在读取文件内容之前，先使用 `cfm_search`。
+3.  **维护头部**：
+    - 创建新文件时，必须生成有效的 CFM 头部（intent, role, exports）。
+    - 修改代码时，必须使用 `cfm_write` 更新头部中的 `exports` 和 `ai_notes`。
+    - 保持 `ai_notes` 简练。只存储永久性的架构约束，不要记录变更日志。
+```
+
+## 🛠 使用方法 & 语法
+
+### 头部格式
+
+CFM 在你所用语言的标准注释语法中使用 YAML 块。
+
+**TypeScript / JavaScript / Java / C#:**
+```typescript
+/*---
+intent: "处理 JWT 令牌验证和轮换"
+role: service
+exports:
+  - "verifyToken: 检查签名"
+  - "refreshToken: 发发新访问令牌"
+depends_on: ["config.ts", "db-client.ts"]
+ai_notes: "不要修改密钥派生逻辑。"
+---*/
+
+export function verifyToken(token) { ... }
+```
+
+**Python / Ruby / Shell / YAML:**
+```python
+#---
+# intent: "用户数据模型定义"
+# role: model
+# domain: "identity"
+# mutates_state: false
+#---
+
+class User(BaseModel): ...
+```
+
+### 可用工具
+
+作为 MCP 服务器安装后，你的 AI 将获得以下超能力：
+
+*   **`cfm_read({ directory })`**:
+    *   返回一个JSON对象，包含所有文件的概要（路径、意图、角色、导出）。
+    *   *适用场景：初始化会话上下文。*
+*   **`cfm_search({ query, role, domain })`**:
+    *   对头部进行语义搜索。
+    *   *适用场景：“查找哪处理用户计费”。*
+*   **`cfm_write({ file, intent, ... })`**:
+    *   写入或更新头部。
+    *   *适用场景：创建新文件或更新文档。*
+*   **`cfm_register_language({ name, extensions, ... })`**:
+    *   教服务器如何解析自定义文件类型的头部。
+
+## 🤝 贡献代码
+
+我们希望将其打造为 AI-Code 交互的行业标准。
+1.  Fork 本仓库。
+2.  创建一个特性分支。
+3.  提交 PR。
+
+**关注领域：**
+- 更多语言的解析器 (Rust, Go, Swift)。
+- IDE 扩展 (VS Code, JetBrains)。
+- 分析工具。
+
+## 📄 许可证
+
+MIT © 2026 [coobi7](https://github.com/coobi7)

package/dist/index.d.ts

@@ -1 +1,3 @@
 #!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}