czon 0.1.0 → 0.1.1

package/docs/test-katex.md

@@ -0,0 +1,66 @@
+# KaTeX 公式显示效果测试
+
+这是一个行内公式测试： $ E = mc^2 $ 。
+
+这是一个块级公式测试：
+
+$$
+\int_a^b f(x) \, dx = F(b) - F(a)
+$$
+
+这是另一个块级公式测试：
+
+$$
+\frac{d}{dx}e^x = e^x
+$$
+
+这是一个复杂的公式测试：
+
+$$
+\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
+$$
+
+带有 cases 的公式测试：
+
+$$
+f(x) =
+\begin{cases}
+x^2 & \text{if } x \geq 0 \\
+-x & \text{if } x < 0
+\end{cases}
+$$
+
+表格公式:
+
+$$
+\begin{array}{c|c|c}
+a & b & c \\
+\hline
+1 & 2 & 3 \\
+4 & 5 & 6 \\
+\end{array}
+$$
+
+矩阵公式:
+
+$$
+\begin{pmatrix}
+1 & 2 \\
+3 & 4
+\end{pmatrix}
+$$
+
+含有 text 的公式测试：
+
+$$
+E = mc^2 \quad \text{where } m \text{ is mass and
+    } c \text{ is the speed of light}
+$$
+
+广义凯利公式：
+
+$$
+f^* = \argmax_f \sum_{i \in X} P_i \ln (1 + f \cdot R_i)
+$$
+
+请确保以上公式均能正确显示。

package/docs/test-mermaid.md

@@ -0,0 +1,105 @@
+# Mermaid 图表测试
+
+这是一个测试文件，用于验证 ZEN 中的 Mermaid 图表渲染功能。
+
+## 流程图示例
+
+```mermaid
+graph TD
+    A[开始] --> B{是否继续?}
+    B -->|是| C[执行操作]
+    B -->|否| D[结束]
+    C --> E[检查结果]
+    E --> F{是否成功?}
+    F -->|是| G[完成]
+    F -->|否| H[重试]
+    H --> C
+    G --> D
+```
+
+## 序列图示例
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant System
+    participant Database
+
+    User->>System: 提交请求
+    System->>Database: 查询数据
+    Database-->>System: 返回结果
+    System-->>User: 显示结果
+```
+
+## 甘特图示例
+
+```mermaid
+gantt
+    title 项目时间表
+    dateFormat  YYYY-MM-DD
+    section 设计
+    需求分析     :done,    des1, 2024-01-01, 7d
+    原型设计     :active,  des2, 2024-01-08, 5d
+    详细设计     :         des3, after des2, 5d
+    section 开发
+    前端开发     :         dev1, after des3, 10d
+    后端开发     :         dev2, after des3, 15d
+    section 测试
+    单元测试     :         test1, after dev1, 5d
+    集成测试     :         test2, after dev2, 5d
+```
+
+## 类图示例
+
+```mermaid
+classDiagram
+    class Animal {
+        +String name
+        +int age
+        +void eat()
+        +void sleep()
+    }
+    class Dog {
+        +void bark()
+    }
+    class Cat {
+        +void meow()
+    }
+
+    Animal <|-- Dog
+    Animal <|-- Cat
+```
+
+## 状态图示例
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Processing : 开始处理
+    Processing --> Success : 处理成功
+    Processing --> Error : 处理失败
+    Success --> [*]
+    Error --> [*]
+```
+
+## 饼图示例
+
+```mermaid
+pie title 浏览器使用率
+    "Chrome" : 65.2
+    "Firefox" : 15.3
+    "Safari" : 12.5
+    "Edge" : 5.2
+    "其他" : 1.8
+```
+
+## 错误语法测试（应该显示错误信息）
+
+```mermaid
+graph TD
+    A --> B
+    // 这里缺少箭头定义
+    C --> D
+```
+
+这个测试文件包含了多种 Mermaid 图表类型，用于验证 ZEN 的 Mermaid 集成是否正常工作。

package/docs/tricks.md

@@ -0,0 +1,15 @@
+# 使用技巧
+
+## 在正文中声明日期
+
+正文中可以使用 "今天是 2026 年 1 月 8 日" 这样的日期声明（格式风格自由），ZEN 会自动识别并处理。
+
+传统 Markdown 文档是通过 YAML Frontmatter 声明日期，需要记住对应的字段，否则会导致日期无法正确识别。
+
+ZEN 支持在正文中直接声明日期，避免了忘记填写 Frontmatter 字段的问题。
+
+AI 会自动提取并推断正文中的日期信息，并将其作为文档的创建日期进行处理。
+
+这种方式更加灵活和智能，提升了用户体验。
+
+顺带一提，具有日期的文档，可以生成时间线视图，方便浏览和管理。特别适合日记、博客等需要时间线的内容类型。

package/package.json

@@ -1,12 +1,64 @@
 {
   "name": "czon",
-  "version": "0.1.0",
-  "description": "",
-  "license": "MIT",
-  "author": "zccz14",
-  "type": "commonjs",
+  "version": "0.1.1",
+  "description": "CZone - A minimalist Markdown documentation site builder",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": "dist/cli.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "npx rimraf dist && tsc",
+    "dev": "ts-node src/cli.ts",
+    "build:doc": "npm run build && node dist/cli.js build --lang zh-Hans --lang en-US --lang ja-JP --lang ko-KR --lang es-ES --lang fr-FR --lang de-DE --lang ru-RU --lang pt-PT --lang it-IT --lang nl-NL --lang pl-PL --lang sv-SE --lang fi-FI --lang da-DK --lang no-NO --lang zh-Hant --lang hi-IN --lang ar-SA --lang th-TH --lang vi-VN --lang id-ID --lang pt-BR --lang es-MX --lang tr-TR --lang uk-UA --verbose",
+    "test": "npm run build && node --test dist/**/*.test.js",
+    "test:types": "tsc --noEmit",
+    "test:build": "npm run build && test -f dist/index.js && test -f dist/cli.js",
+    "test:cli": "node -e \"const pkg = require('./package.json'); console.log('Package:', pkg.name, 'v' + pkg.version)\"",
+    "format": "prettier --write \"**/*.{ts,js,json,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,js,json,md}\"",
+    "prepublishOnly": "npm run build",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "markdown",
+    "static-site",
+    "documentation",
+    "cli"
+  ],
+  "author": "zccz14",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zccz14/CZON.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zccz14/CZON/issues"
+  },
+  "homepage": "https://github.com/zccz14/CZON#readme",
+  "lint-staged": {
+    "*.{ts,js,json,md}": [
+      "prettier --write"
+    ]
+  },
+  "devDependencies": {
+    "@types/chokidar": "^1.7.5",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.3",
+    "@types/yaml": "^1.9.6",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "clipanion": "^4.0.0-rc.4",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "highlight.js": "^11.11.1",
+    "marked": "^17.0.1",
+    "marked-katex-extension": "^5.1.6",
+    "minimatch": "^10.1.1",
+    "yaml": "^2.8.2"
   }
 }

package/src/ai/extractMetadataFromMarkdown.ts

@@ -0,0 +1,95 @@
+import { completeMessages, OpenAIMessage } from '../services/openai';
+import { AIMetadata } from '../types';
+
+/**
+ * 从 markdown 内容中提取 metadata
+ * @param content Markdown 内容
+ * @returns Promise<AIMetadata> 提取的元数据，失败时抛出错误
+ */
+export async function extractMetadataFromMarkdown(content: string): Promise<AIMetadata> {
+  const prompt = buildMetadataPrompt(content);
+  const messages: OpenAIMessage[] = [
+    {
+      role: 'system',
+      content:
+        '你是一个专业的文档分析助手，擅长从文档中提取结构化信息。请严格按照要求的 JSON 格式返回结果。',
+    },
+    {
+      role: 'user',
+      content: prompt,
+    },
+  ];
+
+  const response = await completeMessages(messages, {
+    response_format: { type: 'json_object' },
+  });
+
+  const metadata = parseMetadataResponse(response.choices[0].message.content);
+
+  // 添加 tokens 使用情况
+  metadata.tokens_used = {
+    prompt: response.usage.prompt_tokens,
+    completion: response.usage.completion_tokens,
+    total: response.usage.total_tokens,
+  };
+
+  return metadata;
+}
+
+/**
+ * 构建提取 metadata 的 prompt
+ */
+function buildMetadataPrompt(content: string): string {
+  // 限制内容长度以避免 token 超限
+  const maxContentLength = Infinity; // 可根据需要调整长度限制
+  const truncatedContent =
+    content.length > maxContentLength
+      ? content.substring(0, maxContentLength) + '... [内容已截断]'
+      : content;
+
+  return `请分析以下文档内容，提取以下信息并返回 JSON 格式：
+
+文档内容：
+"""
+${truncatedContent}
+"""
+
+请提取：
+1. title: 文档的标题（简洁明了，不超过 30 个字）
+2. summary: 文档摘要（控制在 300 字以内，概括主要内容）
+3. tags: 关键词列表（3-8 个关键词，使用中文或英文）
+4. inferred_date: 文档中隐含的创建日期（如果有的话，格式：YYYY-MM-DD，没有就留空字符串）
+5. inferred_lang: 文档使用的语言代码（例如：zh-Hans 表示简体中文，en-US 表示美式英语）
+
+请严格按照以下 JSON 格式返回，不要包含任何其他文本：
+{
+  "title": "文档标题",
+  "summary": "文档摘要...",
+  "tags": ["关键词1", "关键词2", "关键词3"],
+  "inferred_date": "2023-01-01",
+  "inferred_lang": "zh-Hans"
+}`;
+}
+
+/**
+ * 解析 AI 返回的 metadata
+ */
+function parseMetadataResponse(responseContent: string): AIMetadata {
+  try {
+    const metadata = JSON.parse(responseContent);
+
+    // 验证和清理数据
+    return {
+      title: metadata.title?.trim() || '未命名文档',
+      summary: metadata.summary?.trim() || '',
+      tags: Array.isArray(metadata.tags)
+        ? metadata.tags.map((tag: string) => tag.trim()).filter(Boolean)
+        : [],
+      inferred_date: metadata.inferred_date?.trim() || undefined,
+      inferred_lang: metadata.inferred_lang?.trim() || 'zh-Hans',
+    };
+  } catch (error) {
+    console.error('❌ Failed to parse AI response:', error, 'Response:', responseContent);
+    throw error;
+  }
+}

package/src/ai/translateMarkdown.ts

@@ -0,0 +1,60 @@
+import { LANGUAGE_NAMES } from '../languages';
+import { completeMessages, OpenAIMessage } from '../services/openai';
+
+/**
+
+ * @param content Markdown 内容
+ * @param targetLang 目标语言代码（例如：zh-Hans, en-US）
+ * @returns Promise<string> 翻译后的 Markdown 内容
+ */
+export async function translateMarkdown(content: string, targetLang: string): Promise<string> {
+  const langName = LANGUAGE_NAMES[targetLang];
+  const lang = `${langName} (${targetLang})`;
+  const messages: OpenAIMessage[] = [
+    {
+      role: 'system',
+      content: [
+        `You are a professional document translator.`,
+        `Translate the following markdown content into ${lang}`,
+        targetLang === 'ja-JP'
+          ? [
+              //
+              '使用日语母语者自然的表达方式。',
+              '采用适合技术/专业文档的礼貌、正式语体（丁寧体/です・ます体）',
+              '确保语法和字符集完全符合日语规范。',
+              '绝对禁止使用繁体中文汉字。',
+              '所有日语汉字必须使用标准的 **日本常用汉字（Jōyō kanji）** 字形。',
+              '特别检查以下字形示例，确保使用日文标准字形：',
+              '1. “国” - 使用“国”而非“國”',
+              '2. “学” - 使用“学”而非“學”',
+              '3. “広” - 使用“広”而非“廣”',
+              '4. “円” - 使用“円”而非“圓”',
+              '5. “医” - 使用“医”而非“醫”',
+              '6. “図” - 使用“図”而非“圖”',
+              '7. “対” - 使用“対”而非“對”',
+              '8. “声” - 使用“声”而非“聲”',
+              '9. “芸” - 使用“芸”而非“藝”',
+              '10. “験” - 使用“験”而非“驗”',
+            ].join('\n')
+          : ``,
+        `Preserve the original markdown formatting, including headings, lists, code blocks, links, and images.`,
+        `Do not change any non-text elements or their formatting.`,
+        `Ensure that technical terms and code snippets remain unchanged.`,
+        `Provide a natural and fluent translation suitable for readers familiar with the subject matter.`,
+      ].join('\n'),
+    },
+    {
+      role: 'user',
+      content: content,
+    },
+  ];
+
+  const response = await completeMessages(messages);
+  const translatedContent = response.choices[0]?.message?.content?.trim() || '';
+
+  if (!translatedContent) {
+    throw new Error('Empty translation response');
+  }
+
+  return translatedContent;
+}

package/src/build/pipeline.ts

@@ -0,0 +1,172 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { translateMarkdown } from '../ai/translateMarkdown';
+import { loadMetaData, MetaData, saveMetaData } from '../metadata';
+import { INPUT_DIR, ZEN_DIR, ZEN_DIST_DIR, ZEN_SRC_DIR } from '../paths';
+import { extractMetadataByAI } from '../process/extractMetadataByAI';
+import { scanSourceFiles } from '../process/scanSourceFiles';
+import { renderTemplates } from '../process/template';
+import { BuildOptions } from '../types';
+import { updateFrontmatter } from '../utils/frontmatter';
+
+/**
+ * 验证构建配置
+ */
+async function validateConfig(options: BuildOptions): Promise<void> {
+  const { verbose = false } = options;
+
+  if (verbose) {
+    console.log(`🚀 Starting ZEN build...`);
+    if (options.langs && options.langs.length > 0) {
+      console.log(`🌐 Target languages: ${options.langs.join(', ')}`);
+    }
+    console.log(`🔍 Verbose mode enabled`);
+  }
+
+  MetaData.options = options;
+}
+
+/**
+ * 存储母语文件到 .zen/src
+ */
+async function storeNativeFiles(): Promise<void> {
+  const {
+    options: { verbose },
+    files,
+  } = MetaData;
+  for (const file of MetaData.files) {
+    try {
+      if (!file.hash) throw new Error(`Missing hash`);
+      if (!file.metadata?.inferred_lang) throw new Error(`Missing inferred language`);
+      const filePath = path.join(ZEN_SRC_DIR, file.metadata.inferred_lang, file.hash + '.md');
+      const originalContent = await fs.readFile(path.join(INPUT_DIR, file.path), 'utf-8');
+
+      const enhancedContent = updateFrontmatter(originalContent, {
+        title: file.metadata.title,
+        summary: file.metadata.summary,
+        tags: file.metadata.tags,
+        inferred_date: file.metadata.inferred_date,
+        inferred_lang: file.metadata.inferred_lang,
+      });
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+
+      await fs.writeFile(filePath, enhancedContent, 'utf-8');
+    } catch (error) {
+      console.warn(`⚠️ Failed to store native file ${file.path}:`, error);
+    }
+  }
+
+  if (verbose && files.length > 0) {
+    console.log(`💾 Stored ${files.length} native language files to .zen/src`);
+  }
+}
+
+/**
+ * 处理翻译
+ */
+async function processTranslations(): Promise<void> {
+  const {
+    files,
+    options: { langs = [], verbose },
+  } = MetaData;
+
+  await Promise.all(
+    files.flatMap(async file => {
+      return Promise.all(
+        langs.map(async lang => {
+          if (verbose) console.info(`📄 Processing file for translation: ${file.path}`);
+          if (!file.metadata) {
+            console.warn(`⚠️ Missing metadata for file: ${file.path}, skipping translation.`);
+            return;
+          }
+          if (verbose) console.log(`🌐 Translating to ${lang}...`);
+          // 存储翻译文件到 .zen/src/{lang}
+          const sourcePath = path.join(ZEN_SRC_DIR, file.metadata.inferred_lang, file.hash + '.md'); // 使用已经加强的母语文件路径
+          const targetPath = path.join(ZEN_SRC_DIR, lang, file.hash + '.md');
+
+          try {
+            const content = await fs.readFile(sourcePath, 'utf-8');
+            if (file.metadata.inferred_lang === lang) {
+              if (verbose)
+                console.log(`ℹ️ Skipping translation for ${file.path}, already in target language`);
+              return;
+            } else {
+              // 翻译
+              // 先检查是否已经有翻译文件存在
+
+              const exists = await fs.access(targetPath).then(
+                () => true,
+                () => false
+              );
+              if (exists) {
+                if (verbose)
+                  console.log(`ℹ️ Translation already exists for ${file.path} in ${lang}`);
+                return;
+              }
+            }
+
+            const translatedContent = await translateMarkdown(content, lang);
+
+            await fs.mkdir(path.dirname(targetPath), { recursive: true });
+            await fs.writeFile(targetPath, translatedContent, 'utf-8');
+
+            if (verbose) console.log(`✅ Translated file saved: ${targetPath}`);
+          } catch (error) {
+            console.error(`❌ Failed to translate to ${lang}:`, error);
+          }
+        })
+      );
+    })
+  );
+}
+
+/**
+ * 构建管道（函数组合）
+ */
+async function buildPipeline(options: BuildOptions): Promise<void> {
+  // 验证配置
+  await validateConfig(options);
+
+  // 清理输出目录
+  await fs.rm(ZEN_DIST_DIR, { recursive: true, force: true });
+
+  // 确保 .zen/.gitignore 文件
+  await fs.mkdir(ZEN_DIR, { recursive: true });
+  await fs.writeFile(path.join(ZEN_DIR, '.gitignore'), 'dist\n', 'utf-8');
+
+  // 扫描源文件
+  await scanSourceFiles();
+
+  // 运行 AI 元数据提取
+  await extractMetadataByAI();
+
+  // 存储母语文件
+  await storeNativeFiles();
+
+  // 处理翻译
+  await processTranslations();
+
+  // 渲染模板
+  await renderTemplates();
+}
+
+/**
+ * 主构建函数
+ */
+export async function buildSite(options: BuildOptions): Promise<void> {
+  const startTime = Date.now();
+
+  try {
+    await loadMetaData();
+    await buildPipeline(options);
+
+    const endTime = Date.now();
+    const duration = ((endTime - startTime) / 1000).toFixed(2);
+    console.log(`🎉 Build completed in ${duration}s`);
+  } catch (error) {
+    console.error(`❌ Build failed:`, error);
+    throw error;
+  } finally {
+    await saveMetaData();
+  }
+}

package/src/cli.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+import { Cli, Command, Option } from 'clipanion';
+import { config } from 'dotenv';
+import * as fs from 'fs';
+import * as path from 'path';
+import { buildSite } from './build/pipeline';
+
+// 加载 .env 文件中的环境变量
+config();
+
+// 获取版本号 - 从 package.json 读取
+function getVersion(): string {
+  const packageJsonPath = path.join(__dirname, '..', 'package.json');
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+  return packageJson.version;
+}
+
+// Build 命令
+class BuildCommand extends Command {
+  static paths = [['build']];
+
+  template = Option.String('-t,--template');
+  verbose = Option.Boolean('-v,--verbose');
+  lang = Option.Array('--lang', {
+    description: 'Target languages for translation (e.g., en-US, ja-JP)',
+  });
+
+  static usage = Command.Usage({
+    description: 'Build documentation site from Markdown files in current directory',
+    details: `
+      This command builds a documentation site from Markdown files in the current directory.
+      The output will be placed in the .zen/dist directory.
+
+      Examples:
+        $ zengen build
+        $ zengen build --lang en-US --lang ja-JP (translate to English and Japanese)
+    `,
+  });
+
+  async execute() {
+    try {
+      await buildSite({
+        template: this.template ? path.resolve(this.template) : undefined,
+        verbose: this.verbose,
+        langs: this.lang,
+      });
+
+      return 0;
+    } catch (error) {
+      this.context.stderr.write(`❌ Build failed: ${error}\n`);
+      return 1;
+    }
+  }
+}
+
+// 创建 CLI 应用
+const cli = new Cli({
+  binaryName: 'zengen',
+  binaryLabel: 'ZEN - A minimalist Markdown documentation site builder',
+  binaryVersion: getVersion(),
+});
+
+// 注册命令
+cli.register(BuildCommand);
+
+// 运行 CLI
+cli.runExit(process.argv.slice(2), {
+  ...Cli.defaultContext,
+  stdin: process.stdin,
+  stdout: process.stdout,
+  stderr: process.stderr,
+});

package/src/findEntries.ts

@@ -0,0 +1,37 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+/**
+ * 使用git命令查找所有Markdown文件
+ * 使用git ls-files --others --cached --exclude-standard获取所有文件
+ * 然后过滤掉.zen目录和只保留.md文件
+ *
+ * @param dirPath 要扫描的目录路径
+ * @returns Promise<string[]> 返回Markdown文件的相对路径数组
+ */
+export const findMarkdownEntries = async (dirPath: string): Promise<string[]> => {
+  try {
+    // 使用git命令获取所有文件（包括已跟踪和未跟踪的文件）
+    // 在指定的目录下执行git命令
+    const { stdout } = await execAsync('git ls-files --others --cached --exclude-standard', {
+      cwd: dirPath,
+    });
+
+    // 按行分割并过滤
+    const files = stdout
+      .split('\n')
+      .filter(line => line.trim() !== '') // 移除空行
+      .filter(file => !file.startsWith('.zen')) // 过滤掉.zen目录下的文件
+      .filter(file => file.endsWith('.md')); // 只保留.md文件
+
+    return files;
+  } catch (error) {
+    console.error('Error finding markdown entries:', error);
+
+    // 如果git命令失败，返回空数组
+    // 这可以处理没有git仓库或git不可用的情况
+    return [];
+  }
+};

package/src/index.ts

@@ -0,0 +1 @@
+import './cli';