@tnotesjs/core 0.2.1 → 0.2.2

package/services/file-watcher/folderChangeHandler.ts

@@ -0,0 +1,325 @@
+/**
+ * services/file-watcher/folderChangeHandler.ts
+ *
+ * 文件夹变更处理：删除、重命名、回退
+ */
+
+import { existsSync, promises as fsPromises } from 'fs'
+import { join } from 'path'
+
+import { safeExecute } from './internal'
+import { REPO_NOTES_URL } from '../../config/constants'
+import { generateNoteTitle } from '../../config/templates'
+
+import type { EventScheduler } from './eventScheduler'
+import type { WatchState } from './watchState'
+import type { NoteIndexCache } from '../../core/NoteIndexCache'
+import type { Logger } from '../../utils'
+import type { NoteService } from '../note/service'
+import type { ReadmeService } from '../readme/service'
+import type { TocService } from '../toc/service'
+
+const RENAME_REVERT_DELAY_MS = 2000
+
+/**
+ * 检测到笔记目录名称变更或者被删除的事件时，需要更新根目录下的 README.md 和 sidebar.json
+ *
+ * 暂定 1s 作为缓冲，1s 过后再恢复监听
+ */
+const DELETE_REINIT_DELAY_MS = 1000
+
+const UPDATE_UNLOCK_DELAY_MS = 500
+
+interface FolderChangeHandlerConfig {
+  /** 笔记目录路径 */
+  notesDir: string
+  /** 监听状态管理器 */
+  watchState: WatchState
+  /** 事件调度器 */
+  scheduler: EventScheduler
+  /** 笔记服务实例 */
+  noteService: NoteService
+  /** README 服务实例 */
+  readmeService: ReadmeService
+  /** TOC 服务实例 */
+  tocService: TocService
+  /** 笔记索引缓存实例 */
+  noteIndexCache: NoteIndexCache
+  /** 日志记录器 */
+  logger: Logger
+  /**
+   * 文件夹重命名成功后回调（可选）。
+   *
+   * 用于在 dev server 中通过 Vite WS 通知前端跳转到新 URL，
+   * 让「文件系统直接改名」与「关于面板保存」体验一致。
+   */
+  onRenameSuccess?: (payload: {
+    oldFolder: string
+    newFolder: string
+    noteIndex: string
+  }) => void
+  /** 笔记结构变更（增删改目录）后触发 dev 搜索索引重建 */
+  onNoteStructureChanged?: (reason: string) => void
+}
+
+export class FolderChangeHandler {
+  /** 活跃的定时器 ID 集合，用于统一清理 */
+  private activeTimers: Set<NodeJS.Timeout> = new Set()
+
+  constructor(private config: FolderChangeHandlerConfig) {}
+
+  /**
+   * 清理所有活跃定时器，释放资源
+   *
+   * 在服务停止时调用，防止定时器在服务销毁后仍然触发回调
+   */
+  clearTimers(): void {
+    for (const timer of this.activeTimers) {
+      clearTimeout(timer)
+    }
+    this.activeTimers.clear()
+  }
+
+  private scheduleTimer(fn: () => void, delay: number): void {
+    const timer = setTimeout(() => {
+      this.activeTimers.delete(timer)
+      fn()
+    }, delay)
+    this.activeTimers.add(timer)
+  }
+
+  async handleFolderDeletion(deletedFolderName: string): Promise<void> {
+    const { scheduler, watchState, noteIndexCache, tocService, logger } =
+      this.config
+
+    if (scheduler.getUpdating()) return
+    scheduler.setUpdating(true)
+
+    try {
+      const noteIndex = this.extractNoteIndexOrWarn(deletedFolderName)
+      if (!noteIndex) return
+
+      logger.info(`正在处理笔记删除: ${noteIndex} (${deletedFolderName})`)
+
+      // 清理缓存
+      watchState.deleteNoteDir(deletedFolderName)
+      watchState.clearNoteCaches(deletedFolderName)
+      noteIndexCache.delete(noteIndex)
+
+      // 更新根 README.md、sidebar.json
+      await safeExecute(
+        `删除笔记 ${noteIndex}`,
+        async () => {
+          await tocService.deleteNoteFromToc(noteIndex)
+          await tocService.regenerateSidebar()
+          this.config.onNoteStructureChanged?.(`watcher:delete:${noteIndex}`)
+        },
+        logger,
+      )
+    } finally {
+      this.scheduleTimer(() => {
+        scheduler.setUpdating(false)
+        watchState.initializeFromDisk()
+      }, DELETE_REINIT_DELAY_MS)
+    }
+  }
+
+  async handleFolderRenameUpdate(
+    oldName: string,
+    newName: string,
+  ): Promise<void> {
+    const { scheduler, watchState, logger } = this.config
+
+    if (scheduler.getUpdating()) return
+    scheduler.setUpdating(true)
+
+    try {
+      const { oldNoteIndex, newNoteIndex } = this.validateRenameIndexes(
+        oldName,
+        newName,
+      )
+      if (!oldNoteIndex || !newNoteIndex) return
+
+      logger.info(`正在处理文件夹重命名: ${oldName} → ${newName}`)
+
+      if (oldNoteIndex === newNoteIndex) {
+        await safeExecute(
+          `标题重命名 ${newNoteIndex}`,
+          () => this.handleTitleOnlyRename(newNoteIndex, newName),
+          logger,
+        )
+      } else {
+        await safeExecute(
+          `索引变更 ${oldNoteIndex}→${newNoteIndex}`,
+          () => this.handleIndexChangedRename(oldNoteIndex, newNoteIndex),
+          logger,
+        )
+      }
+
+      this.config.onRenameSuccess?.({
+        oldFolder: oldName,
+        newFolder: newName,
+        noteIndex: newNoteIndex,
+      })
+    } finally {
+      this.scheduleTimer(() => {
+        scheduler.setUpdating(false)
+        watchState.initializeFromDisk()
+      }, UPDATE_UNLOCK_DELAY_MS)
+    }
+  }
+
+  // #region - 私有实现
+
+  private validateRenameIndexes(
+    oldName: string,
+    newName: string,
+  ): { oldNoteIndex: string | null; newNoteIndex: string | null } {
+    const { noteIndexCache, logger } = this.config
+    const oldNoteIndex = this.extractNoteIndexOrWarn(oldName)
+    const newNoteIndex = this.extractNoteIndexOrWarn(newName)
+
+    if (!oldNoteIndex || !newNoteIndex) {
+      return { oldNoteIndex: null, newNoteIndex: null }
+    }
+
+    if (!/^\d{4}$/.test(newNoteIndex)) {
+      logger.error(`新笔记索引格式非法: ${newNoteIndex}，自动回退`)
+      this.revertFolderRename(oldName, newName)
+      return { oldNoteIndex: null, newNoteIndex: null }
+    }
+
+    if (oldNoteIndex !== newNoteIndex && noteIndexCache.has(newNoteIndex)) {
+      logger.error(`新笔记索引 ${newNoteIndex} 已存在，自动回退`)
+      this.revertFolderRename(oldName, newName)
+      return { oldNoteIndex: null, newNoteIndex: null }
+    }
+
+    return { oldNoteIndex, newNoteIndex }
+  }
+
+  private async handleTitleOnlyRename(
+    noteIndex: string,
+    newName: string,
+  ): Promise<void> {
+    const { noteIndexCache, tocService, logger, notesDir } = this.config
+
+    logger.info(`笔记索引未变 (${noteIndex})，只更新标题`)
+    noteIndexCache.updateFolderName(noteIndex, newName)
+
+    // 同步重写笔记目录内 README.md 的一级标题，与 RenameNoteCommand 行为一致
+    await safeExecute(
+      `更新 README 一级标题 ${noteIndex}`,
+      () => this.rewriteNoteReadmeH1(notesDir, newName, noteIndex),
+      logger,
+    )
+
+    await tocService.renameNoteInToc(noteIndex, newName)
+    await tocService.regenerateSidebar()
+    this.config.onNoteStructureChanged?.(`watcher:rename-title:${noteIndex}`)
+    logger.success(`标题更新完成`)
+  }
+
+  /**
+   * 重写指定笔记目录下 README.md 的一级标题。
+   *
+   * 输入的 `folderName` 形如 `0003. 评论功能的技术实现`，
+   * 据此推导出新标题文本（去掉 `${noteIndex}. ` 前缀）。
+   */
+  private async rewriteNoteReadmeH1(
+    notesDir: string,
+    folderName: string,
+    noteIndex: string,
+  ): Promise<void> {
+    const readmePath = join(notesDir, folderName, 'README.md')
+    if (!existsSync(readmePath)) return
+
+    const newTitle = folderName.replace(/^\d{4}\.\s*/, '').trim()
+    if (!newTitle) return
+
+    const content = await fsPromises.readFile(readmePath, 'utf-8')
+    const lines = content.split('\n')
+
+    let h1Index = -1
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].trim().startsWith('# ')) {
+        h1Index = i
+        break
+      }
+    }
+
+    if (h1Index === -1) {
+      this.config.logger.warn(
+        `未在 ${readmePath} 找到一级标题，跳过 README H1 更新`,
+      )
+      return
+    }
+
+    const newH1 = generateNoteTitle(noteIndex, newTitle, REPO_NOTES_URL)
+    if (lines[h1Index] === newH1) return
+
+    lines[h1Index] = newH1
+    await fsPromises.writeFile(readmePath, lines.join('\n'), 'utf-8')
+  }
+
+  private async handleIndexChangedRename(
+    oldNoteIndex: string,
+    newNoteIndex: string,
+  ): Promise<void> {
+    const { noteService, noteIndexCache, tocService, logger } = this.config
+
+    logger.info(`笔记索引变更: ${oldNoteIndex} → ${newNoteIndex}`)
+
+    await tocService.deleteNoteFromToc(oldNoteIndex)
+
+    const newNote = noteService.getNoteByIndex(newNoteIndex)
+
+    if (newNote) {
+      noteIndexCache.delete(oldNoteIndex)
+      noteIndexCache.add(newNote)
+
+      await tocService.appendNoteToToc(newNoteIndex)
+      await tocService.regenerateSidebar()
+      this.config.onNoteStructureChanged?.(
+        `watcher:rename-index:${oldNoteIndex}->${newNoteIndex}`,
+      )
+      logger.success(`笔记索引变更处理完成`)
+    } else {
+      logger.error(`未找到新笔记: ${newNoteIndex}`)
+    }
+  }
+
+  private async revertFolderRename(
+    oldName: string,
+    newName: string,
+  ): Promise<void> {
+    const { notesDir, scheduler, watchState, logger } = this.config
+
+    try {
+      const oldPath = join(notesDir, oldName)
+      const newPath = join(notesDir, newName)
+
+      if (existsSync(newPath)) {
+        scheduler.setUpdating(true)
+        await fsPromises.rename(newPath, oldPath)
+        logger.warn(`文件夹已回退: ${newName} → ${oldName}`)
+        this.scheduleTimer(() => {
+          scheduler.setUpdating(false)
+          watchState.initializeFromDisk()
+        }, RENAME_REVERT_DELAY_MS)
+      }
+    } catch (error) {
+      logger.error(`回退文件夹重命名失败: ${error}`)
+    }
+  }
+
+  private extractNoteIndexOrWarn(name: string): string | null {
+    const noteIndex = name.match(/^(\d{4})/)?.[1] || null
+    if (!noteIndex) {
+      this.config.logger.warn(`无法从文件夹名称提取笔记索引: ${name}`)
+    }
+    return noteIndex
+  }
+
+  // #endregion - 私有实现
+}

package/services/file-watcher/fsWatcherAdapter.ts

@@ -0,0 +1,128 @@
+/**
+ * services/file-watcher/fsWatcherAdapter.ts
+ *
+ *  fs.watch 适配器：仅负责监听和事件分发
+ */
+
+import { watch } from 'fs'
+import { basename, dirname, join, sep } from 'path'
+
+import { WATCH_EVENT_TYPES } from './internal'
+import { NoteManager } from '../../core/NoteManager'
+
+import type { WatchEvent, WatchEventType } from './internal'
+import type { Logger } from '../../utils'
+import type { FSWatcher } from 'fs'
+
+interface FsWatcherAdapterConfig {
+  /** 笔记目录路径 */
+  notesDir: string
+  /** 检查是否正在更新的方法 */
+  isUpdating: () => boolean
+  /** 文件夹重命名事件回调 */
+  onRename: (folderName: string) => void
+  /** 笔记事件处理回调 */
+  onNoteEvent: (event: WatchEvent) => void
+  /** 日志记录器 */
+  logger: Logger
+}
+
+export class FsWatcherAdapter {
+  /** 文件系统监听器实例 */
+  private watcher: FSWatcher | null = null
+
+  constructor(private config: FsWatcherAdapterConfig) {}
+
+  start(): void {
+    const { logger } = this.config
+
+    if (this.watcher) {
+      logger.warn('文件监听服务已启动')
+      return
+    }
+
+    this.watcher = watch(
+      this.config.notesDir,
+      { recursive: true },
+      (eventType, filename) => this.handleFsEvent(eventType, filename),
+    )
+
+    logger.debug(`文件监听已启动，监听目录：${this.config.notesDir}`)
+  }
+
+  stop(): void {
+    if (!this.watcher) return
+    this.watcher.close()
+    this.watcher = null
+  }
+
+  isWatching(): boolean {
+    return this.watcher !== null
+  }
+
+  private handleFsEvent(eventType: string, filename: string | undefined): void {
+    const { isUpdating, onRename, onNoteEvent } = this.config
+
+    // 过滤无效事件
+    // 处理需要跳过监听的场景
+    if (
+      !filename || // 忽略无文件变更
+      isUpdating() // 如果正在更新，忽略所有变更
+    ) {
+      return
+    }
+
+    // 文件夹级事件
+    // 处理笔记名称（笔记所属的直接父级文件夹名称）发生变化的场景
+    // 根层 rename：文件夹创建/删除/重命名，交给 RenameDetector
+    if (
+      eventType === 'rename' && // 检测文件夹 rename 事件
+      !filename.includes(sep) // 顶层文件夹名称发生变更
+    ) {
+      onRename(filename)
+      return
+    }
+
+    // 文件级事件
+    // 处理笔记文件内容（笔记 README.md 文件、笔记配置 .tnotes.json 文件）发生变化的场景
+    // 只处理 README.md 和 .tnotes.json 文件的变更
+    const baseFilename = basename(filename)
+    if (baseFilename !== 'README.md' && baseFilename !== '.tnotes.json') {
+      // 忽略非目标文件的变更事件（如 assets 文件夹、其他文件等）
+      return
+    }
+
+    const fullPath = join(this.config.notesDir, filename)
+    const event = this.buildWatchEvent(fullPath, filename)
+    if (!event) {
+      // 无法构建变更事件 - 通常是笔记格式错误导致，比如笔记名的索引不是 0001-9999
+      return
+    }
+
+    onNoteEvent(event)
+  }
+
+  private buildWatchEvent(
+    fullPath: string,
+    filename: string,
+  ): WatchEvent | null {
+    const noteDirName = basename(dirname(fullPath))
+    const noteIndex = NoteManager.extractNoteIndex(noteDirName)
+    if (!noteIndex) {
+      NoteManager.warnInvalidNoteIndex(noteDirName)
+      return null
+    }
+
+    const fileType: WatchEventType = filename.endsWith('README.md')
+      ? WATCH_EVENT_TYPES.README
+      : WATCH_EVENT_TYPES.CONFIG
+
+    return {
+      path: fullPath,
+      type: fileType,
+      noteIndex,
+      noteDirName,
+      noteDirPath: dirname(fullPath),
+    }
+  }
+}

package/services/file-watcher/globalUpdateCoordinator.ts

@@ -0,0 +1,60 @@
+/**
+ * services/file-watcher/globalUpdateCoordinator.ts
+ *
+ * 全局更新协调：应用配置更新、更新 README 列表
+ */
+
+import { safeExecute } from './internal'
+
+import type { WatchEvent } from './internal'
+import type { NoteIndexCache } from '../../core/NoteIndexCache'
+import type { Logger } from '../../utils'
+import type { ReadmeService } from '../readme/service'
+import type { TocService } from '../toc/service'
+
+
+interface GlobalUpdateCoordinatorConfig {
+  /** README 服务实例，用于更新笔记 README */
+  readmeService: ReadmeService
+  /** TOC 服务实例，用于更新 TOC.md 与 sidebar */
+  tocService: TocService
+  /** 笔记索引缓存实例 */
+  noteIndexCache: NoteIndexCache
+  /** 日志记录器 */
+  logger: Logger
+}
+
+export class GlobalUpdateCoordinator {
+  constructor(private config: GlobalUpdateCoordinatorConfig) {}
+
+  async applyConfigUpdates(changedNoteIndexes: string[]): Promise<void> {
+    if (changedNoteIndexes.length === 0) return
+
+    const { tocService, noteIndexCache, logger } = this.config
+
+    logger.info('检测到笔记状态变化，增量更新全局文件...')
+
+    for (const noteIndex of changedNoteIndexes) {
+      await safeExecute(
+        `增量更新 ${noteIndex}`,
+        async () => {
+          const item = noteIndexCache.getByNoteIndex(noteIndex)
+          await tocService.updateNoteInToc(
+            noteIndex,
+            item?.noteConfig || {},
+          )
+          logger.info(`增量更新 TOC.md 中的笔记: ${noteIndex}`)
+        },
+        logger,
+      )
+    }
+
+    await tocService.regenerateSidebar()
+  }
+
+  async updateNoteReadmesOnly(events: WatchEvent[]): Promise<void> {
+    const noteIndexesToUpdate = [...new Set(events.map((c) => c.noteIndex))]
+    if (noteIndexesToUpdate.length === 0) return
+    await this.config.readmeService.updateNoteReadmesOnly(noteIndexesToUpdate)
+  }
+}

package/services/file-watcher/index.ts

@@ -0,0 +1,7 @@
+/**
+ * services/file-watcher/index.ts
+ *
+ * 文件监听层入口
+ */
+
+export { FileWatcherService } from './service'

package/services/file-watcher/internal.ts

@@ -0,0 +1,79 @@
+/**
+ * services/file-watcher/internal.ts
+ *
+ * 文件监听层内部模型：仅供 file-watcher 层使用
+ */
+
+import type { Logger } from '../../utils'
+
+/**
+ * 监听事件类型常量
+ */
+export const WATCH_EVENT_TYPES = {
+  README: 'readme',
+  CONFIG: 'config',
+} as const
+
+export type WatchEventType =
+  (typeof WATCH_EVENT_TYPES)[keyof typeof WATCH_EVENT_TYPES]
+
+/**
+ * 监听到的文件变更事件
+ *
+ * 示例：
+ *
+ * ```js
+ * {
+ *   path: 'C:\\tnotesjs\\TNotes.introduction\\notes\\0001. TNotes 简介\\README.md',
+ *   type: 'readme',
+ *   noteIndex: '0001',
+ *   noteDirName: '0001. TNotes 简介',
+ *   noteDirPath: 'C:\\tnotesjs\\TNotes.introduction\\notes\\0001. TNotes 简介'
+ * }
+ * ```
+ */
+export interface WatchEvent {
+  /**
+   * 笔记文件（README.md、.tnotes.json）的绝对路径
+   */
+  path: string
+  type: WatchEventType
+  noteIndex: string
+  noteDirName: string
+  noteDirPath: string
+  /**
+   * 文件夹重命名时的旧名称
+   */
+  oldNoteDirName?: string
+}
+
+export type ConfigSnapshot = {
+  done: boolean
+  enableDiscussions: boolean
+  description: string
+}
+
+/**
+ * 统一的异步错误处理辅助函数
+ *
+ * 用于包装可能抛出异常的异步操作，将错误统一通过 logger.error 输出，
+ * 避免各模块错误处理方式不一致（静默吞掉、格式各异等）。
+ *
+ * @param label 操作标签，用于错误日志前缀
+ * @param fn 需要执行的异步函数
+ * @param logger 日志记录器
+ * @returns true 表示执行成功，false 表示捕获到异常
+ */
+export async function safeExecute(
+  label: string,
+  fn: () => Promise<void>,
+  logger: Logger,
+): Promise<boolean> {
+  try {
+    await fn()
+    return true
+  } catch (error) {
+    logger.error(`[${label}] ${error}`)
+    return false
+  }
+}

package/services/file-watcher/readmeChangeHandler.ts

@@ -0,0 +1,28 @@
+/**
+ * services/file-watcher/readmeChangeHandler.ts
+ *
+ * README 变更处理
+ */
+
+import type { WatchEvent } from './internal'
+import type { NoteService } from '../note/service'
+
+interface ReadmeChangeHandlerConfig {
+  /** 笔记服务实例 */
+  noteService: NoteService
+}
+
+export class ReadmeChangeHandler {
+  constructor(private config: ReadmeChangeHandlerConfig) {}
+
+  async handle(events: WatchEvent[]): Promise<void> {
+    if (events.length === 0) return
+    const indexes = [...new Set(events.map((c) => c.noteIndex))]
+    for (const noteIndex of indexes) {
+      const noteInfo = this.config.noteService.getNoteByIndex(noteIndex)
+      if (noteInfo) {
+        await this.config.noteService.fixNoteTitle(noteInfo)
+      }
+    }
+  }
+}