@tnotesjs/core 0.2.0 → 0.2.2

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)
+      }
+    }
+  }
+}

package/services/file-watcher/renameDetector.ts

@@ -0,0 +1,120 @@
+/**
+ * services/file-watcher/renameDetector.ts
+ *
+ * 文件夹重命名/删除检测
+ */
+
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+import { NoteManager } from '../../core/NoteManager'
+
+import type { Logger } from '../../utils'
+
+const FOLDER_RENAME_DETECT_WINDOW_MS = 500
+
+interface RenameDetectorDeps {
+  /** 笔记目录路径 */
+  notesDir: string
+  /** 目录缓存操作 */
+  dirCache: {
+    has: (name: string) => boolean
+    add: (name: string) => void
+    delete: (name: string) => void
+  }
+  /** 日志记录器 */
+  logger: Logger
+}
+
+interface RenameDetectorCallbacks {
+  /** 笔记删除事件回调 */
+  onDelete: (oldName: string) => void
+  /** 笔记重命名事件回调 */
+  onRename: (oldName: string, newName: string) => void
+}
+
+interface RenameDetectorConfig
+  extends RenameDetectorDeps, RenameDetectorCallbacks {}
+
+export interface PendingRename {
+  oldName: string
+  time: number
+}
+
+export class RenameDetector {
+  /** 待处理的文件夹重命名 */
+  private pendingFolderRename: PendingRename | null = null
+
+  /** 文件夹重命名检测定时器 */
+  private folderRenameTimer: NodeJS.Timeout | null = null
+
+  constructor(private config: RenameDetectorConfig) {}
+
+  handleFsRename(folderName: string) {
+    const { notesDir, dirCache, logger, onDelete, onRename } = this.config
+
+    const folderPath = join(notesDir, folderName)
+    const folderExists = existsSync(folderPath)
+    const noteIndex = NoteManager.extractNoteIndex(folderName)
+    if (!noteIndex) {
+      logger.warn(`无法从文件夹名称提取笔记索引: ${folderName}`)
+      return
+    }
+
+    if (!folderExists) {
+      // 第一次收到“删除”，先假设是重命名的起点，延迟一段时间再决策
+      if (dirCache.has(folderName)) {
+        logger.info(`检测到文件夹删除/重命名: ${folderName}`)
+        this.pendingFolderRename = { oldName: folderName, time: Date.now() }
+        if (this.folderRenameTimer) clearTimeout(this.folderRenameTimer)
+        this.folderRenameTimer = setTimeout(() => {
+          if (this.pendingFolderRename) {
+            logger.warn(`检测到笔记删除: ${this.pendingFolderRename.oldName}`)
+            onDelete(this.pendingFolderRename.oldName)
+          }
+          this.pendingFolderRename = null
+          this.folderRenameTimer = null
+        }, FOLDER_RENAME_DETECT_WINDOW_MS)
+      }
+      return
+    }
+
+    // folder exists
+    if (!dirCache.has(folderName)) {
+      logger.info(`检测到文件夹创建/重命名: ${folderName}`)
+      if (
+        this.pendingFolderRename &&
+        Date.now() - this.pendingFolderRename.time <
+          FOLDER_RENAME_DETECT_WINDOW_MS
+      ) {
+        const oldName = this.pendingFolderRename.oldName
+        const oldNoteIndex = NoteManager.extractNoteIndex(oldName)
+        if (oldNoteIndex && oldNoteIndex === noteIndex) {
+          logger.info(`检测到文件夹重命名: ${oldName} → ${folderName}`)
+          if (this.folderRenameTimer) {
+            clearTimeout(this.folderRenameTimer)
+            this.folderRenameTimer = null
+          }
+          onRename(oldName, folderName)
+          this.pendingFolderRename = null
+        } else if (oldNoteIndex && oldNoteIndex !== noteIndex) {
+          logger.warn(`索引冲突，回退: ${oldName} -> ${folderName}`)
+        }
+      }
+
+      // 新文件夹：无论是否匹配 rename，都把目录缓存补上，必要时移除旧目录
+      dirCache.add(folderName)
+      if (this.pendingFolderRename) {
+        dirCache.delete(this.pendingFolderRename.oldName)
+      }
+    }
+  }
+
+  clearTimers() {
+    if (this.folderRenameTimer) {
+      clearTimeout(this.folderRenameTimer)
+      this.folderRenameTimer = null
+    }
+    this.pendingFolderRename = null
+  }
+}