@tnotesjs/core 0.2.1 → 0.3.0

package/services/vitepress/index.ts

@@ -0,0 +1,7 @@
+/**
+ * services/vitepress/index.ts
+ *
+ * Vitepress 服务入口
+ */
+
+export { VitepressService } from './service'

package/services/vitepress/service.ts

@@ -0,0 +1,339 @@
+/**
+ * services/vitepress/VitepressService.ts
+ *
+ * VitePress 服务 - 封装 VitePress 开发服务器相关的业务逻辑
+ */
+
+import { spawn } from 'child_process'
+
+import { ConfigManager } from '../../config/ConfigManager'
+import { ROOT_DIR_PATH } from '../../config/constants'
+import { ProcessManager } from '../../core'
+import { logger, isPortInUse, killPortProcess, waitForPort } from '../../utils'
+
+/** VitePress 服务启动结果 */
+export interface VitepressStartResult {
+  pid: number
+  version: string
+  /** 启动耗时（毫秒） */
+  elapsed: number
+}
+
+export class VitepressService {
+  /** VitePress 开发服务器默认端口 */
+  static readonly DEFAULT_DEV_PORT = 5173
+
+  /** VitePress 预览服务器默认端口 */
+  static readonly DEFAULT_PREVIEW_PORT = 4173
+
+  /** 开发服务器进程 ID 后缀 */
+  private static readonly PROCESS_ID_DEV_SUFFIX = 'vitepress-dev'
+
+  /** 预览服务器进程 ID 后缀 */
+  private static readonly PROCESS_ID_PREVIEW_SUFFIX = 'vitepress-preview'
+
+  /** 服务启动超时时间（毫秒） */
+  private static readonly SERVER_STARTUP_TIMEOUT = 60000
+
+  /** 端口释放等待超时时间（毫秒） */
+  private static readonly PORT_RELEASE_TIMEOUT = 3000
+
+  /** 进程清理等待时间（毫秒） */
+  private static readonly PROCESS_CLEANUP_DELAY = 3000
+
+  /** 显示启动服务状态行间隔（毫秒） */
+  private static readonly SERVER_STATUS_LINE_INTERVAL = 1000
+
+  /** 默认包管理器 */
+  private static readonly DEFAULT_PACKAGE_MANAGER = 'pnpm'
+
+  private processManager: ProcessManager
+  private configManager: ConfigManager
+
+  constructor() {
+    this.processManager = new ProcessManager()
+    this.configManager = ConfigManager.getInstance()
+  }
+
+  /**
+   * 启动 VitePress 开发服务器
+   * @returns 启动结果（服务就绪后返回），失败时返回 undefined
+   */
+  async startServer(): Promise<VitepressStartResult | undefined> {
+    const port =
+      this.configManager.get('port') || VitepressService.DEFAULT_DEV_PORT
+    const repoName = this.configManager.get('repoName')
+    const processId = `${repoName}-${VitepressService.PROCESS_ID_DEV_SUFFIX}`
+
+    // 检查内存中的进程管理器（清理残留）
+    if (
+      this.processManager.has(processId) &&
+      this.processManager.isRunning(processId)
+    ) {
+      this.processManager.kill(processId)
+      await new Promise((resolve) =>
+        setTimeout(resolve, VitepressService.PROCESS_CLEANUP_DELAY),
+      )
+    }
+
+    // 检查目标端口是否被占用，如果是则强制清理
+    if (isPortInUse(port)) {
+      logger.warn(`端口 ${port} 被占用，正在清理...`)
+      killPortProcess(port)
+      const available = await waitForPort(
+        port,
+        VitepressService.PORT_RELEASE_TIMEOUT,
+      )
+
+      if (available) {
+        logger.info(`端口 ${port} 已释放，继续启动服务`)
+      } else {
+        logger.warn(
+          `端口 ${port} 未确认释放，仍将尝试启动；如启动失败，请手动清理该端口`,
+        )
+      }
+    }
+
+    // 启动 VitePress 开发服务器
+    const pm =
+      this.configManager.get('packageManager') ||
+      VitepressService.DEFAULT_PACKAGE_MANAGER
+    const args = ['vitepress', 'dev', '--port', port.toString()]
+
+    const processInfo = this.processManager.spawn(processId, pm, args, {
+      cwd: ROOT_DIR_PATH,
+      stdio: ['inherit', 'pipe', 'pipe'], // stdin 继承，stdout/stderr 管道捕获
+    })
+
+    // 等待服务就绪，显示启动状态
+    const serverInfo = await this.waitForServerReady(processInfo.process)
+
+    if (!processInfo.pid) return undefined
+
+    return {
+      pid: processInfo.pid,
+      version: serverInfo.version,
+      elapsed: serverInfo.elapsed,
+    }
+  }
+
+  /**
+   * 等待服务就绪，显示启动状态
+   * @param childProcess - 子进程
+   */
+  private waitForServerReady(
+    childProcess: import('child_process').ChildProcess,
+  ): Promise<{ version: string; elapsed: number }> {
+    return new Promise((resolve) => {
+      const startTime = Date.now()
+      let serverReady = false
+      let version = ''
+
+      // 定时器：显示启动状态（真实的已用时间）
+      const statusTimer = setInterval(() => {
+        if (serverReady) {
+          clearInterval(statusTimer)
+          return
+        }
+
+        const elapsed = Date.now() - startTime
+        const seconds = (elapsed / 1000).toFixed(0)
+        // 使用 stderr 输出，避免与 VitePress 输出混在一起
+        process.stderr.clearLine?.(0)
+        process.stderr.cursorTo?.(0)
+        process.stderr.write(`⏳ 启动中: 已用 ${seconds}s...`)
+      }, VitepressService.SERVER_STATUS_LINE_INTERVAL)
+
+      // 处理输出
+      const handleOutput = (data: string) => {
+        const text = data.toString()
+
+        // 提取版本号
+        const versionMatch = text.match(/vitepress v([\d.]+)/)
+        if (versionMatch) {
+          version = versionMatch[1]
+        }
+
+        // 检测服务就绪
+        if (
+          !serverReady &&
+          (text.includes('Local:') ||
+            text.includes('http://localhost') ||
+            (text.includes('➜') && text.includes('Local')))
+        ) {
+          serverReady = true
+          clearInterval(statusTimer)
+
+          // 清除状态行
+          process.stderr.clearLine?.(0)
+          process.stderr.cursorTo?.(0)
+
+          const elapsed = Date.now() - startTime
+
+          // 延迟 resolve，让后续输出完成
+          setTimeout(() => resolve({ version, elapsed }), 200)
+          return
+        }
+
+        // 服务就绪前只显示错误信息
+        if (!serverReady) {
+          if (
+            text.includes('error') ||
+            text.includes('Error') ||
+            (text.includes('Port') && text.includes('is in use'))
+          ) {
+            process.stderr.clearLine?.(0)
+            process.stderr.cursorTo?.(0)
+            process.stdout.write(data)
+          }
+        }
+      }
+
+      // 监听输出
+      if (childProcess.stdout) {
+        childProcess.stdout.setEncoding('utf8')
+        childProcess.stdout.on('data', handleOutput)
+      }
+
+      if (childProcess.stderr) {
+        childProcess.stderr.setEncoding('utf8')
+        childProcess.stderr.on('data', handleOutput)
+      }
+
+      // 超时处理
+      setTimeout(() => {
+        if (!serverReady) {
+          serverReady = true
+          clearInterval(statusTimer)
+          process.stderr.clearLine?.(0)
+          process.stderr.cursorTo?.(0)
+          logger.warn('启动超时，请检查 VitePress 输出')
+          resolve({ version, elapsed: VitepressService.SERVER_STARTUP_TIMEOUT })
+        }
+      }, VitepressService.SERVER_STARTUP_TIMEOUT)
+    })
+  }
+
+  /**
+   * 构建生产版本
+   */
+  build(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const pm =
+        this.configManager.get('packageManager') ||
+        VitepressService.DEFAULT_PACKAGE_MANAGER
+      const child = spawn(pm, ['vitepress', 'build'], {
+        cwd: ROOT_DIR_PATH,
+        shell: true,
+        stdio: ['inherit', 'pipe', 'pipe'],
+        env: {
+          ...process.env,
+          NODE_OPTIONS: (process.env.NODE_OPTIONS || '').includes(
+            '--max-old-space-size',
+          )
+            ? process.env.NODE_OPTIONS
+            : [process.env.NODE_OPTIONS, '--max-old-space-size=4096']
+                .filter(Boolean)
+                .join(' '),
+        },
+      })
+
+      // 过滤 VitePress 的 spinner 和状态输出，但保留我们的进度条
+      const filterOutput = (data: Buffer) => {
+        const str = data.toString()
+
+        // 允许我们的进度条和结果输出
+        if (
+          str.includes('🔨') ||
+          str.includes('✅') ||
+          str.includes('❌ 构建失败') ||
+          str.includes('📁') ||
+          str.includes('📊') ||
+          str.includes('📦') ||
+          str.includes('⏱️') ||
+          str.includes('⏳') ||
+          str.includes('Building [') ||
+          str.includes('error') ||
+          str.includes('Error')
+        ) {
+          process.stdout.write(data)
+          return
+        }
+
+        // 过滤掉 VitePress 的 spinner 和状态输出
+        // 包括: ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ spinner 字符, ✓ 完成标记, vitepress 版本信息等
+        if (
+          /^[\s⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏✓\r\n]*$/.test(str) ||
+          str.includes('building client + server') ||
+          str.includes('rendering pages') ||
+          str.includes('generating sitemap') ||
+          str.includes('build complete in') ||
+          str.includes('vitepress v')
+        ) {
+          return // 静默这些输出
+        }
+
+        // 其他输出也静默（插件已经在内部拦截了）
+      }
+
+      child.stdout?.on('data', filterOutput)
+      child.stderr?.on('data', filterOutput)
+
+      child.on('error', (err: Error) => {
+        reject(err)
+      })
+
+      child.on('close', (code: number) => {
+        if (code === 0) {
+          resolve()
+        } else {
+          reject(new Error(`Command failed with code ${code}`))
+        }
+      })
+    })
+  }
+
+  /**
+   * 预览构建后的站点
+   */
+  async preview(): Promise<number | undefined> {
+    const repoName = this.configManager.get('repoName')
+    const processId = `${repoName}-${VitepressService.PROCESS_ID_PREVIEW_SUFFIX}`
+    const pm =
+      this.configManager.get('packageManager') ||
+      VitepressService.DEFAULT_PACKAGE_MANAGER
+    const args = ['vitepress', 'preview']
+    const previewPort = VitepressService.DEFAULT_PREVIEW_PORT
+
+    // 检查端口是否被占用
+    if (isPortInUse(previewPort)) {
+      logger.warn(`端口 ${previewPort} 已被占用，正在尝试清理...`)
+      const killed = killPortProcess(previewPort)
+
+      if (killed) {
+        // 等待端口释放
+        const available = await waitForPort(
+          previewPort,
+          VitepressService.PORT_RELEASE_TIMEOUT,
+        )
+        if (!available) {
+          logger.error(`端口 ${previewPort} 释放超时，请手动清理`)
+          return undefined
+        }
+        logger.info(`端口 ${previewPort} 已释放`)
+      } else {
+        logger.error(
+          `无法清理端口 ${previewPort}，请手动执行: taskkill /F /PID <PID>`,
+        )
+        return undefined
+      }
+    }
+
+    const processInfo = this.processManager.spawn(processId, pm, args, {
+      cwd: ROOT_DIR_PATH,
+      stdio: 'inherit',
+    })
+
+    return processInfo.pid
+  }
+}

package/types/config.ts

@@ -54,7 +54,4 @@ export interface RootItem {
   completed_notes_count: Record<string, number>
   details: string
   link: string
-  created_at?: number
-  updated_at?: number
-  days_since_birth?: number
 }

package/types/note.ts

@@ -16,8 +16,6 @@ export interface NoteConfig {
   category?: string
   enableDiscussions: boolean
   description?: string // 笔记简介(一句话描述)
-  created_at?: number
-  updated_at?: number
 }
 
 /**

package/utils/errorHandler.ts

@@ -0,0 +1,174 @@
+/**
+ * utils/errorHandler.ts
+ *
+ * 统一的错误处理系统
+ */
+
+/** TNotes 错误代码枚举 */
+export enum ErrorCode {
+  // 文件系统错误
+  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
+  FILE_READ_ERROR = 'FILE_READ_ERROR',
+  FILE_WRITE_ERROR = 'FILE_WRITE_ERROR',
+
+  // Git 相关错误
+  GIT_NOT_REPO = 'GIT_NOT_REPO',
+  GIT_COMMAND_FAILED = 'GIT_COMMAND_FAILED',
+  GIT_MERGE_CONFLICT = 'GIT_MERGE_CONFLICT',
+
+  // 笔记相关错误
+  NOTE_INDEX_INVALID = 'NOTE_INDEX_INVALID',
+  NOTE_CONFIG_INVALID = 'NOTE_CONFIG_INVALID',
+  NOTE_NOT_FOUND = 'NOTE_NOT_FOUND',
+
+  // 配置错误
+  CONFIG_INVALID = 'CONFIG_INVALID',
+  CONFIG_MISSING = 'CONFIG_MISSING',
+
+  // 命令执行错误
+  COMMAND_NOT_FOUND = 'COMMAND_NOT_FOUND',
+  COMMAND_FAILED = 'COMMAND_FAILED',
+
+  // 服务器错误
+  SERVER_START_FAILED = 'SERVER_START_FAILED',
+  SERVER_STOP_FAILED = 'SERVER_STOP_FAILED',
+  PORT_IN_USE = 'PORT_IN_USE',
+
+  // 未知错误
+  UNKNOWN = 'UNKNOWN',
+}
+
+/**
+ * TNotes 自定义错误类
+ */
+class TNotesError extends Error {
+  constructor(
+    message: string,
+    public code: ErrorCode = ErrorCode.UNKNOWN,
+    public context?: Record<string, any>,
+  ) {
+    super(message)
+    this.name = 'TNotesError'
+
+    // 保持正确的堆栈跟踪
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, TNotesError)
+    }
+  }
+}
+
+/**
+ * 统一的错误处理函数
+ */
+export function handleError(error: unknown, exitOnError = false): void {
+  if (error instanceof TNotesError) {
+    console.error(`❌ TNotesError`)
+    console.error(`错误码：${error.code}`)
+    console.error(`错误信息：${error.message}`)
+
+    if (error.context && Object.keys(error.context).length > 0) {
+      console.error('错误上下文信息：', error.context)
+    }
+
+    if (error.stack && process.env.DEBUG) {
+      console.error('错误堆栈信息：', error.stack)
+    }
+  } else if (error instanceof Error) {
+    console.error(`❌ Error`)
+    console.error(`错误信息：${error.message}`)
+
+    if (error.stack && process.env.DEBUG) {
+      console.error('错误堆栈信息：', error.stack)
+    }
+  } else {
+    console.error('❌ 未知错误：', error)
+  }
+
+  if (exitOnError) {
+    process.exit(1)
+  }
+}
+
+/**
+ * 创建特定类型的错误
+ */
+export const createError = {
+  fileNotFound: (path: string) =>
+    new TNotesError(`文件未找到：${path}`, ErrorCode.FILE_NOT_FOUND, {
+      path,
+    }),
+
+  fileReadError: (path: string, originalError?: Error) =>
+    new TNotesError(`读取文件失败：${path}`, ErrorCode.FILE_READ_ERROR, {
+      path,
+      originalError: originalError?.message,
+    }),
+
+  fileWriteError: (path: string, originalError?: Error) =>
+    new TNotesError(`写入文件失败：${path}`, ErrorCode.FILE_WRITE_ERROR, {
+      path,
+      originalError: originalError?.message,
+    }),
+
+  gitNotRepo: (dir: string) =>
+    new TNotesError(`不是一个 Git 仓库：${dir}`, ErrorCode.GIT_NOT_REPO, {
+      dir,
+    }),
+
+  gitCommandFailed: (command: string, dir: string, originalError?: Error) =>
+    new TNotesError(`Git 命令失败：${command}`, ErrorCode.GIT_COMMAND_FAILED, {
+      command,
+      dir,
+      originalError: originalError?.message,
+    }),
+
+  noteIndexInvalid: (noteIndex: string) =>
+    new TNotesError(
+      `无效的笔记索引：${noteIndex}`,
+      ErrorCode.NOTE_INDEX_INVALID,
+      {
+        noteIndex,
+      },
+    ),
+
+  noteConfigInvalid: (notePath: string, reason?: string) =>
+    new TNotesError(
+      `无效的笔记配置：${notePath}`,
+      ErrorCode.NOTE_CONFIG_INVALID,
+      { notePath, reason },
+    ),
+
+  configInvalid: (field: string, reason: string) =>
+    new TNotesError(`无效的配置字段：${field}`, ErrorCode.CONFIG_INVALID, {
+      field,
+      reason,
+    }),
+
+  commandNotFound: (commandName: string) =>
+    new TNotesError(`未找到命令：${commandName}`, ErrorCode.COMMAND_NOT_FOUND, {
+      commandName,
+    }),
+
+  commandFailed: (
+    commandName: string,
+    exitCode?: number,
+    originalError?: Error,
+  ) =>
+    new TNotesError(`命令执行失败：${commandName}`, ErrorCode.COMMAND_FAILED, {
+      commandName,
+      exitCode,
+      originalError: originalError?.message,
+    }),
+
+  serverStartFailed: (port: number, originalError?: Error) =>
+    new TNotesError(
+      `启动服务器失败：端口 ${port}`,
+      ErrorCode.SERVER_START_FAILED,
+      { port, originalError: originalError?.message },
+    ),
+
+  portInUse: (port: number) =>
+    new TNotesError(`端口 ${port} 已被占用`, ErrorCode.PORT_IN_USE, {
+      port,
+    }),
+}

package/utils/file.ts

@@ -0,0 +1,17 @@
+/**
+ * utils/file.ts
+ *
+ * 文件操作工具函数
+ */
+
+import fs from 'fs'
+
+/**
+ * 确保目录存在
+ * @param dir - 目录路径
+ */
+export async function ensureDirectory(dir: string): Promise<void> {
+  if (!fs.existsSync(dir)) {
+    await fs.promises.mkdir(dir, { recursive: true })
+  }
+}

package/utils/genHierarchicalSidebar.ts

@@ -0,0 +1,69 @@
+/**
+ * utils/genHierarchicalSidebar.ts
+ *
+ * 生成层次化侧边栏
+ */
+
+/** 侧边栏项类型 */
+interface SidebarItem {
+  text: string
+  link?: string
+  collapsed?: boolean
+  items?: SidebarItem[]
+}
+
+interface StackItem {
+  level: number
+  node: SidebarItem
+}
+
+/**
+ * 生成层次化侧边栏
+ * @param itemList - 笔记项列表
+ * @param titles - 标题列表
+ * @param titlesNotesCount - 每个标题下的笔记数量
+ * @param sidebarIsCollapsed - 侧边栏是否默认折叠
+ * @returns 层次化的侧边栏结构
+ */
+export const genHierarchicalSidebar = (
+  itemList: SidebarItem[],
+  titles: string[],
+  titlesNotesCount: number[],
+  sidebarIsCollapsed: boolean,
+): SidebarItem[] => {
+  const stack: StackItem[] = []
+  const root: SidebarItem[] = []
+
+  titles.forEach((title, i) => {
+    const match = title.match(/^#+/)
+    if (!match) return
+
+    const level = match[0].length
+    const text = title.replace(/^#+\s*/, '')
+    const noteItems = itemList.splice(0, titlesNotesCount[i])
+
+    const node: SidebarItem = {
+      text,
+      collapsed: sidebarIsCollapsed,
+      items: noteItems.length > 0 ? noteItems : [],
+    }
+
+    if (i === 0 && level === 1) return
+
+    while (stack.length > 0 && stack[stack.length - 1].level >= level) {
+      stack.pop()
+    }
+
+    if (stack.length === 0) {
+      root.push(node)
+    } else {
+      const parent = stack[stack.length - 1].node
+      if (!parent.items) parent.items = []
+      parent.items.push(node)
+    }
+
+    stack.push({ level, node })
+  })
+
+  return root
+}

package/utils/generateAnchor.ts

@@ -0,0 +1,24 @@
+/**
+ * utils/generateAnchor.ts
+ * 
+ * 生成 GitHub 风格的锚点
+ */
+
+import GithubSlugger from 'github-slugger'
+
+const slugger = new GithubSlugger()
+
+/**
+ * 生成 GitHub 风格的锚点
+ *
+ * !注意：锚点的生成规则要保持一致：
+ * - .vitepress/config/markdown.config.ts - markdown.anchor.slugify
+ * - .vitepress/tnotes/update.ts
+ *
+ * @param label - 标题文本
+ * @returns 生成的锚点字符串
+ */
+export const generateAnchor = (label: string): string => {
+  slugger.reset()
+  return slugger.slug(label)
+}

package/utils/getChangedIds.ts

@@ -0,0 +1,35 @@
+/**
+ * utils/getChangedIds.ts
+ *
+ * 获取 Git 中变更的笔记 ID 集合
+ */
+
+import { execSync } from 'child_process'
+import path from 'path'
+
+/**
+ * 获取 Git 中变更的笔记 ID 集合
+ * @returns 变更的笔记 ID 集合
+ */
+export function getChangedIds(): Set<string> {
+  const changedFiles = execSync(
+    `git diff --name-only HEAD -- "notes/[0-9][0-9][0-9][0-9]*/README.md"`
+    // 根据当前仓库状态和最近一次提交之间的比较
+  )
+    .toString()
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((fp) => fp.replace(/^"|"$/g, '')) // 去掉 Git 输出的双引号
+    .map((fp) => fp.split('/').join(path.sep)) // 转换为平台路径
+
+  const changedIds = changedFiles
+    .map((fp) => {
+      const parts = fp.split(path.sep)
+      const dirName = parts.find((p, i) => parts[i - 1] === 'notes')
+      return dirName?.slice(0, 4)
+    })
+    .filter((id): id is string => Boolean(id))
+
+  // 移除日志输出，由调用方决定是否输出
+  return new Set(changedIds)
+}